Massive rework of documentation

8 files changed, 421 insertions, 212 deletions

diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
deleted file mode 100644
index c01b22f..0000000
--- a/doc/_templates/layout.html
+++ /dev/null
@@ -1,6 +0,0 @@
-{% extends "!layout.html" %}
-{% block relbaritems %}
-    <li style="margin-left: 20px">PyXB hosted on <a href="http://sourceforge.net/projects/pyxb"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=263147&amp;type=9"
-    width="80" height="15" alt="Get PyXB: Python XML Schema Bindings at SourceForge.net. Fast, secure and Free Open Source software downloads"/></a></li>
-    {{ super() }}
-{% endblock %}
diff --git a/doc/arch_namespaces.txt b/doc/arch_namespaces.txt
index 4b7664f..00fe95c 100644
--- a/doc/arch_namespaces.txt
+++ b/doc/arch_namespaces.txt
@@ -215,6 +215,8 @@ There are a variety of intricacies involved in this serialization; see the
 source code starting at :api:`pyxb.namespace.Namespace.saveToFile` for
 details.
 
+.. _namespace-archive:
+
 The Namespace Archive Model
 ---------------------------
 
diff --git a/doc/examples.txt b/doc/examples.txt
index 09d4330..99c7203 100644
--- a/doc/examples.txt
+++ b/doc/examples.txt
@@ -8,14 +8,14 @@ A detailed, albeit contrived, example of how to use PyXB is in
 :ref:`pyxbgen`.
 
 Multiple real-world XML and web service examples of varying complexity are
-provided in the examples subdirectory.  Some are WSDL services, and others
-are simply XMLSchema documents.  Generally, invoke :file:`genbindings.sh` to
-retrieve the source schema and perform the binding transformations.  Often
-there are a couple trivial programs that show how the bindings are used.  In
-that case, the script :file:`test.sh` can be used to generate the bindings
-and run the programs in a single step.
+provided in the examples subdirectories of the PyXB distribution and of the
+various bundles.  Some are WSDL services, and others are simply XMLSchema
+documents.  Often there are a couple trivial programs that show how the
+bindings are used.  The script :file:`test.sh` in each directory can be used
+to generate the bindings and run the programs in a single step.
 
-See the :file:`README.txt` file in each example subdirectory for more information.
+See the :file:`README.txt` file in each example subdirectory for more
+information.
 
 For ...
  - REST-style interactions, see :ref:`ex_dictionary`, :ref:`ex_ndfd`, and :ref:`thirty_sec_example`
@@ -50,13 +50,14 @@ Simple Weather (CDyne)
 
 A `free weather service <http://ws.cdyne.com/WeatherWS/Weather.asmx>`_.
 The REST interface was demonstrated as the :ref:`thirty_sec_example`.  A
-SOAP interface example is:
+SOAP interface example is in ``client.py``:
 
 .. literalinclude:: ../examples/weather/client.py
 
 Note the various misspellings in the schema (e.g., "Desciption").  Also, be
 aware that the weather information in this service does not get updated
-often, and sometimes fails to provide valid dates.
+often, and sometimes fails to provide valid dates.  Try various zip codes;
+usually you can find one that works.
 
 .. _ex_ndfd:
 
diff --git a/doc/index.txt b/doc/index.txt
index 729d11c..f7cb4f1 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -23,15 +23,20 @@ documents and Python instances.  In concept it is similar to `JAXB
 <http://www.codesynthesis.com/products/xsd/>`_ for C++.  A
 :ref:`thirty_sec_example` is at the bottom of this page.
 
-For downloads, support, etc. please see the `PyXB project page
-<http://sourceforge.net/projects/pyxb>`_ on SourceForge.  For a history of
-releases, see :ref:`releases`.
+Getting Help
+============
 
-** WARNING ** 0.7.x is a :ref:`BETA RELEASE<releases>`.  Documentation is not up
-to date.
+PyXB is distributed on `SourceForge <http://sourceforge.net/projects/pyxb>`_.
 
-** NEW ** Uses properties instead of accessor methods for binding element and
-   attribute fields.
+For support, consult the `Help Forum
+<https://sourceforge.net/forum/forum.php?forum_id=956708>`_, or subscribe to
+and email the `mailing list
+<https://sourceforge.net/mailarchive/forum.php?forum_name=pyxb-users>`_.
+
+To file a bug report or see the status of defects reported against the current
+release, visit the `Trac database <http://sourceforge.net/apps/trac/pyxb/>`_.
+
+For a history of releases, see :ref:`releases`.
 
 ********
 Contents
@@ -45,6 +50,7 @@ Contents
    architecture
    userref
    maintref
+   pyxbgen_cli
 
 .. _thirty_sec_example:
 
@@ -57,21 +63,16 @@ An example of a program using PyXB to interact with a `web service
 automatically-generated module.  First, retrieve the WSDL and generate the
 bindings::
 
- vmfed9[23]$ pyxbgen -W 'http://ws.cdyne.com/WeatherWS/Weather.asmx?wsdl' -m weather
- urn:uuid:1f774546-80b9-11de-afc9-000c292f797c
+ vmfed9[23]$ pyxbgen \
+   --wsdl-location="http://ws.cdyne.com/WeatherWS/Weather.asmx?wsdl" --module=weather \
+   --write-for-customization
+ urn:uuid:769983dc-8ecb-11de-b7e5-000c292f797c
  Retrieving WSDL from http://ws.cdyne.com/WeatherWS/Weather.asmx?wsdl
- Load MR[urn:uuid:bcbebe4e-80b2-11de-8f26-000c292f797c]@http://schemas.xmlsoap.org/wsdl/ from NSArchive@/home/pab/pyxb/dev/pyxb/standard/bindings/raw/wsdl.wxs
  Importing pyxb.binding.datatypes to get binding for wildcard {http://www.w3.org/2001/XMLSchema}schema
- WARNING: Unable to convert wildcard node {http://www.w3.org/2001/XMLSchema}schema to Python instance: 'module' object has no attribute 'CreateFromDOM'
  NOTE: Created unbound wildcard element from DOM node {http://www.w3.org/2001/XMLSchema}schema
- PS urn:uuid:1f774546-80b9-11de-afc9-000c292f797c
- Load MR[urn:uuid:bea57d24-80b2-11de-bd6b-000c292f797c]@http://schemas.xmlsoap.org/wsdl/http/ from NSArchive@/home/pab/pyxb/dev/pyxb/standard/bindings/raw/http.wxs
- Load MR[urn:uuid:bd932116-80b2-11de-97bf-000c292f797c]@http://schemas.xmlsoap.org/soap/encoding/ from NSArchive@/home/pab/pyxb/dev/pyxb/standard/bindings/raw/soapenc.wxs
- Load MR[urn:uuid:be060b2c-80b2-11de-b19d-000c292f797c]@http://schemas.xmlsoap.org/wsdl/mime/ from NSArchive@/home/pab/pyxb/dev/pyxb/standard/bindings/raw/mime.wxs
- Load MR[urn:uuid:beff4fe8-80b2-11de-ae43-000c292f797c]@http://schemas.xmlsoap.org/wsdl/soap12/ from NSArchive@/home/pab/pyxb/dev/pyxb/standard/bindings/raw/soap12.wxs
- Load MR[urn:uuid:be5fc0a4-80b2-11de-803a-000c292f797c]@http://schemas.xmlsoap.org/wsdl/soap/ from NSArchive@/home/pab/pyxb/dev/pyxb/standard/bindings/raw/soap.wxs
+ PS urn:uuid:769983dc-8ecb-11de-b7e5-000c292f797c
  Python for http://ws.cdyne.com/WeatherWS/ requires 1 modules
- Saved binding source to ./weather.py
+ Saved binding source to ./raw/weather.py
 
 Then write a program that uses them:
 
@@ -79,16 +80,16 @@ Then write a program that uses them:
 
 And run it::
 
- vmfed9[24]$ python client_get.py
+ vmfed9[64]$ python client_get.py 
  Weather forecast for Tucson, AZ:
-   Saturday, May 02 2009: Partly Cloudy, from  to 64
-   Sunday, May 03 2009: Sunny, from 43 to 66
-   Monday, May 04 2009: Partly Cloudy, from 45 to 69
-   Tuesday, May 05 2009: Mostly Cloudy, from 54 to 69
-   Wednesday, May 06 2009: Partly Cloudy, from 47 to 69
-   Thursday, May 07 2009: Mostly Cloudy, from 49 to 66
-   Friday, May 08 2009: Partly Cloudy, from 48 to 67
- vmfed9[25]$ 
+  Saturday, August 22 2009: Thunder Storms, from 80 to 90
+  Sunday, August 23 2009: Partly Cloudy, from 78 to 92
+  Monday, August 24 2009: Partly Cloudy, from 75 to 95
+  Tuesday, August 25 2009: Partly Cloudy, from 75 to 96
+  Wednesday, August 26 2009: Partly Cloudy, from 76 to 99
+  Thursday, August 27 2009: Sunny, from 77 to 99
+  Friday, August 28 2009: Sunny, from 77 to 100
+ vmfed9[65]$ 
 
 That's it.
 
diff --git a/doc/limitations.txt b/doc/limitations.txt
index 982b434..6a523c7 100644
--- a/doc/limitations.txt
+++ b/doc/limitations.txt
@@ -23,6 +23,10 @@ Things That Work
 
 * Namespace qualified attributes and elements
 
+* Documentation annotations present in the schema are converted to Python
+  docstrings in the generated bindings.
+
+
 
 Things That Don't Work
 ----------------------
@@ -32,11 +36,6 @@ Things That Don't Work
 
 * Pattern constraints don't do anything.
 
-* Prohibited attributes
-
-* Documentation present in the schema is not made available in the bindings
-  (viz., I want the annotations to become docstrings).
-
 * The ability to use templates to customize binding generation was promised
   in the vision document.  That has not yet been done, though it should be
   fairly straightforward.
@@ -75,10 +74,6 @@ Things That Don't Work
 Things That Mostly Work, But They're Ugly
 -----------------------------------------
 
-* Processing of include and import directives is a little too fragile.  In
-  particular, relative URIs in schemaLocation values probably won't be
-  resolvable.
-
 * The `duration <http://www.w3.org/TR/xmlschema-2/#duration>`_ type is based
   on the Python ``datetime.timedelta`` class, which works reasonably well
   for small deltas but does not handle month and year deltas.  The PyXB
@@ -90,6 +85,5 @@ Things That Mostly Work, But They're Ugly
 Intended Near-Term Enhancements
 -------------------------------
 
-* Customized WSDL support to work around inconsistencies in the SOAP
-  encoding handling of schema, and lack of bindings for defined messages.
+* Any requests?
 
diff --git a/doc/overview_how.txt b/doc/overview_how.txt
index e7eeb53..6d334ef 100644
--- a/doc/overview_how.txt
+++ b/doc/overview_how.txt
@@ -1,10 +1,6 @@
 How to use it
 =============
 
-The current release of PyXB is 0.2.0, the first public release.  Early
-adopters are asked to be patient as installation and operation problems are
-worked out.
-
 Installation
 ------------
 
@@ -40,11 +36,8 @@ Python data bindings.  There are two key components to generating bindings:
 - The module path into which the binding will be installed.  This is the
   path that users of the binding will import.
 
-There are additional parameters; for a full description of the utility see
-:ref:`pyxbgen`.  An example of translating the schema for WSDL documents is::
-
- pyxbgen --module-path pyxb.standard.bindings.wsdl \
-    --schema-uri http://schemas.xmlsoap.org/wsdl/
+There are many additional parameters; see :ref:`pyxbgen` and
+:ref:`pyxbgen-cli`.
 
 WSDL Functions
 --------------
@@ -72,9 +65,10 @@ operations and parameters.  For example::
         Input: typens:doGoogleSearch
         Output: typens:doGoogleSearchResponse
 
-In the future, this script is expected to provide more powerful display of
-available services, and perhaps to generate functions which interact with the
-service using the appropriate encoding.
+Currently, this is an unmaintained example.  In the future, this script may
+provide a more powerful display of available services, and perhaps support for
+generating functions which interact with the service using the appropriate
+encoding.
 
 .. ignored
    ## Local Variables:
diff --git a/doc/overview_what.txt b/doc/overview_what.txt
index 5846238..c99d2b9 100644
--- a/doc/overview_what.txt
+++ b/doc/overview_what.txt
@@ -34,48 +34,138 @@ The major goals of PyXB are:
 Secondary goals, some of which have been achieved in the current release, are
 listed in :ref:`pyxb_vision`.
 
-Examples of Processable Schema
-------------------------------
-
-PyXB can parse the following namespaces and create bindings for them (though
-not all have been rigorously tested).  For examples of how to use PyXB with
-schemas like these, see :ref:`examples`.
-
-* The `National Digital Forecast Database <http://www.nws.noaa.gov/ndfd/>`_
-
-::
-
-  http://www.weather.gov/forecasts/xml/DWMLgen/schema/DWML.xsd
-
-* `SOAP infrastructure <http://www.w3.org/TR/soap/>`_
-
-::
-
-  http://schemas.xmlsoap.org/soap/envelope/
-  http://schemas.xmlsoap.org/soap/encoding/
-  http://schemas.xmlsoap.org/wsdl/soap12/
-
-* `Web Services Description Language <http://www.w3.org/TR/wsdl>`_
-
-::
-
-  http://schemas.xmlsoap.org/wsdl/
-  http://schemas.xmlsoap.org/wsdl/mime/
-  http://schemas.xmlsoap.org/wsdl/soap/
-  http://schemas.xmlsoap.org/wsdl/http/
-
-* `Keyhole Markup Language <http://code.google.com/apis/kml/>`_ (v 2.1)
-
-::
-
-  http://code.google.com/apis/kml/schema/kml21.xsd
-
-* Others (parsed only, no testing)
-
-::
-
-  http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd
-  http://www.w3.org/TR/2002/REC-xmlenc-core-20021210/xenc-schema.xsd
-  http://docs.oasis-open.org/security/saml/v2.0/saml-schema-assertion-2.0.xsd
-  http://docs.oasis-open.org/security/saml/v2.0/saml-schema-protocol-2.0.xsd
+Examples of Supported Schema
+----------------------------
+
+PyXB comes with pre-defined *bundles* which aggregate related namespaces
+into pre-generated bindings that allow you to use them without having to
+generate and manage them yourself.  These bundles also demonstrate the
+complexity of schema that PyXB is prepared to handle.  Not all namespaces
+have been fully tested, but they are expected to function correctly.
+
+WS-*
+^^^^
+
+The following namespaces are available in support of web service
+development:
+
+.. PYXB_ARCHIVE_PATH=/home/pab/pyxb/dev/pyxb/bundles/wssplat// pyxbdump \
+   | grep wssplat \
+   | tr '\011' ' ' \
+   | sed -e 's@^\([^ ]*\) \([^ ]*\).*$@``\2`` ``\1``@g' \
+   | tr ' ' '\011' \
+   | expand -40 \
+   | sort \
+   > /tmp/x
+
+=====================================   ==========================================================
+Binding Module                          Namespace
+=====================================   ==========================================================
+``pyxb.bundles.wssplat.bpws``           ``http://schemas.xmlsoap.org/ws/2003/03/business-process/``
+``pyxb.bundles.wssplat.ds``             ``http://www.w3.org/2000/09/xmldsig#``
+``pyxb.bundles.wssplat.httpbind``       ``http://schemas.xmlsoap.org/wsdl/http/``
+``pyxb.bundles.wssplat.mimebind``       ``http://schemas.xmlsoap.org/wsdl/mime/``
+``pyxb.bundles.wssplat.soap11``         ``http://schemas.xmlsoap.org/soap/envelope/``
+``pyxb.bundles.wssplat.soap12``         ``http://www.w3.org/2003/05/soap-envelope``
+``pyxb.bundles.wssplat.soapbind11``     ``http://schemas.xmlsoap.org/wsdl/soap/``
+``pyxb.bundles.wssplat.soapbind12``     ``http://schemas.xmlsoap.org/wsdl/soap12/``
+``pyxb.bundles.wssplat.soapenc``        ``http://schemas.xmlsoap.org/soap/encoding/``
+``pyxb.bundles.wssplat.whttp``          ``http://www.w3.org/ns/wsdl/http``
+``pyxb.bundles.wssplat.wsa``            ``http://www.w3.org/2005/08/addressing``
+``pyxb.bundles.wssplat.wsam``           ``http://www.w3.org/2007/02/addressing/metadata``
+``pyxb.bundles.wssplat.wscoor``         ``http://docs.oasis-open.org/ws-tx/wscoor/2006/06``
+``pyxb.bundles.wssplat.wsdl11``         ``http://schemas.xmlsoap.org/wsdl/``
+``pyxb.bundles.wssplat.wsdl20``         ``http://www.w3.org/ns/wsdl``
+``pyxb.bundles.wssplat.wsdli``          ``http://www.w3.org/ns/wsdl-instance``
+``pyxb.bundles.wssplat.wsdlx``          ``http://www.w3.org/ns/wsdl-extensions``
+``pyxb.bundles.wssplat.wsoap``          ``http://www.w3.org/ns/wsdl/soap``
+``pyxb.bundles.wssplat.wsp200607``      ``http://www.w3.org/2006/07/ws-policy``
+``pyxb.bundles.wssplat.wsp``            ``http://www.w3.org/ns/ws-policy``
+``pyxb.bundles.wssplat.wsrm``           ``http://docs.oasis-open.org/ws-rx/wsrm/200702``
+``pyxb.bundles.wssplat.wsse``           ``http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd``
+``pyxb.bundles.wssplat.wsu``            ``http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd``
+=====================================   ==========================================================
+
+OpenGIS
+^^^^^^^
+
+The following namespaces are available in support of `Open Geospatial
+Consortium <http://www.opengeospatial.org/standards>`_ Geographic
+Information System processing.  Note that several of these namespaces are
+"private" bindings generated because the OGC definitions include their own
+schema.  The modules corresponding to these namespace uses begin with an
+underscore, and should generally not be used in other contexts.
+
+.. PYXB_ARCHIVE_PATH=/home/pab/pyxb/dev/pyxb/bundles/opengis// pyxbdump \
+   | grep opengis \
+   | tr '\011' ' ' \
+   | sed -e 's@^\([^ ]*\) \([^ ]*\).*$@``\2`` ``\1``@g' \
+   | tr ' ' '\011' \
+   | expand -50 \
+   | sort \
+   > /tmp/x
+
+================================================  ==========================================================
+Binding Module                                    Namespace
+================================================  ==========================================================
+``pyxb.bundles.opengis._atom``                    ``http://www.w3.org/2005/Atom``
+``pyxb.bundles.opengis._dc``                      ``http://purl.org/dc/elements/1.1/``
+``pyxb.bundles.opengis._dct``                     ``http://purl.org/dc/terms/``
+``pyxb.bundles.opengis._ogc``                     ``http://www.opengis.net/ogc``
+``pyxb.bundles.opengis._smil20``                  ``http://www.w3.org/2001/SMIL20/``
+``pyxb.bundles.opengis._smil20lang``              ``http://www.w3.org/2001/SMIL20/Language``
+``pyxb.bundles.opengis.citygml.appearance``       ``http://www.opengis.net/citygml/appearance/1.0``
+``pyxb.bundles.opengis.citygml.base``             ``http://www.opengis.net/citygml/1.0``
+``pyxb.bundles.opengis.citygml.building``         ``http://www.opengis.net/citygml/building/1.0``
+``pyxb.bundles.opengis.citygml.cityFurniture``    ``http://www.opengis.net/citygml/cityfurniture/1.0``
+``pyxb.bundles.opengis.citygml.cityObjectGroup``  ``http://www.opengis.net/citygml/cityobjectgroup/1.0``
+``pyxb.bundles.opengis.citygml.generics``         ``http://www.opengis.net/citygml/generics/1.0``
+``pyxb.bundles.opengis.citygml.landUse``          ``http://www.opengis.net/citygml/landuse/1.0``
+``pyxb.bundles.opengis.citygml.relief``           ``http://www.opengis.net/citygml/relief/1.0``
+``pyxb.bundles.opengis.citygml.texturedSurface``  ``http://www.opengis.net/citygml/texturedsurface/1.0``
+``pyxb.bundles.opengis.citygml.transportation``   ``http://www.opengis.net/citygml/transportation/1.0``
+``pyxb.bundles.opengis.citygml.vegetation``       ``http://www.opengis.net/citygml/vegetation/1.0``
+``pyxb.bundles.opengis.citygml.waterBody``        ``http://www.opengis.net/citygml/waterbody/1.0``
+``pyxb.bundles.opengis.csw_2_0_2``                ``http://www.opengis.net/cat/csw/2.0.2``
+``pyxb.bundles.opengis.filter``                   ``http://www.opengis.net/ogc``
+``pyxb.bundles.opengis.gml_3_2``                  ``http://www.opengis.net/gml/3.2``
+``pyxb.bundles.opengis.gml``                      ``http://www.opengis.net/gml``
+``pyxb.bundles.opengis.gmlsf``                    ``http://www.opengis.net/gmlsf``
+``pyxb.bundles.opengis.gmx``                      ``http://www.isotc211.org/2005/gmx``
+``pyxb.bundles.opengis.ic_ism_2_1``               ``urn:us:gov:ic:ism:v2``
+``pyxb.bundles.opengis.iso19139.gco``             ``http://www.isotc211.org/2005/gco``
+``pyxb.bundles.opengis.iso19139.gmd``             ``http://www.isotc211.org/2005/gmd``
+``pyxb.bundles.opengis.iso19139.gsr``             ``http://www.isotc211.org/2005/gsr``
+``pyxb.bundles.opengis.iso19139.gss``             ``http://www.isotc211.org/2005/gss``
+``pyxb.bundles.opengis.iso19139.gts``             ``http://www.isotc211.org/2005/gts``
+``pyxb.bundles.opengis.misc.xAL``                 ``urn:oasis:names:tc:ciq:xsdschema:xAL:2.0``
+``pyxb.bundles.opengis.misc.xlinks``              ``http://www.w3.org/1999/xlink``
+``pyxb.bundles.opengis.ogckml22``                 ``http://www.opengis.net/kml/2.2``
+``pyxb.bundles.opengis.om_1_0``                   ``http://www.opengis.net/om/1.0``
+``pyxb.bundles.opengis.ows_1_1``                  ``http://www.opengis.net/ows/1.1``
+``pyxb.bundles.opengis.ows``                      ``http://www.opengis.net/ows``
+``pyxb.bundles.opengis.sampling_1_0``             ``http://www.opengis.net/sampling/1.0``
+``pyxb.bundles.opengis.sensorML_1_0_1``           ``http://www.opengis.net/sensorML/1.0.1``
+``pyxb.bundles.opengis.sos_1_0``                  ``http://www.opengis.net/sos/1.0``
+``pyxb.bundles.opengis.swe_1_0_0``                ``http://www.opengis.net/swe/1.0``
+``pyxb.bundles.opengis.swe_1_0_1``                ``http://www.opengis.net/swe/1.0.1``
+``pyxb.bundles.opengis.tml``                      ``http://www.opengis.net/tml``
+``pyxb.bundles.opengis.wcs_1_1``                  ``http://www.opengis.net/wcs/1.1``
+``pyxb.bundles.opengis.wfs``                      ``http://www.opengis.net/wfs``
+================================================  ==========================================================
+
+Generating Bundled Bindings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Due to the size of the generated code, bundles are not incorporated into the
+core distribution of PyXB.  To create the support infrastructure for a
+particular bundle, run the ``scripts/genbind`` script in the bundle root.
+For example::
+
+  cd ${PYXB_ROOT}
+  pyxb/bundles/wssplat/scripts/genbind
+
+will invoke the :manpage:`wget(1)` program to retrieve the XML schema for a
+variety of namespaces related to web services, and generate bindings and
+archive files for them.
 
diff --git a/doc/userref.txt b/doc/userref.txt
index 83f8161..a1c78c7 100644
--- a/doc/userref.txt
+++ b/doc/userref.txt
@@ -4,28 +4,8 @@ User Reference
 
 .. _pyxbgen:
 
-Creating bindings with ``pyxbgen``
-==================================
-
-.. toctree::
-   :hidden:
-
-   pyxbgen_cli
-
-.. include:: pyxbgen_cli.txt
-
-** THESE EXAMPLES ARE NOT UP TO DATE.  SEE `examples/ndfd/genbindings.sh`
-and `examples/openGIS/makebind.sh` **
-
-The module path and schema URI are required.  Raw bindings allow the user to
-import the module and obtain :ref:`customized classes
-<binding_customization>` that augment the pure data with functionality or
-additional data.  Optionally, the XML document retrieved from the URI can be
-stored into a local file for review (usually important when working with
-WSDL definitions).  If the XML document is a WSDL definition, only the
-``types`` portion is extracted.  Last, the component model must be saved if
-the subsequent bindings are to be generated for namespaces that refer to
-defined objects in this namespace.
+Generating Binding Classes
+==========================
 
 The following sections reference example schema and programs that are
 available in the ``examples/manual`` subdirectory of the PyXB distribution.
@@ -39,11 +19,20 @@ Primer:
 
 .. literalinclude:: ../examples/manual/po1.xsd
 
-Translate this into Python with the following command::
+Translate this into Python with the following command:
+
+.. literalinclude:: ../examples/manual/demo1.sh
 
-  pyxbgen -u po1.xsd  -m po1
+The :ref:`-u<pyxbgen--schema-location>` parameter identifies a schema
+document describing contents of a namespace.  The parameter may be a path to
+a file on the local system, or a URL to a network-accessible location like
+http://www.weather.gov/forecasts/xml/DWMLgen/schema/DWML.xsd.  The
+:ref:`-m<pyxbgen--module>` parameter specifies the name to be used by the
+Python module holding the bindings generated for the namespace in the
+preceding schema.  After running this, the Pythong bindings will be in a
+file named ``po1.py``.
 
-Then this program (``demo1.py``):
+With the bindings available, this program (``demo1.py``):
 
 .. literalinclude:: ../examples/manual/demo1.py
 
@@ -51,19 +40,17 @@ processing this document:
 
 .. literalinclude:: ../examples/manual/po1.xml
 
-produces the following output::
+produces the following output:
 
- Robert Smith is sending Alice Smith 2 thing(s):
-   Quantity 1 of Lapis necklace at $99.95
-   Quantity 4 of Plastic necklace at $3.95
+.. literalinclude:: ../examples/manual/demo1.out
 
 Multi-document schema
 ---------------------
 
 Complex schema are more easy to manage when they are separated into multiple
 documents, each of which contains a cohesive set of types.  In the example
-above, the USAddress can be abstracted to handle a variety of addresses, and
-maintained as its own document ``address.xsd``:
+above, the ``USAddress`` type can be abstracted to handle a variety of
+addresses, and maintained as its own document ``address.xsd``:
 
 .. literalinclude:: ../examples/manual/address.xsd
 
@@ -74,82 +61,228 @@ incorporate this document into ``po2.xsd``:
 .. literalinclude:: ../examples/manual/po2.xsd
 
 Translation of this document and execution of the test program is just as it
-was in the previous section.
-
-Multi-namespace documents
--------------------------
-
-Documents of significant complexity are likely to require references to
-multiple namespaces.  You may have noticed that the schemas we've looked at
-so far have :ref:`no namespace <absentNamespaces>` for both their target and
-default namespaces.  The following schema ``nsaddress.xsd`` places the types
-that are in ``address.xsd`` into the namespace ``URN:address``:
-
-.. literalinclude:: ../examples/manual/nsaddress.xsd
-
-This schema can be translated into its own Python binding module with the
-following command::
+was in the previous section:
 
-  pyxbgen -u nsaddress.xsd -m address -C
+.. literalinclude:: ../examples/manual/demo2.sh
 
-Note that the ``-C`` or ``--save-component-model`` option was given this
-time.  This causes a file ``address.wxs`` to be written which contains a
-:ref:`stored namespace <namespaceStorage>` with all the types and elements
-defined in ``address.xsd`` available for lookup when :ref:`resolving
-<resolution>` names in the ``URN:address`` namespace.
+Note that you do not need to explicitly list the ``address.xsd`` file.  PyXB
+detects the ``include`` directive and reads the second schema by resolving
+its ``schemaLocation`` relative to the base URI of the containing document.
+Because the contents of the two schema files belong to the same namespace,
+their combined bindings are placed into the ``po2.py`` module.
 
-The following schema references the address information through a namespace
-declaration:
-
-.. literalinclude:: ../examples/manual/po3.xsd
-
-and can be translated with the standard command.  As with the previous
-purchase order schemas, we don't need to save the component model here since
-we won't be referencing it.  However, we do have to set an environment
-variable that tells ``pyxbgen`` where to find the stored ``URN:address``
-namespace::
-
-  export PYXB_NAMESPACE_PATH=+:.
-  pyxbgen -u po3.xsd -m po3
-
-The ``PYXB_NAMESPACE_PATH`` environment variable is a colon-separated set of
-directories.  Upon startup, the :api:`pyxb.namespace` module walks all the
-specified directories looking for files that end with ``.wxs``.  Any that it
-finds that it can correctly read are recorded, and namespaces created, so
-that if they are referenced in a schema the namespace contents can be
-retrieved.  The value ``+`` in the path refers to the default binding path,
-which is normally ``pyxb/standard/bindings/raw`` in your installation area.
-
-If you examine the top of the generated ``po3.py`` file, you'll see that
-``pyxbgen`` inserted a Python ``import`` statement so that the
-``address:USAddress`` type can be referenced in the purchase order::
-
-  # Import bindings for namespaces imported into schema
-  import address
-
-The name of the module to import was retrieved from the ``address.wxs``
-file.
-
-Note that if you wish only to refer to types in a different namespace, it is
-sufficient to provide the namespace declaration in the schema, and to have a
-stored namespace along with the generated binding accessible to ``pyxbgen``.
-If you wish to extend one of the types from the namespace, you must use the
-XMLSchema `import directive
-<http://www.w3.org/TR/xmlschema-1/#composition-schemaImport>`_.  A fourth
-example showing this is also available in the ``examples/manual``
-subdirectory.
-
-** THIS SECTION HAS NOT BEEN UPDATED FOR 0.5.0.  RUN ``pyxbgen`` WITH NO
-ARGUMENTS TO SEE NEW INTERFACE.  ALSO SEE `examples/ndfd/genbindings.sh`
-and `examples/openGIS/makebind.sh` **
+Working with Namespaces
+-----------------------
 
+Documents of significant complexity are likely to require references to
+multiple namespaces.  Notice that the schemas we've looked at so far have
+:ref:`no namespace <absentNamespaces>` for both their target and default
+namespaces.  The following schema ``nsaddress.xsd`` places the types that
+are in ``address.xsd`` into the namespace ``URN:address`` by defining a
+`target namespace
+<http://www/Documentation/W3C/www.w3.org/TR/xmlschema-0/index.html#QualLocals>`_
+along with a namespace declaration that associates it with the QName
+references to types defined in that namespace:
 
-Customized bindings
-===================
+.. literalinclude:: ../examples/manual/nsaddress.xsd
 
-To customize bindings, you need to be familiar with the
-:api:`pyxb.binding.basis._DynamicCreate_mixin` class.  One readily-available
-example is :ref:`ex_tmsxtvd`.  A more complex example is the customized
-standard binding for WSDL, available in
-:file:`pyxb/standard/bindings/wsdl.py`.
+There are several ways you can prepare to process documents with multiple
+namespaces.  If you have no expectation of using the imported namespace
+directly, you can process the importing schema just as before:
+
+.. literalinclude:: ../examples/manual/demo3a.sh
+
+PyXB will detect the ``import`` statement, read the corresponding schema,
+and create bindings for its types.  However, since the ``pyxbgen``
+invocation did not mention the ``URN:address`` namespace, the bindings are
+written into a :ref:`private <pyxbgen--private-namespace>` binding file.
+The generated module file ``_address.py`` is created with a prefixed
+underscore indicating that it is not expected to be referenced directly.
+The public module ``po3.py`` will locally import module ``_address`` so that
+the required classes are available, but will not expose them to code that
+imports only module ``po3``.  The demonstration program ``demo3.py`` shows
+that things work as expected without the new namespace being made explicit.
+
+.. literalinclude:: ../examples/manual/demo3.py
+
+More often, you will want to be able to import the module defining bindings
+from the additional namespaces.  To do this, explicitly reference the
+additional schema and provide it with a module name:
+
+.. literalinclude:: ../examples/manual/demo3b.sh
+
+Here each namespace is represented in its own module (``address`` for
+``URN:address`` and ``po3`` for module with an absent namespace).  In this
+case, the demonstration program is unchanged; see `Creating Instances in
+Python Code`_ for additional examples.
+
+Sharing Namespace Bindings
+--------------------------
+
+Most often, if you have a common utility namespace like ``URN:address``, you
+will want to generate its bindings once, and reference them in other schema
+without regenerating them.  To do this, PyXB must be provided with an
+archive containing the schema components that were defined in that
+namespace, so they can be referenced in independent generation activities.
+
+To generate the archive, you add the :ref:`pyxbgen--archive-to-file`
+flag to the binding generation command:
+
+.. literalinclude:: ../examples/manual/demo3c.sh
+
+In addition to generating the ``addresss`` Python module, this causes a
+:ref:`archive <namespace-archive>` of the schema contents to be saved in the
+corresponding file, which by convention ends with the extension ``.wxs``.
+Any anonymous names that were generated with the bindings are also recorded
+in this archive, so that cross-namespace extension works correctly.
+
+You can then generate bindings for importing namespaces by providing PyXB
+with the information necessary to locate this archive:
+
+.. literalinclude:: ../examples/manual/demo3d.sh
+
+The :ref:`pyxbgen--archive-path` directive indicates that the current
+directory (``.``) should be searched for files that end in ``.wxs``, and any
+namespaces found in such files implicitly made available for reference when
+they are encountered in an ``import`` instruction.  (The second path
+component ``+`` causes the standard search path to be used after searching
+the current directory.)
+
+In this case, when the ``import`` instruction is encountered, PyXB detects
+that it has an archive ``address.wxs`` that defines the contents of the
+imported namespace.  Instead of reading and processing the schema, it
+generates references to the existing binding modules.  Again, the
+demonstration program is unchanged.
+
+Advanced Topics
+---------------
+
+Schemas Defined in WSDL Documents
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is a common, if regrettable, practice that web services define the
+structure of their documents using XML schema stanzas encoded directly into
+``types`` stanzas of WSDL specifications rather than having those stanzas
+import complete standalone schema.  To accommodate this, pyxbgen supports
+the :ref:`pyxbgen--wsdl-location` argument as an alternative to
+:ref:`pyxbgen--schema-location`.  For example, the following will generate a
+module ``ndfd`` containing bindings required to communicate with the
+`National Digital Forecast Database <http://www.nws.noaa.gov/xml>`_::
+
+  pyxbgen \
+   --wsdl-location=http://www.weather.gov/forecasts/xml/DWMLgen/wsdl/ndfdXML.wsdl --module=ndfd
+
+Customizing Binding Classes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+PyXB permits you to customize the bindings that it generates by creating a
+module that imports the generated classes and instances, then extends them
+with subclasses with additional behavior.  As long as you do not make major
+changes to the structure and names used in your namespaces, you can
+fine-tune the schema without changing the custom code.
+
+The :ref:`pyxbgen--write-for-customization` option causes PyXB to generate
+all the Python modules in a subdirectory ``raw``.  Then you write a module
+that imports the generated bindings and extends them.
+
+Until this documentation is enhanced significantly, users interested in
+generating custom bindings are referred to the extensions for WSDL 1.1 that
+are provided in the WS-* support bundle as
+``pyxb.bundles.wssplat.wsdl11.py``.  An excerpt of the sort of thing done
+there is::
+
+  from pyxb.bundles.wssplat.raw.wsdl11 import *
+  import pyxb.bundles.wssplat.raw.wsdl11 as raw_wsdl11
+
+  class tParam (raw_wsdl11.tParam):
+    def __getMessageReference (self):
+        return self.__messageReference
+    def _setMessageReference (self, message_reference):
+        self.__messageReference = message_reference
+    __messageReference = None
+    messageReference = property(__getMessageReference)
+  raw_wsdl11.tParam._SetSupersedingClass(tParam)
+
+The first line brings in all the public identifiers from the generated
+binding.  The second makes them available in a qualified form that ensures
+we use the generated value rather than the customized value.
+
+The class definition shows how to extend the generated bindings for the
+``tParam`` complex type so that it has a field that can hold the instance
+of ``tMessage`` that was identified by the ``message`` attribute in an
+``operation`` stanza.  Following the class is a directive that tells PyXB to
+create instances of the customized class when automatically generating
+``tParam`` instances from XML documents.
+
+To customize bindings, you will need to be familiar with the
+:api:`pyxb.binding.basis._DynamicCreate_mixin` class.
+
+Generating Related Namespaces
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :ref:`pyxbgen--module-prefix` option permits you to add a fixed prefix
+to the generated modules.  For example, when generating bindings for the
+OpenGIS schemas it is desirable to aggregate them into a Python module
+hierarchy so the imported name incorporates the namespace collection::
+
+ pyxbgen \
+   --schema-location=${SCHEMA_DIR}/gml/3.2.1/gml.xsd --module=gml_3_2 \
+   --schema-location=${SCHEMA_DIR}/iso/19139/20070417/gmd/gmd.xsd --module=iso19139.gmd \
+   --schema-location=${SCHEMA_DIR}/iso/19139/20070417/gts/gts.xsd --module=iso19139.gts \
+   --schema-location=${SCHEMA_DIR}/iso/19139/20070417/gsr/gsr.xsd --module=iso19139.gsr \
+   --schema-location=${SCHEMA_DIR}/iso/19139/20070417/gss/gss.xsd --module=iso19139.gss \
+   --schema-location=${SCHEMA_DIR}/iso/19139/20070417/gco/gco.xsd --module=iso19139.gco \
+   --module-prefix=opengis \
+   --archive-to-file=opengis/iso19139.core.wxs
+
+When generated this way, your Python code imports these modules with
+directives like::
+
+  import opengis.gml_3_2 as gml
+  import opengis.iso19139.gmd
+
+PyXB comes with pre-defined bundles for related namespaces in the
+``pyxb.bundles`` module hierarchy.
+
+Fine-Grained Namespace Control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For example, when generating the bindings for the OpenGIS `Sensor
+Observation Service <http://www.opengeospatial.org/standards/sos>`_, you
+would find that this service extends the ``http://www.opengis.net/ogc``
+namespace, normally defined in the OpenGIS `Filter Encoding
+<http://www.opengeospatial.org/standards/filter>`_ with temporal operators
+that are defined in a local schema ``ogc4sos.xsd``.
+
+Because ``http://www.opengis.net/ogc`` is defined in a namespace archive,
+PyXB would normally assume that any ``import`` commands related to that
+namespace are redundant with the contents of that archive.  In this case,
+that is not the case, and the ``ogc4sos.xsd`` schema must be read to define
+the additional elements and types.  The required build command is::
+
+  pyxbgen \
+    --schema-location=${SCHEMA_DIR}/sos/1.0.0/sosAll.xsd --module sos_1_0 \
+    --archive-path=${ARCHIVE_DIR} \
+    --pre-load-archive=${ARCHIVE_DIR}/filter.wxs
+
+The :ref:`pyxbgen--pre-load-archive` directive causes PyXB to read the
+contents of that archive into its active database prior to processing any
+schema.  Consequently, when reference to the ``ogc4sos.xsd`` schema is
+encountered, PyXB detects that, although it already has definitions for
+components in that namespace, this particular schema has not yet been read.
+PyXB reads the additional components, and generates bindings for the
+additional material into a private module ``_ogc`` which is then imported
+into the ``sos_1_0`` module.
+
+Using Binding Classes
+=====================
+
+Creating Instances from XML Documents
+-------------------------------------
+
+Creating Instances in Python Code
+---------------------------------
+
+Creating XML Documents from Binding Instances
+---------------------------------------------