imported

lib/python/third_party/docutils/BUGS.txt

+================
+ Docutils_ Bugs
+================
+
+:Author: David Goodger; open to all Docutils developers
+:Contact: goodger@python.org
+:Date: $Date: 2004/10/29 19:08:15 $
+:Revision: $Revision: 1.1.4.1 $
+:Copyright: This document has been placed in the public domain.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+
+Bugs in Docutils?!?  Yes, we do have a few.  Some are old-timers that
+tend to stay in the shadows and don't bother anybody.  Once in a while
+new bugs are born.  From time to time some bugs (new and old) crawl
+out into the light and must be dealt with.  Icky.
+
+This document describes how to report a bug, and lists known bugs.
+
+.. contents::
+
+
+How To Report A Bug
+===================
+
+If you think you've discovered a bug, please read through these
+guidelines before reporting it.
+
+First, make sure it's a new bug:
+
+* Please check the list of `known bugs`_ below and the `SourceForge
+  Bug Tracker`_ to see if it has already been reported.
+
+* Are you using the very latest version of Docutils?  The bug may have
+  already been fixed.  Please get the latest version of Docutils from
+  CVS_ or from the `development snapshot`_ and check again.  Even if
+  your bug has not been fixed, others probably have, and you're better
+  off with the most up-to-date code.
+
+  If you don't have time to check the latest snapshot, please report
+  the bug anyway.  We'd rather tell you that it's already fixed than
+  miss reports of unfixed bugs.
+
+* If Docutils does not behave the way you expect, look in the
+  documentation_ (don't forget the FAQ_!) and `mailing list archives`_
+  for evidence that it should behave the way you expect.
+
+If you're not sure, please ask on the
+docutils-users@lists.sourceforge.net [1]_ mailing list first.
+
+If it's a new bug, the most important thing you can do is to write a
+simple description and a recipe that reproduces the bug.  Try to
+create a minimal document that demonstrates the bug.  The easier you
+make it to understand and track down the bug, the more likely a fix
+will be.
+
+Now you're ready to write the bug report.  Please include:
+
+* A clear description of the bug.  Describe how you expected Docutils
+  to behave, and contrast that with how it actually behaved.  While
+  the bug may seem obvious to you, it may not be so obvious to someone
+  else, so it's best to avoid a guessing game.
+
+* A complete description of the environment in which you reproduced
+  the bug:
+
+  - Your operating system & version.
+  - The version of Python (``python -V``).
+  - The version of Docutils (use the "-V" option to most Docutils
+    front-end tools).
+  - Any private modifications you made to Docutils.
+  - Anything else that could possibly be relevant.  Err on the side
+    of too much information, rather than too little.
+
+* A literal transcript of the *exact* command you ran, and the *exact*
+  output.  Use the "--traceback" option to get a complete picture.
+
+* The exact input and output files.  Better to attach complete files
+  to your bug report than to include just a summary or excerpt.
+
+* If you also want to include speculation as to the cause, and even a
+  patch to fix the bug, that would be great!
+
+The best place to send your bug report is to the `SourceForge Bug
+Tracker`_.  That way, it won't be misplaced or forgotten.  In fact, an
+open bug report on SourceForge is a constant irritant that begs to be
+squashed.
+
+Thank you!
+
+(This section was inspired by the `Subversion project's`__ BUGS__
+file.)
+
+.. [1] Due to overwhelming amounts of spam, the
+   docutils-users@lists.sourceforge.net mailing list has been set up
+   for subscriber posting only.  Non-subscribers who post to
+   docutils-users will receive a message with "Subject: Your message
+   to Docutils-users awaits moderator approval".  Legitimate messages
+   are accepted and posted as soon as possible (a list administrator
+   must verify the message manually).  If you'd like to subscribe to
+   docutils-users, please visit
+   <http://lists.sourceforge.net/lists/listinfo/docutils-users>.
+
+__ http://subversion.tigris.org/
+__ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup
+
+.. _CVS: http://sourceforge.net/cvs/?group_id=38414
+.. _development snapshot: http://docutils.sf.net/#development-snapshot
+.. _documentation: docs/
+.. _FAQ: FAQ.html
+.. _mailing list archives: http://docutils.sf.net/#mailing-lists
+.. _SourceForge Bug Tracker:
+   http://sourceforge.net/tracker/?group_id=38414&atid=422030
+
+
+Known Bugs
+==========
+
+Also see the `SourceForge Bug Tracker`_.
+
+* _`Line numbers` in system messages are inconsistent in the parser.
+
+  - In text inserted by the "include" directive, errors are often not
+    reported with the correct "source" or "line" numbers.  Perhaps all
+    Reporter calls need "source" and "line" keyword arguments.
+    Elements' .line assignments should be checked.  (Assign to .source
+    too?  Add a set_info method?  To what?)  There's a test in
+    test/test_parsers/test_rst/test_directives/test_include.py.
+
+  - Some line numbers in elements are not being set properly
+    (explicitly), just implicitly/automatically.  See rev. 1.74 of
+    docutils/parsers/rst/states.py for an example of how to set.
+
+* .. _none source:
+
+  Quite a few nodes are getting a "None" source attribute as well.  In
+  particular, see the bodies of definition lists.
+
+* .. _mislocated targets:
+
+  Explicit targets are sometimes mis-located.  In particular, placing
+  a target before a section header puts the target at the end of the
+  previous section instead of the start of the next section.  The code
+  in docutils.transforms.misc.ClassAttribute could be used to fix
+  this.  (Reported by David Priest.)
+
+* David Abrahams pointed out that _`doubly-indirect substitutions`
+  have a bug, but only when there's multiple references::
+
+      |substitute| my coke for gin
+      |substitute| you for my mum
+      at least I'll get my washing done
+
+      .. |substitute| replace:: |replace|
+      .. |replace| replace:: swap
+
+  This is tricky.  Substitutions have to propagate back completely.
+
+* .. _subsitutions and references:
+
+  Another bug from David Abrahams (run with ``rst2html.py --traceback``)::
+
+      |substitution| and again a |substitution|.
+
+      .. |substitution| replace:: ref__
+
+      __ a.html
+      __ b.html
+
+  Change the references.Substitutions tranform's priority from 220 to
+  680, so it happens after reference resolution?  Then we have to deal
+  with multiple IDs.  Perhaps the Substitution transform should remove
+  all IDs from definitions after the first substitution reference is
+  processed.
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

lib/python/third_party/docutils/COPYING.txt

+==================
+ Copying Docutils
+==================
+
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:Date: $Date: 2004/10/29 19:08:15 $
+:Web site: http://docutils.sourceforge.net/
+:Copyright: This document has been placed in the public domain.
+
+Most of the files included in this project have been placed in the
+public domain, and therefore have no license requirements and no
+restrictions on copying or usage; see the `Public Domain Dedication`_
+below.  There are a few exceptions_, listed below.
+
+One goal of the Docutils project is to be included in the Python
+standard library distribution, at which time it is expected that
+copyright will be asserted by the `Python Software Foundation
+<http://www.python.org/psf/>`_.
+
+
+Public Domain Dedication
+========================
+
+The persons who have associated their work with this project (the
+"Dedicator": David Goodger and the many contributors to the Docutils
+project) hereby dedicate the entire copyright, less the exceptions_
+listed below, in the work of authorship known as "Docutils" identified
+below (the "Work") to the public domain.
+
+The primary repository for the Work is the Internet World Wide Web
+site <http://docutils.sourceforge.net/>.  The Work consists of the
+files within the "docutils" module of the Docutils project CVS
+repository (Internet host cvs.sourceforge.net, filesystem path
+/cvsroot/docutils), whose Internet web interface is located at
+<http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/docutils/>.
+Files dedicated to the public domain may be identified by the
+inclusion, near the beginning of each file, of a declaration of the
+form::
+
+    Copyright: This document/module/DTD/stylesheet/file/etc. has been
+               placed in the public domain.
+
+Dedicator makes this dedication for the benefit of the public at large
+and to the detriment of Dedicator's heirs and successors.  Dedicator
+intends this dedication to be an overt act of relinquishment in
+perpetuity of all present and future rights under copyright law,
+whether vested or contingent, in the Work.  Dedicator understands that
+such relinquishment of all rights includes the relinquishment of all
+rights to enforce (by lawsuit or otherwise) those copyrights in the
+Work.
+
+Dedicator recognizes that, once placed in the public domain, the Work
+may be freely reproduced, distributed, transmitted, used, modified,
+built upon, or otherwise exploited by anyone for any purpose,
+commercial or non-commercial, and in any way, including by methods
+that have not yet been invented or conceived.
+
+(This dedication is derived from the text of the `Creative Commons
+Public Domain Dedication
+<http://creativecommons.org/licenses/publicdomain>`_.)
+
+
+Exceptions
+==========
+
+The exceptions to the `Public Domain Dedication`_ above are:
+
+* extras/optparse.py, copyright by Gregory P. Ward, released under a
+  BSD-style license (which can be found in the module's source code).
+
+* extras/textwrap.py, copyright by Gregory P. Ward and the Python
+  Software Foundation, released under the `Python 2.3 license`_
+  (`local copy`__).
+
+  __ licenses/python-2-3.txt
+
+* extras/roman.py, copyright by Mark Pilgrim, released under the
+  `Python 2.1.1 license`_ (`local copy`__).
+
+  __ licenses/python-2-1-1.txt
+
+* test/docutils_difflib.py, copyright by the Python Software
+  Foundation, released under the `Python 2.2 license`_ (`local
+  copy`__).  This file is included for compatibility with Python
+  versions less than 2.2.  (It's only used to report test failures
+  anyhow; it isn't installed anywhere.  The included file is a
+  pre-generator version of the difflib.py module included in Python
+  2.2.)
+
+  __ licenses/python-2-2.txt
+
+* tools/pep2html.py, copyright by the Python Software Foundation,
+  released under the `Python 2.2 license`_ (`local copy`__).
+
+  __ licenses/python-2-2.txt
+
+* tools/editors/emacs/rst-html.el, copyright by Martin Blais, released
+  under the `GNU General Public License`_ (`local copy`__).
+
+  __ licenses/gpl.txt
+
+* tools/editors/emacs/rst-mode.el, copyright by Stefan Merten,
+  released under the `GNU General Public License`_ (`local copy`__).
+
+  __ licenses/gpl.txt
+
+(Disclaimer: I am not a lawyer.)  The BSD license and the Python
+licenses are OSI-approved_ and GPL-compatible_.  Although complicated
+by multiple owners and lots of legalese, the Python license basically
+lets you copy, use, modify, and redistribute files as long as you keep
+the copyright attribution intact, note any changes you make, and don't
+use the owner's name in vain.  The BSD license is similar.
+
+Plaintext versions of all the linked-to licenses are provided in the
+licenses_ directory.
+
+.. _licenses: licenses/
+.. _Python 2.1.1 license: http://www.python.org/2.1.1/license.html
+.. _Python 2.2 license: http://www.python.org/2.2/license.html
+.. _Python 2.3 license: http://www.python.org/2.3/license.html
+.. _GNU General Public License: http://www.gnu.org/copyleft/gpl.html
+.. _OSI-approved: http://opensource.org/licenses/
+.. _GPL-compatible: http://www.gnu.org/philosophy/license-list.html

lib/python/third_party/docutils/PKG-INFO

+Metadata-Version: 1.0
+Name: docutils
+Version: 0.3.5
+Summary: Docutils -- Python Documentation Utilities
+Home-page: http://docutils.sourceforge.net/
+Author: David Goodger
+Author-email: goodger@users.sourceforge.net
+License: public domain, Python, BSD, GPL (see COPYING.txt)
+Description: Docutils is a modular system for processing documentation
+        into useful formats, such as HTML, XML, and LaTeX.  For
+        input Docutils supports reStructuredText, an easy-to-read,
+        what-you-see-is-what-you-get plaintext markup syntax.
+Platform: OS-independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Other Audience
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: Public Domain
+Classifier: License :: OSI Approved :: Python Software Foundation License
+Classifier: License :: OSI Approved :: BSD License
+Classifier: License :: OSI Approved :: GNU General Public License (GPL)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Afrikaans
+Classifier: Natural Language :: Esperanto
+Classifier: Natural Language :: French
+Classifier: Natural Language :: German
+Classifier: Natural Language :: Italian
+Classifier: Natural Language :: Russian
+Classifier: Natural Language :: Slovak
+Classifier: Natural Language :: Spanish
+Classifier: Natural Language :: Swedish

lib/python/third_party/docutils/THANKS.txt

+Acknowledgements
+================
+
+:Author: David Goodger
+:Contact: goodger@python.org
+:Date: $Date: 2004/10/29 19:08:15 $
+:Revision: $Revision: 1.1.4.1 $
+:Copyright: This document has been placed in the public domain.
+
+I would like to acknowledge the people who have made a direct impact
+on the Docutils project, knowingly or not, in terms of encouragement,
+suggestions, criticism, bug reports, code contributions, cash
+donations, tasty treats, and related projects:
+
+* Aahz
+* David Abrahams
+* David Ascher
+* Heiko Baumann
+* Eric Bellot
+* Ian Bicking
+* Marek Blaha
+* Martin Blais
+* Stephen Boulet
+* Fred Bremmer
+* Simon Budig
+* Bill Bumgarner
+* Brett Cannon
+* Greg Chapman
+* Nicolas Chauveau
+* Beni Cherniavsky
+* Adam Chodorowski
+* Brent Cook
+* Laura Creighton
+* Artur de Sousa Rocha
+* Stephan Deibel & `Wing IDE <http://wingide.com/>`__
+* Jason Diamond
+* William Dode
+* Fred Drake
+* Reggie Dugard
+* Dethe Elza
+* Marcus Ertl
+* Benja Fallenstein
+* fantasai
+* Stefane Fermigier
+* Jim Fulton
+* Peter Funk
+* Lele Gaifax
+* Dinu C. Gherman
+* Matt Gilbert
+* Jorge Gonzalez
+* Engelbert Gruber
+* Jacob Hallen
+* Simon Hefti
+* Doug Hellmann
+* Marc Herbert
+* Juergen Hermann
+* Jannie Hofmeyr
+* Steve Holden
+* Michael Hudson
+* Marcelo Huerta San Martin
+* Ludger Humbert
+* Jeremy Hylton
+* Tony Ibbs
+* Alan Jaffray
+* Dmitry Jemerov
+* Richard Jones
+* Andreas Jung
+* Garth Kidd
+* Axel Kollmorgen
+* Jeff Kowalczyk
+* Dave Kuhlman
+* Lloyd Kvam
+* Kirill Lapshin
+* Nicola Larosa
+* Daniel Larsson
+* Marc-Andre Lemburg
+* Julien Letessier
+* Wolfgang Lipp
+* Edward Loper
+* Dallas Mahrt
+* Ken Manheimer
+* Bob Marshall
+* Mark McEahern
+* Vincent McIntyre
+* John F Meinel Jr
+* Vasko Miroslav
+* Skip Montanaro
+* Paul Moore
+* Nigel W. Moriarty
+* Mark Nodine
+* Patrick K. O'Brien
+* Michel Pelletier
+* Sam Penrose
+* Tim Peters
+* Pearu Peterson
+* Mark Pilgrim
+* Brett g Porter
+* David Priest
+* Jens Quade
+* Andy Robinson
+* Tavis Rudd
+* Tracy Ruggles
+* Oliver Rutherfurd
+* Kenichi Sato
+* Ueli Schlaepfer
+* Gunnar Schwant
+* Bill Sconce
+* Frank Siebenlist
+* Bruce Smith
+* Darek Suchojad
+* Roman Suzi
+* tav
+* Kent Tenney
+* Bob Tolbert
+* Paul Tremblay
+* Laurence Tratt
+* Adrian van den Dries
+* Guido van Rossum
+* Paul Viren
+* Martin von Loewis
+* Greg Ward
+* Barry Warsaw
+* Edward Welbourne
+* Felix Wiemann
+* Ka-Ping Yee
+* Moshe Zadka
+
+Thank you!
+
+Special thanks to `SourceForge <http://sourceforge.net>`__ and the
+`Python Software Foundation <http://www.python.org/psf/>`__.
+
+Hopefully I haven't forgotten anyone or misspelled any names;
+apologies (and please let me know!) if I have.

lib/python/third_party/docutils/docs/api/cmdline-tool.txt

+===============================================
+ Inside A Docutils Command-Line Front-End Tool
+===============================================
+
+:Author: David Goodger
+:Contact: goodger@python.org
+:Date: $Date: 2004/10/29 19:08:16 $
+:Revision: $Revision: 1.1.4.1 $
+:Copyright: This document has been placed in the public domain.
+
+`The Docutils Publisher`_ class was set up to make building
+command-line tools easy.  All that's required is to choose components
+and supply settings for variations.  Let's take a look at a typical
+command-line front-end tool, ``tools/rst2html.py``, from top to
+bottom.
+
+On Unixish systems, it's best to make the file executable (``chmod +x
+file``), and supply an interpreter on the first line, the "shebang" or
+"hash-bang" line::
+
+    #!/usr/bin/env python
+
+Windows systems can be set up to associate the Python interpreter with
+the ``.py`` extension.
+
+Next are some comments providing metadata::
+
+    # Author: David Goodger
+    # Contact: goodger@python.org
+    # Revision: $Revision: ...
+    # Date: $Date: ...
+    # Copyright: This module has been placed in the public domain.
+
+The module docstring describes the purpose of the tool::
+
+    """
+    A minimal front end to the Docutils Publisher, producing HTML.
+    """
+
+This next block attempts to invoke locale support for
+internationalization services, specifically text encoding.  It's not
+supported on all platforms though, so it's forgiving::
+
+    try:
+        import locale
+        locale.setlocale(locale.LC_ALL, '')
+    except:
+        pass
+
+The real work will be done by the code that's imported here::
+
+    from docutils.core import publish_cmdline, default_description
+
+We construct a description of the tool, for command-line help::
+
+    description = ('Generates (X)HTML documents from standalone '
+                   'reStructuredText sources.  ' + default_description)
+
+Now we call the Publisher convenience function, which takes over.
+Most of it's defaults are used ("standalone" Reader,
+"reStructuredText" Parser, etc.).  The HTML Writer is chosen by name,
+and a description for command-line help is passed in::
+
+    publish_cmdline(writer_name='html', description=description)
+
+That's it!  `The Docutils Publisher`_ takes care of the rest.
+
+.. _The Docutils Publisher: ./publisher.html

lib/python/third_party/docutils/docs/api/publisher.txt

+========================
+ The Docutils Publisher
+========================
+
+:Author: David Goodger
+:Contact: goodger@python.org
+:Date: $Date: 2004/10/29 19:08:16 $
+:Revision: $Revision: 1.1.4.1 $
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+
+Publisher Convenience Functions
+===============================
+
+Each of these functions set up a ``docutils.core.Publisher`` object,
+then call its ``publish`` method.  ``docutils.core.Publisher.publish``
+handles everything else.  There are five convenience functions in the
+``docutils.core`` module:
+
+* ``publish_cmdline``: for command-line front-end tools, like
+  ``rst2html.py``.  There are several examples in the ``tools/``
+  directory.  A detailed analysis of one such tool is in `Inside A
+  Docutils Command-Line Front-End Tool`_
+
+* ``publish_file``: for programmatic use with file-like I/O.  In
+  addition to writing the encoded output to a file, also returns the
+  encoded output as a string.
+
+* ``publish_string``: for programmatic use with string I/O.  Returns
+  the encoded output as a string.
+
+* ``publish_parts``: for programmatic use with string input; returns a
+  dictionary of document parts.  Dictionary keys are the names of
+  parts, and values are Unicode strings; encoding is up to the client.
+  Useful when only portions of the processed document are desired.
+  Currently only implemented for the HTML Writer.
+
+  There are examples in the ``docutils/examples.py`` module.
+
+* ``publish_programmatically``: for custom programmatic use.  This
+  function implements common code and is used by ``publish_file``,
+  ``publish_string``, and ``publish_parts``.  It returns a 2-tuple:
+  the encoded string output and the Publisher object.
+
+.. _Inside A Docutils Command-Line Front-End Tool: ./cmdline-tool.html
+
+
+Configuration
+-------------
+
+To pass application-specific setting defaults to the Publisher
+convenience functions, use the ``settings_overrides`` parameter.  Pass
+a dictionary of setting names & values, like this::
+
+    overrides = {'input_encoding': 'ascii',
+                 'output_encoding': 'latin-1'}
+    output = publish_string(..., settings_overrides=overrides)
+
+Settings from command-line options override configuration file
+settings, and they override application defaults.  For details, see
+`Docutils Runtime Settings`_.  See `Docutils Configuration Files`_ for
+details about individual settings.
+
+.. _Docutils Runtime Settings: ./runtime-settings.html
+.. _Docutils Configuration Files: ../user/tools.html
+
+
+Encodings
+---------
+
+The default output encoding of Docutils is UTF-8.  If you have any
+non-ASCII in your text, you may have to do a bit more setup.  Docutils
+may introduce some non-ASCII text if you use symbol-footnotes or
+section numbering.

lib/python/third_party/docutils/docs/api/runtime-settings.txt

+===========================
+ Docutils Runtime Settings
+===========================
+
+:Author: David Goodger
+:Contact: goodger@python.org
+:Date: $Date: 2004/10/29 19:08:16 $
+:Revision: $Revision: 1.1.4.1 $
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+
+Introduction
+============
+
+Docutils runtime settings are assembled from several sources:
+component settings specifications, application settings
+specifications, configuration files, and command-line options.
+Docutils overlays default and explicitly specified values from these
+sources such that settings behave the way we want and expect them to
+behave.
+
+To understand how Docutils deals with runtime settings, the attributes
+and parameters involved must first be understood.  Begin with the the
+docstrings of the attributes of the ``docutils.SettingsSpec`` base
+class (in the ``docutils/__init__.py`` module):
+
+* ``settings_spec``
+* ``settings_defaults``
+* ``settings_default_overrides``
+* ``relative_path_settings``
+* ``config_section``
+* ``config_section_dependencies``
+
+Next, several _`convenience function parameters` are also significant
+(described in the ``docutils.core.publish_programmatically`` function
+docstring):
+
+* ``settings``, if present, is assumed to be complete and no further
+  runtime settings processing is done.
+
+* ``settings_spec`` is treated as a fourth component (after the
+  Parser, Reader, and Writer).
+
+* ``settings_overrides`` is a dictionary which will override the
+  defaults of the components.
+
+* ``config_section`` sets or overrides an application-specific
+  configuration file section.
+
+
+.. _command-line tools:
+
+Runtime Settings Processing for Command-Line Tools
+==================================================
+
+Following along with the actual code is recommended.  The
+``docutils/__init__.py``, ``docutils/core.py``, and
+``docutils.frontend`` modules are described.
+
+1. A command-line front-end tool imports and calls
+   ``docutils.core.publish_cmdline``.  The relevant `convenience
+   function parameters`_ are described above.
+
+2. ``docutils.core.publish_cmdline`` initializes a
+   ``docutils.core.Publisher`` object, then calls its ``publish``
+   method.
+
+3. The ``docutils.core.Publisher`` object's ``publish`` method checks
+   its ``settings`` attribute to see if it's defined.  If it is, no
+   further runtime settings processing is done.
+
+   If ``settings`` is not defined, ``self.process_command_line`` is
+   called with the following relevant arguments:
+
+   * ``settings_spec``
+   * ``config_section``
+   * ``settings_overrides`` (in the form of excess keyword
+     arguments, collected in the ``defaults`` parameter)
+
+4. ``self.process_command_line`` calls ``self.setup_option_parser``,
+   passing ``settings_spec``, ``config_section``, and ``defaults``.
+
+5. ``self.setup_option_parser`` checks its ``config_section``
+   parameter; if defined, it adds that config file section to
+   ``settings_spec`` (or to a new, empty ``docutils.SettingsSpec``
+   object), replacing anything defined earlier.  (See `Docutils
+   Configuration Files`_ for details.)  Then it instantiates a new
+   ``docutils.frontend.OptionParser`` object, passing the following
+   relevant arguments:
+
+   * ``components``: A tuple of ``docutils.SettingsSpec`` objects,
+     ``(self.parser, self.reader, self.writer, settings_spec)``
+   * ``defaults`` (originally from ``settings_overrides``)
+
+6. The ``docutils.frontend.OptionParser`` object's ``__init__`` method
+   calls ``self.populate_from_components`` with ``self.components``,
+   which consists of ``self`` prepended to the ``components`` tuple it
+   received.  ``self`` (``docutils.frontend.OptionParser``) defines
+   general Docutils settings.
+
+7. In ``self.populate_from_components``, for each component passed,
+   ``component.settings_spec`` is processed and
+   ``component.settings_defaults`` is applied.  Then, for each
+   component, ``component.settings_default_overrides`` is applied.
+   This two-loop process ensures that
+   ``component.settings_default_overrides`` can override the default
+   settings of any other component.
+
+8. Back in ``docutils.frontend.OptionParser.__init__``, the
+   ``defaults`` parameter (derived from the ``settings_overrides``
+   parameter of ``docutils.core.Publisher.publish``) is overlaid over
+   ``self.defaults``.  So ``settings_overrides`` has priority over all
+   ``SettingsSpec`` data.
+
+9. Next, ``docutils.frontend.OptionParser.__init__`` checks if
+   configuration files are enabled (its ``read_config_files``
+   parameter is true, and ``self.defaults['_disable_config']`` is
+   false).  If they are enabled (and normally, they are),
+   ``self.get_standard_config_settings`` is called.  This reads the
+   `docutils configuration files`_, and returns a dictionary of
+   settings.  This is then overlaid on ``self.defaults``.  So
+   configuration file settings have priority over all software-defined
+   defaults.
+
+10. Back in the ``docutils.core.Publisher`` object,
+    ``self.setup_option_parser`` returns the ``option_parser`` object
+    to its caller, ``self.process_command_line``.
+
+11. ``self.process_command_line`` calls ``option_parser.parse_args``,
+    which parses all command line options and returns a
+    ``docutils.frontend.Values`` object.  This is assigned to the
+    ``docutils.core.Publisher`` object's ``self.settings``.  So
+    command-line options have priority over configuration file
+    settings.
+
+    When ``option_parser.parse_args`` is called, the source and
+    destination command-line arguments are also parsed, and assigned
+    to the ``_source`` and ``_destination`` attributes of what becomes
+    the ``docutils.core.Publisher`` object's ``self.settings``.
+
+12. From ``docutils.core.Publisher.publish``, ``self.set_io`` is
+    called with no arguments.  If either ``self.source`` or
+    ``self.destination`` are not set, the corresponding
+    ``self.set_source`` and ``self.set_destination`` are called,
+    effectively with no arguments.
+
+13. ``self.set_source`` checks for a ``source_path`` parameter, and if
+    there is none (which is the case for command-line use), it is
+    taken from ``self.settings._source``.  ``self.source`` is set by
+    instantiating a ``self.source_class`` object.  For command-line
+    front-end tools, the default ``self.source_class`` is used,
+    ``docutils.io.FileInput``.
+
+14. ``self.set_destination`` does the same job for the destination
+    that ``self.set_source`` does for the source (the default
+    ``self.destination_class`` is ``docutils.io.FileOutput``).
+
+.. _Docutils Configuration Files: ../user/tools.html
+
+
+Runtime Settings Processing From Applications
+=============================================
+
+Applications process runtime settings in a significantly different way
+than `command-line tools`_ do.  Instead of calling
+``publish_cmdline``, the application calls one of ``publish_file``,
+``publish_string``, or ``publish_parts``.  These in turn call
+``publish_programmatically``, which implements a generic programmatic
+interface.  Although an application may also call
+``publish_programmatically`` directly, it is not recommended (if it
+does seem to be necessary, please write to the `Docutils-Develop
+mailing list`_).
+
+``publish_programmatically`` accepts the same `convenience function
+parameters`_ as ``publish_cmdline``.  Where things differ is that
+programmatic use does not
+
+TO BE COMPLETED.
+
+.. copy & modify the list from command-line tools?
+
+
+.. _Docutils-Develop mailing list: docutils-develop@lists.sf.net

lib/python/third_party/docutils/docs/dev/enthought-rfp.txt

+==================================
+ Enthought API Documentation Tool
+==================================
+-----------------------
+ Request for Proposals
+-----------------------
+
+:Author: Janet Swisher, Senior Technical Writer
+:Organization: `Enthought, Inc. <http://www.enthought.com>`_
+:Copyright: 2004 by Enthought, Inc.
+:License: `Enthought License`_ (BSD Style)
+
+.. _Enthought License: http://docutils.sf.net/licenses/enthought.txt
+
+The following is excerpted from the full RFP, and is published here
+with permission from `Enthought, Inc.`_  See the `Plan for Enthought
+API Documentation Tool`__.
+
+__ enthought-plan.html
+
+.. contents::
+.. sectnum::
+
+
+Requirements
+============
+
+The documentation tool will address the following high-level goals:
+
+
+Documentation Extraction
+------------------------
+
+1. Documentation will be generated directly from Python source code,
+   drawing from the code structure, docstrings, and possibly other
+   comments.
+
+2. The tool will extract logical constructs as appropriate, minimizing
+   the need for comments that are redundant with the code structure.
+   The output should reflect both documented and undocumented
+   elements.
+
+
+Source Format
+-------------
+
+1. The docstrings will be formatted in as terse syntax as possible.
+   Required tags, syntax, and white space should be minimized.
+
+2. The tool must support the use of Traits.  Special comment syntax
+   for Traits may be necessary.  Information about the Traits package
+   is available at http://old.scipy.org/site_content/traits.  In the
+   following example, each trait definition is prefaced by a plain
+   comment::
+
+       __traits__ = {
+
+       # The current selection within the frame.
+       'selection' : Trait([], TraitInstance(list)),
+
+       # The frame has been activated or deactivated.
+       'activated' : TraitEvent(),
+
+       'closing' : TraitEvent(),
+
+       # The frame is closed.
+       'closed' : TraitEvent(),
+       }
+
+3. Support for ReStructuredText (ReST) format is desirable, because
+   much of the existing docstrings uses ReST.  However, the complete
+   ReST specification need not be supported, if a subset can achieve
+   the project goals.  If the tool does not support ReST, the
+   contractor should also provide a tool or path to convert existing
+   docstrings.
+
+
+Output Format
+-------------
+
+1. Documentation will be output as a navigable suite of HTML
+   files.
+
+2. The style of the HTML files will be customizable by a cascading
+   style sheet and/or a customizable template.
+
+3. Page elements such as headers and footer should be customizable, to
+   support differing requirements from one documentation project to
+   the next.
+
+
+Output Structure and Navigation
+-------------------------------
+
+1. The navigation scheme for the HTML files should not rely on frames,
+   and should harmonize with conversion to Microsoft HTML Help (.chm)
+   format.
+
+2. The output should be structured to make navigable the architecture
+   of the Python code.  Packages, modules, classes, traits, and
+   functions should be presented in clear, logical hierarchies.
+   Diagrams or trees for inheritance, collaboration, sub-packaging,
+   etc. are desirable but not required.
+
+3. The output must include indexes that provide a comprehensive view
+   of all packages, modules, and classes.  These indexes will provide
+   readers with a clear and exhaustive view of the code base.  These
+   indexes should be presented in a way that is easily accessible and
+   allows easy navigation.
+
+4. Cross-references to other documented elements will be used
+   throughout the documentation, to enable the reader to move quickly
+   relevant information.  For example, where type information for an
+   element is available, the type definition should be
+   cross-referenced.
+
+5. The HTML suite should provide consistent navigation back to the
+   home page, which will include the following information:
+
+   * Bibliographic information
+
+     - Author
+     - Copyright
+     - Release date
+     - Version number
+
+   * Abstract
+
+   * References
+
+     - Links to related internal docs (i.e., other docs for the same
+       product)
+
+     - Links to related external docs (e.g., supporting development
+       docs, Python support docs, docs for included packages)
+
+   It should be possible to specify similar information at the top
+   level of each package, so that packages can be included as
+   appropriate for a given application.
+
+
+License
+=======
+
+Enthought intends to release the software under an open-source
+("BSD-style") license.

lib/python/third_party/docutils/docs/dev/pysource.dtd

+<!--
+======================================================================
+    Docutils Python Source DTD
+======================================================================
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:Revision: $Revision: 1.1.4.1 $
+:Date: $Date: 2004/10/29 19:08:16 $
+:Copyright: This DTD has been placed in the public domain.
+:Filename: pysource.dtd
+
+This DTD (document type definition) extends the Generic DTD (see
+below).
+
+More information about this DTD and the Docutils project can be found
+at http://docutils.sourceforge.net/.  The latest version of this DTD
+is available from
+http://docutils.sourceforge.net/docs/dev/pysource.dtd.
+
+The formal public identifier for this DTD is::
+
+    +//IDN docutils.sourceforge.net//DTD Docutils Python Source//EN//XML
+-->
+
+<!--
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Parameter Entity Overrides
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-->
+
+<!ENTITY % additional.section.elements
+  " | package_section | module_section | class_section
+    | method_section | function_section
+    | module_attribute_section | function_attribute_section
+    | class_attribute_section | instance_attribute_section ">
+
+<!ENTITY % additional.inline.elements
+  " | package | module | class | method | function
+    | variable | parameter | type | attribute
+    | module_attribute | class_attribute | instance_attribute
+    | exception_class | warning_class ">
+
+<!--
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Generic DTD
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This DTD extends the Docutils Generic DTD, available from
+http://docutils.sourceforge.net/docs/ref/docutils.dtd.
+-->
+
+<!ENTITY % docutils PUBLIC
+    "+//IDN python.org//DTD Docutils Generic//EN//XML"
+    "docutils.dtd">
+%docutils;
+
+<!--
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Additional Section Elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-->
+
+<!ELEMENT package_section
+    (package, fullname?, import_list?, %structure.model;)>
+<!ATTLIST package_section %basic.atts;>
+
+<!ELEMENT module_section
+    (module, fullname?, import_list?, %structure.model;)>
+<!ATTLIST module_section %basic.atts;>
+
+<!ELEMENT class_section
+    (class, inheritance_list?, fullname?, subclasses?,
+     %structure.model;)>
+<!ATTLIST class_section %basic.atts;>
+
+<!ELEMENT method_section
+    (method, parameter_list?, fullname?, overrides?,
+     %structure.model;)>
+<!ATTLIST method_section %basic.atts;>
+
+<!ELEMENT function_section
+    (function, parameter_list?, fullname?, %structure.model;)>
+<!ATTLIST function_section %basic.atts;>
+
+<!ELEMENT module_attribute_section
+    (attribute, initial_value?, fullname?, %structure.model;)>
+<!ATTLIST module_attribute_section %basic.atts;>
+
+<!ELEMENT function_attribute_section
+    (attribute, initial_value?, fullname?, %structure.model;)>
+<!ATTLIST function_attribute_section %basic.atts;>
+
+<!ELEMENT class_attribute_section
+    (attribute, initial_value?, fullname?, overrides?,
+     %structure.model;)>
+<!ATTLIST class_attribute_section %basic.atts;>
+
+<!ELEMENT instance_attribute_section
+    (attribute, initial_value?, fullname?, overrides?,
+     %structure.model;)>
+<!ATTLIST instance_attribute_section %basic.atts;>
+
+<!--
+    Section Subelements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-->
+
+<!ELEMENT fullname
+    (package | module | class | method | function | attribute)+>
+<!ATTLIST fullname %basic.atts;>
+
+<!ELEMENT import_list (import_item+)>
+<!ATTLIST import_list %basic.atts;>
+
+<!--
+Support ``import module``, ``import module as alias``, ``from module
+import identifier``, and ``from module import identifier as alias``.
+-->
+<!ELEMENT import_item (fullname, identifier?, alias?)>
+<!ATTLIST import_item %basic.atts;>
+
+<!ELEMENT inheritance_list (class+)>
+<!ATTLIST inheritance_list %basic.atts;>
+
+<!ELEMENT subclasses (class+)>
+<!ATTLIST subclasses %basic.atts;>
+
+<!ELEMENT parameter_list
+    ((parameter_item+, optional_parameters*) | optional_parameters+)>
+<!ATTLIST parameter_list %basic.atts;>
+
+<!ELEMENT parameter_item
+    ((parameter | parameter_tuple), parameter_default?)>
+<!ATTLIST parameter_item %basic.atts;>
+
+<!ELEMENT optional_parameters (parameter_item+, optional_parameters*)>
+<!ATTLIST optional_parameters %basic.atts;>
+
+<!ELEMENT parameter_tuple (parameter | parameter_tuple)+>
+<!ATTLIST parameter_tuple %basic.atts;>
+
+<!ELEMENT parameter_default (#PCDATA)>
+<!ATTLIST parameter_default %basic.atts;>
+
+<!ELEMENT overrides (fullname+)>
+<!ATTLIST overrides %basic.atts;>
+
+<!ELEMENT initial_value (#PCDATA)>
+<!ATTLIST initial_value %basic.atts;>
+
+<!--
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Additional Inline Elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-->
+
+<!-- Also used as the `package_section` identifier/title. -->
+<!ELEMENT package (#PCDATA)>
+<!ATTLIST package
+    %basic.atts;
+    %reference.atts;>
+
+<!-- Also used as the `module_section` identifier/title. -->
+<!ELEMENT module (#PCDATA)>
+<!ATTLIST module
+    %basic.atts;
+    %reference.atts;>
+
+<!--
+Also used as the `class_section` identifier/title, and in the
+`inheritance` element.
+-->
+<!ELEMENT class (#PCDATA)>
+<!ATTLIST class
+    %basic.atts;
+    %reference.atts;>
+
+<!-- Also used as the `method_section` identifier/title. -->
+<!ELEMENT method (#PCDATA)>
+<!ATTLIST method
+    %basic.atts;
+    %reference.atts;>
+
+<!-- Also used as the `function_section` identifier/title. -->
+<!ELEMENT function (#PCDATA)>
+<!ATTLIST function
+    %basic.atts;
+    %reference.atts;>
+
+<!--
+??? Use this instead of the ``*_attribute`` elements below?  Add a
+"type" attribute to differentiate?
+
+Also used as the identifier/title for `module_attribute_section`,
+`class_attribute_section`, and `instance_attribute_section`.
+-->
+<!ELEMENT attribute (#PCDATA)>
+<!ATTLIST attribute
+    %basic.atts;
+    %reference.atts;>
+
+<!--
+Also used as the `module_attribute_section` identifier/title. A module
+attribute is an exported module-level global variable.
+-->
+<!ELEMENT module_attribute (#PCDATA)>
+<!ATTLIST module_attribute
+    %basic.atts;
+    %reference.atts;>
+
+<!-- Also used as the `class_attribute_section` identifier/title. -->
+<!ELEMENT class_attribute (#PCDATA)>
+<!ATTLIST class_attribute
+    %basic.atts;
+    %reference.atts;>
+
+<!--
+Also used as the `instance_attribute_section` identifier/title.
+-->
+<!ELEMENT instance_attribute (#PCDATA)>
+<!ATTLIST instance_attribute
+    %basic.atts;
+    %reference.atts;>
+
+<!ELEMENT variable (#PCDATA)>
+<!ATTLIST variable
+    %basic.atts;
+    %reference.atts;>
+
+<!-- Also used in `parameter_list`. -->
+<!ELEMENT parameter (#PCDATA)>
+<!ATTLIST parameter
+    %basic.atts;
+    %reference.atts;
+    excess_positional  %yesorno;  #IMPLIED
+    excess_keyword     %yesorno;  #IMPLIED>
+
+<!ELEMENT type (#PCDATA)>
+<!ATTLIST type
+    %basic.atts;
+    %reference.atts;>
+
+<!ELEMENT exception_class (#PCDATA)>
+<!ATTLIST exception_class
+    %basic.atts;
+    %reference.atts;>
+
+<!ELEMENT warning_class (#PCDATA)>
+<!ATTLIST warning_class
+    %basic.atts;
+    %reference.atts;>
+
+<!--
+Local Variables:
+mode: sgml
+indent-tabs-mode: nil
+fill-column: 70
+End:
+-->

lib/python/third_party/docutils/docs/dev/pysource.txt

+======================
+ Python Source Reader
+======================
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:Revision: $Revision: 1.1.4.1 $
+:Date: $Date: 2004/10/29 19:08:16 $
+:Copyright: This document has been placed in the public domain.
+
+This document explores issues around extracting and processing
+docstrings from Python modules.
+
+For definitive element hierarchy details, see the "Python Plaintext
+Document Interface DTD" XML document type definition, pysource.dtd_
+(which modifies the generic docutils.dtd_).  Descriptions below list
+'DTD elements' (XML 'generic identifiers' or tag names) corresponding
+to syntax constructs.
+
+
+.. contents::
+
+
+Model
+=====
+
+The Python Source Reader ("PySource") model that's evolving in my mind
+goes something like this:
+
+1. Extract the docstring/namespace [#]_ tree from the module(s) and/or
+   package(s).
+
+   .. [#] See `Docstring Extractor`_ below.
+
+2. Run the parser on each docstring in turn, producing a forest of
+   doctrees (per nodes.py).
+
+3. Join the docstring trees together into a single tree, running
+   transforms:
+
+   - merge hyperlinks
+   - merge namespaces
+   - create various sections like "Module Attributes", "Functions",
+     "Classes", "Class Attributes", etc.; see pysource.dtd_
+   - convert the above special sections to ordinary doctree nodes
+
+4. Run transforms on the combined doctree.  Examples: resolving
+   cross-references/hyperlinks (including interpreted text on Python
+   identifiers); footnote auto-numbering; first field list ->
+   bibliographic elements.
+
+   (Or should step 4's transforms come before step 3?)
+
+5. Pass the resulting unified tree to the writer/builder.
+
+I've had trouble reconciling the roles of input parser and output
+writer with the idea of modes ("readers" or "directors").  Does the
+mode govern the tranformation of the input, the output, or both?
+Perhaps the mode should be split into two.
+
+For example, say the source of our input is a Python module.  Our
+"input mode" should be the "Python Source Reader".  It discovers (from
+``__docformat__``) that the input parser is "reStructuredText".  If we
+want HTML, we'll specify the "HTML" output formatter.  But there's a
+piece missing.  What *kind* or *style* of HTML output do we want?
+PyDoc-style, LibRefMan style, etc.  (many people will want to specify
+and control their own style).  Is the output style specific to a
+particular output format (XML, HTML, etc.)?  Is the style specific to
+the input mode?  Or can/should they be independent?
+
+I envision interaction between the input parser, an "input mode" , and
+the output formatter.  The same intermediate data format would be used
+between each of these, being transformed as it progresses.
+
+
+Docstring Extractor
+===================
+
+We need code that scans a parsed Python module, and returns an ordered
+tree containing the names, docstrings (including attribute and
+additional docstrings), and additional info (in parentheses below) of
+all of the following objects:
+
+- packages
+- modules
+- module attributes (+ values)
+- classes (+ inheritance)
+- class attributes (+ values)
+- instance attributes (+ values)
+- methods (+ formal parameters & defaults)
+- functions (+ formal parameters & defaults)
+
+(Extract comments too?  For example, comments at the start of a module
+would be a good place for bibliographic field lists.)
+
+In order to evaluate interpreted text cross-references, namespaces for
+each of the above will also be required.
+
+See python-dev/docstring-develop thread "AST mining", started on
+2001-08-14.
+
+
+Interpreted Text
+================
+
+DTD elements: package, module, class, method, function,
+module_attribute, class_attribute, instance_attribute, variable,
+parameter, type, exception_class, warning_class.
+
+To classify identifiers explicitly, the role is given along with the
+identifier in either prefix or suffix form::
+
+    Use :method:`Keeper.storedata` to store the object's data in
+    `Keeper.data`:instance_attribute:.
+
+The role may be one of 'package', 'module', 'class', 'method',
+'function', 'module_attribute', 'class_attribute',
+'instance_attribute', 'variable', 'parameter', 'type',
+'exception_class', 'exception', 'warning_class', or 'warning'.  Other
+roles may be defined.
+
+.. _pysource.dtd: pysource.dtd
+.. _docutils.dtd: ../ref/docutils.dtd
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   fill-column: 70
+   End:

lib/python/third_party/docutils/docs/dev/website.txt

+===================
+ Docutils Web Site
+===================
+:Author: David Goodger; open to all Docutils developers
+:Contact: goodger@python.org
+:Date: $Date: 2004/10/29 19:08:16 $
+:Revision: $Revision: 1.1.4.1 $
+:Copyright: This document has been placed in the public domain.
+
+The Docutils web site, <http://docutils.sourceforge.net/>, is
+maintained automatically by the docutils-update script, run as an
+hourly cron job (by user "goodger").  The script will process any .txt
+file which is newer than the corresponding .html file in the project's
+web directory on SourceForge (``/home/groups/d/do/docutils/htdocs/``).
+For a new .txt file, just SSH to SourceForge and ::
+
+    touch filename.html
+    chmod g+w filename.html
+    sleep 1
+    touch filename.txt
+
+The script will take care of the rest within an hour.  Thereafter
+whenever the .txt file is modified (checked in to CVS), the .html will
+be regenerated automatically.
+
+After adding directories to CVS, allow the script to run once to
+create the directories in the filesystem before preparing for HTML
+processing as described above.
+
+The docutils-update__ script is in CVS as
+``sandbox/davidg/infrastructure/docutils-update``.
+
+__ http://docutils.sf.net/sandbox/davidg/infrastructure/docutils-update
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End: