removed

lib/python/third_party/README.txt

-This directory contains some third party packages.
-
-To upgrade docutils:
-
- - untar docutils-XX.tar.gz inside the third_party directoy
-
- - rename it to 'docutils'
-
- - remove docutils/tools/editors/emacs/* (files are GPLed)
-
- - update the files in the CVS
-
-

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/docutils/languages/__init__.py

-# Author: David Goodger
-# Contact: goodger@users.sourceforge.net
-# Revision: $Revision: 1.1.4.1 $
-# Date: $Date: 2004/10/29 19:08:21 $
-# Copyright: This module has been placed in the public domain.
-
-# Internationalization details are documented in
-# <http://docutils.sf.net/docs/howto/i18n.html>.
-
-"""
-This package contains modules for language-dependent features of Docutils.
-"""
-
-__docformat__ = 'reStructuredText'
-
-_languages = {}
-
-def get_language(language_code):
-    if _languages.has_key(language_code):
-        return _languages[language_code]
-    module = __import__(language_code, globals(), locals())
-    _languages[language_code] = module
-    return module