New documentation directory.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_4_BRANCH@20357 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

wxPython/docs/wxPackage.txt

@@ -0,0 +1,144 @@
+=========================
+ The wxPython wx Package
+=========================
+
+--------------------------------------------------
+ Or, how to survive the new wx namespace changes.
+--------------------------------------------------
+
+:Author: Patrick K. O'Brien
+:Contact: pobrien@orbtech.com
+:Date: $Date$
+:Revision: $Revision$
+
+.. contents::
+
+
+.. Add a link to wxExamples.html
+
+
+
+Introduction
+============
+
+Big things sometimes come in small packages.  This is certainly true
+of the new wx package, which is being introduced as a transition to
+allow the "wx" prefix to be dropped from the names of all wxPython
+classes, functions, and constants.
+
+
+Why change anything?
+====================
+
+This change is being made for a couple of reasons.  The first reason
+is to discourage the use of ``import *``, which is a dangerous
+technique that can create name conflicts and bloated namespaces.
+
+The second reason is to remove what some perceive to be a "wart."  For
+example, the following code is rather ugly in that the "wx" prefix on
+the wxFrame class name is no longer useful when you're using the wx
+module prefix::
+
+    from wxPython import wx
+
+    class Frame(wx.wxFrame)
+
+The new wx package allows you to write code like this, instead::
+
+    import wx
+
+    class Frame(wx.Frame)
+
+The third reason is that the wxWindows project intends to do the same
+thing (implement a new wx namespace and drop the "wx" prefix) and we
+want wxPython to lead the way.
+
+
+What does the new wx package do?
+================================
+
+As a way of getting to this new syntax as quickly as possible, the
+code in this new wx package was created.  What it does is alter the
+existing wx namespace dynamically.  By making the changes on-the-fly
+at runtime, we can try out the new syntax before any permanent changes
+are made to the underlying class library.  The downside of making
+these changes at runtime is that there is a slight delay when you
+``import wx``; the upside is that you can start using the new syntax
+now.
+
+
+Will any of this effect my existing code?
+=========================================
+
+No.  Your existing code will continue to work and be supported for
+some time.  It will be up to you to decide when to switch to the new
+syntax.  But all new documentation and code examples will use the new
+syntax.  So don't wait too long.  You wouldn't want anyone calling you
+old-fashioned, would you?
+
+
+How does the new wx package work?
+=================================
+
+It's pretty simple, and pretty clever.  The wx directory contains an
+``__init__.py`` file, making it a Python package.  (In contrast, the
+old wxPython.wx module is a module, not a package.)  When you ``import
+wx`` the code in the ``__init__.py`` file is executed, and that's
+where all the magic takes place.  Let's take a look at the code inside
+the ``__init__.py`` file:
+
+.. include:: ../wx/__init__.py
+   :literal:
+
+Namespaces in Python are implemented as dictionaries.  The dictionary
+used to create the wx package's namespace is accessible using the
+``globals()`` function.  The dictionary used to create the old
+wxPython.wx module's namespace is ``wx.__dict__``.  Once we have these
+two dictionaries, it's a simple matter of iterating through one,
+changing the names, adding the renamed object to the other dictionary,
+and cleaning up a few local variables and imported modules.  Voila!
+
+
+What about all the other modules, like grid, html, and stc?
+===========================================================
+
+There's more to wxPython than just the wx namespace.  And we've got
+those extra modules covered as well.  For each of those modules (as
+well as the lib package) we've got matching modules in the new wx
+package.  Let's take a look at a few of them.
+
+Here is ``html.py``:
+
+.. include:: ../wx/html.py
+   :literal:
+
+And here is ``lib/dialogs.py``:
+
+.. include:: ../wx/lib/dialogs.py
+   :literal:
+
+As you can see, they both rely on the ``prefix.rename()`` function
+defined in ``prefix.py``:
+
+.. include:: ../wx/prefix.py
+   :literal:
+
+Again, the technique is very similar to the one used by the wx
+package.
+
+
+How do I use it?
+================
+
+The wx package is created when you install wxPython.  So you can start
+using it now.  Examples are included in the wx/examples directory,
+which includes an examples.txt documentation file.  Here is the source
+code for ``hello.py``, a simple program that displays a wxPython
+graphic inside a frame:
+
+.. include:: ../samples/wx_examples/hello/hello.py
+   :literal:
+
+Good luck.  I hope you like the new wx package as much as I do.
+
+Pat