Added files missing from initial import.

BUGS.txt

@@ -0,0 +1,291 @@
+================
+ Docutils_ Bugs
+================
+
+:Author: David Goodger; open to all Docutils developers
+:Contact: goodger@python.org
+:Date: $Date: 2017-06-09 13:02:35 +0200 (Fr, 09 Jun 2017) $
+:Revision: $Revision: 8103 $
+: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
+  the repository_ or from the current 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_ 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 example`_ that demonstrates the bug.  The easier you
+make it to understand and track down the bug, the more likely a fix
+will be.
+
+.. _minimal example:
+
+.. sidebar:: minimal example
+
+  A `minimal working example` is a complete example which is as as small and
+  simple as possible. It should be complete and working, so that
+
+  * you cannot accidentally omit information important to diagnosing
+    the problem and
+  * the person responding can just copy-and-paste the code to try it out.
+
+  To construct an example which is as small as possible, the rule
+  quite simple: *remove/leave out anything which is not necessary*.
+
+  See also: `What is a minimal working example?`__, `LaTeX FAQ`__
+
+  __ http://www.minimalbeispiel.de/mini-en.html
+  __ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=minxampl
+
+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.  Create a `minimal example`_
+  of the failing behaviour — it is 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.)
+
+__ http://subversion.tigris.org/
+__ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup
+
+.. _repository: docs/dev/repository.html
+.. _snapshot: http://docutils.sourceforge.net/#download
+.. _documentation: docs/
+.. _FAQ: FAQ.html
+.. _mailing list archives: http://docutils.sf.net/#mailing-lists
+.. _Docutils-users: docs/user/mailing-lists.html#docutils-users
+.. _SourceForge Bug Tracker:
+   http://sourceforge.net/p/docutils/bugs/
+
+
+Known Bugs
+==========
+
+Also see the `SourceForge Bug Tracker`_.
+
+* .. _error reporting:
+
+  Calling rst2s5.py with a non-existent theme (``--theme
+  does_not_exist``)
+  causes exceptions.  Such errors should be handled more gracefully.
+
+* The "stylesheet" setting (a URL, to be used verbatim) should be
+  allowed to be combined with "embed_stylesheet".  The stylesheet data
+  should be read in using urllib.  There was an assumption that a
+  stylesheet to be embedded should exist as a file on the local
+  system, and only the "stylesheet_path" setting should be used.
+
+* ``utils.relative_path()`` sometimes returns absolute _`paths on
+  Windows` (like ``C:/test/foo.css``) where it could have chosen a
+  relative path.
+
+  Furthermore, absolute pathnames are inserted verbatim, like
+  ``href="C:/test/foo.css"`` instead of
+  ``href="file:///C:/test/foo.css"``.
+
+  .. gmane web interface is down.
+     TODO: find this article in the Sourceforge mail archives
+     For details, see `this posting by Alan G. Isaac
+     <http://article.gmane.org/gmane.text.docutils.user/1569>`_.
+
+* Footnote label "5" should be "4" when processing the following
+  input::
+
+      ref [#abc]_ [#]_ [1]_ [#4]_
+
+      .. [#abc] footnote
+      .. [#] two
+      .. [1] one
+      .. [#4] four
+
+  Output::
+
+      <document source="<stdin>">
+          <paragraph>
+              ref
+              <footnote_reference auto="1" ids="id1" refid="abc">
+                  2
+
+              <footnote_reference auto="1" ids="id2" refid="id5">
+                  3
+
+              <footnote_reference ids="id3" refid="id6">
+                  1
+
+              <footnote_reference auto="1" ids="id4" refid="id7">
+                  5
+          <footnote auto="1" backrefs="id1" ids="abc" names="abc">
+              <label>
+                  2
+              <paragraph>
+                  footnote
+          <footnote auto="1" backrefs="id2" ids="id5" names="3">
+              <label>
+                  3
+              <paragraph>
+                  two
+          <footnote backrefs="id3" ids="id6" names="1">
+              <label>
+                  1
+              <paragraph>
+                  one
+          <footnote auto="1" backrefs="id4" ids="id7" names="4">
+              <label>
+                  5
+              <paragraph>
+                  four
+
+* IDs are based on names.  Explicit hyperlink targets have priority
+  over implicit targets.  But if an explicit target comes after an
+  implicit target with the same name, the ID of the first (implicit)
+  target remains based on the implicit name.  Since HTML fragment
+  identifiers based on the IDs, the first target keeps the name.  For
+  example::
+
+      .. contents::
+
+      Section
+      =======
+
+      .. _contents:
+
+      Subsection
+      ----------
+
+      text with a reference to contents_ and section_
+
+      .. _section:
+
+      This paragraph is explicitly targeted with the name "section".
+
+  When processed to HTML, the 2 internal hyperlinks (to "contents" &
+  "section") will work fine, but hyperlinks from outside the document
+  using ``href="...#contents"`` and ``href="...#section"`` won't work.
+  Such external links will connect to the implicit targets (table of
+  contents and "Section" title) instead of the explicit targets
+  ("Subsection" title and last paragraph).
+
+  Hyperlink targets with duplicate names should be assigned new IDs
+  unrelated to the target names (i.e., "id"-prefix serial IDs).
+
+* The "contents" ID of the local table of contents in
+  ``test/functional/expected/standalone_rst_pseudoxml.txt`` is lost in
+  the HTML output at
+  ``test/functional/expected/standalone_rst_html4css1.html``.
+
+* _`Blank first columns` in simple tables with explicit row separators
+  silently swallow their input.  They should at least produce system
+  error messages.  But, with explicit row separators, the meaning is
+  unambiguous and ought to be supported::
+
+      ==============  ==========
+      Table with row  separators
+      ==============  ==========
+                      and blank
+      --------------  ----------
+                      entries
+      --------------  ----------
+                      in first
+      --------------  ----------
+                      columns.
+      ==============  ==========
+
+  Added a commented-out test case to
+  test/test_parsers/test_rst/test_SimpleTableParser.py.
+
+* _`Footnote references with hyperlink targets` cause a possibly
+  invalid node tree and make the HTML writer crash::
+
+      $ rst2pseudoxml.py
+      [1]_
+
+      .. _1: URI
+      <document source="<stdin>">
+          <paragraph>
+              <footnote_reference ids="id1" refuri="URI">
+                  1
+          <target ids="id2" names="1" refuri="URI">
+
+* Anonymous references have "name" attributes.  Should they?  Are they
+  used?  See ``test/test_parsers/test_rst/test_inline_markup.py``.
+
+* <reference> elements have a "name" attribute, not "names".  The
+  attribute should be "names"; this is an inconsistency.
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

COPYING.txt

@@ -0,0 +1,137 @@
+==================
+ Copying Docutils
+==================
+
+:Author: David Goodger
+:Contact: goodger@python.org
+:Date: $Date: 2015-05-08 17:56:32 +0200 (Fr, 08 Mai 2015) $
+: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.
+Files in the Sandbox_ are not distributed with Docutils releases and
+may have different license terms.
+
+
+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 Subversion
+repository (Internet host docutils.svn.sourceforge.net, filesystem path
+/svnroot/docutils), whose Internet web interface is located at
+<http://docutils.svn.sourceforge.net/viewvc/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`. [#]_)
+
+.. [#] Creative Commons has `retired this legal tool`__ and does not
+   recommend that it be applied to works: This tool is based on United
+   States law and may not be applicable outside the US. For dedicating new
+   works to the public domain, Creative Commons recommend the replacement
+   Public Domain Dedication CC0_ (CC zero, "No Rights Reserved"). So does
+   the Free Software Foundation in its license-list_.
+
+   __  http://creativecommons.org/retiredlicenses
+   .. _CC0: http://creativecommons.org/about/cc0
+
+Exceptions
+==========
+
+The exceptions to the `Public Domain Dedication`_ above are:
+
+* docutils/writers/s5_html/themes/default/iepngfix.htc:
+
+      IE5.5+ PNG Alpha Fix v1.0 by Angus Turnbull
+      <http://www.twinhelix.com>.  Free usage permitted as long as
+      this notice remains intact.
+
+* docutils/utils/math/__init__.py,
+  docutils/utils/math/latex2mathml.py,
+  docutils/writers/xetex/__init__.py,
+  docutils/writers/latex2e/docutils-05-compat.sty,
+  docs/user/docutils-05-compat.sty.txt,
+  docutils/utils/error_reporting.py,
+  docutils/test/transforms/test_smartquotes.py:
+
+  Copyright © Günter Milde.
+  Released under the terms of the `2-Clause BSD license`_
+  (`local copy <licenses/BSD-2-Clause.txt>`__).
+
+* docutils/utils/smartquotes.py
+
+  Copyright © 2011 Günter Milde,
+  based on `SmartyPants`_ © 2003 John Gruber
+  (released under a 3-Clause BSD license included in the file)
+  and smartypants.py © 2004, 2007 Chad Miller.
+  Released under the terms of the `2-Clause BSD license`_
+  (`local copy <licenses/BSD-2-Clause.txt>`__).
+
+  .. _SmartyPants: http://daringfireball.net/projects/smartypants/
+
+* docutils/utils/math/math2html.py,
+  docutils/writers/html4css1/math.css
+
+  Copyright © Alex Fernández
+  These files are part of eLyXer_, released under the `GNU
+  General Public License`_ version 3 or later. The author relicensed
+  them for Docutils under the terms of the `2-Clause BSD license`_
+  (`local copy <licenses/BSD-2-Clause.txt>`__).
+
+  .. _eLyXer: http://www.nongnu.org/elyxer/
+
+* docutils/utils/roman.py, copyright by Mark Pilgrim, released under the
+  `Python 2.1.1 license`_ (`local copy`__).
+
+  __ licenses/python-2-1-1.txt
+
+* tools/editors/emacs/rst.el, copyright by Free Software Foundation,
+  Inc., released under the `GNU General Public License`_ version 3 or
+  later (`local copy`__).
+
+  __ licenses/gpl-3-0.txt
+
+The `2-Clause BSD license`_ and the Python licenses are OSI-approved_
+and GPL-compatible_.
+
+Plaintext versions of all the linked-to licenses are provided in the
+licenses_ directory.
+
+.. _sandbox: http://docutils.sourceforge.net/sandbox/README.html
+.. _licenses: licenses/
+.. _Python 2.1.1 license: http://www.python.org/2.1.1/license.html
+.. _GNU General Public License: http://www.gnu.org/copyleft/gpl.html
+.. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause
+.. _OSI-approved: http://opensource.org/licenses/
+.. _license-list:
+.. _GPL-compatible: http://www.gnu.org/licenses/license-list.html

MANIFEST.in

@@ -0,0 +1,11 @@
+include *.txt
+include *.py
+include setup.cfg
+include MANIFEST
+include MANIFEST.in
+recursive-include docutils *
+recursive-include docs *
+recursive-include licenses *
+recursive-include test *
+recursive-include tools *
+recursive-exclude * *.pyc *~ .DS_Store

THANKS.txt

@@ -0,0 +1,169 @@
+.. -*- coding: utf-8 -*-
+
+Acknowledgements
+================
+
+:Author: David Goodger
+:Contact: goodger@python.org
+:Date: $Date: 2015-02-09 00:21:18 +0100 (Mo, 09 Feb 2015) $
+:Revision: $Revision: 7784 $
+: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
+* Guy D. Alcos
+* David Ascher
+* Ned Batchelder
+* Heiko Baumann
+* Anthony Baxter
+* Eric Bellot
+* Frank Bennett
+* 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
+* Michael Foord
+* 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 G. Isaac
+* Alan Jaffray
+* Joe YS Jaw
+* Dmitry Jemerov
+* Richard Jones
+* Andreas Jung
+* Robert Kern
+* Garth Kidd
+* Philipp Knüsel
+* Axel Kollmorgen
+* Jeff Kowalczyk
+* Martin F. Krafft
+* Meir Kriheli
+* Dave Kuhlman
+* Lloyd Kvam
+* Kirill Lapshin
+* Nicola Larosa
+* Daniel Larsson
+* Marc-Andre Lemburg
+* Julien Letessier
+* Chris Liechti
+* Wolfgang Lipp
+* Edward Loper
+* Dallas Mahrt
+* Brecht Machiels
+* Mikolaj Machowski
+* Ken Manheimer
+* Bob Marshall
+* Mark McEahern
+* Vincent McIntyre
+* John F Meinel Jr
+* Ivan Mendez for Free Software Office of the University of A Coruña
+* Eric Meyer
+* Günter Milde
+* Skip Montanaro
+* Paul Moore
+* Nigel W. Moriarty
+* Hisashi Morita
+* Mark Nodine
+* Omidyar Network (Pierre Omidyar & Doug Solomon)
+* Panjunyong
+* Patrick K. O'Brien
+* Michel Pelletier
+* Toshio Kuratomi
+* Sam Penrose
+* Tim Peters
+* Pearu Peterson
+* Martijn Pieters
+* Mark Pilgrim
+* Brett g Porter
+* David Priest
+* Jens Quade
+* Stefan Rank
+* Edward K. Ream
+* Andy Robinson
+* Tavis Rudd
+* Tracy Ruggles
+* Oliver Rutherfurd
+* Luc Saffre
+* Seo Sanghyeon
+* Kenichi Sato
+* Ueli Schlaepfer
+* Gunnar Schwant
+* Bill Sconce
+* Frank Siebenlist
+* Bruce Smith
+* Nir Soffer
+* Asko Soukka
+* Darek Suchojad
+* Roman Suzi
+* Janet Swisher
+* tav
+* Kent Tenney
+* Bob Tolbert
+* Paul Tremblay
+* Laurence Tratt
+* Adrian van den Dries
+* Guido van Rossum
+* Miroslav Vasko
+* Paul Viren
+* Martin von Loewis
+* Greg Ward
+* Barry Warsaw
+* Wu Wei
+* Edward Welbourne
+* Lea Wiemann
+* Anthony Williams
+* Robert Wojciechowicz
+* Ka-Ping Yee
+* Moshe Zadka
+* Shmuel Zeigerman
+
+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.

docs/api/cmdline-tool.txt

@@ -0,0 +1,66 @@
+===============================================
+ Inside A Docutils Command-Line Front-End Tool
+===============================================
+
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:Revision: $Revision: 7302 $
+: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::
+
+    # $Id: cmdline-tool.txt 7302 2012-01-03 19:23:53Z grubert $
+    # Author: David Goodger <goodger@python.org>
+    # 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 its 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

docs/api/publisher.txt

@@ -0,0 +1,344 @@
+========================
+ The Docutils Publisher
+========================
+
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:Revision: $Revision: 7302 $
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+
+The ``docutils.core.Publisher`` class is the core of Docutils,
+managing all the processing and relationships between components.  See
+`PEP 258`_ for an overview of Docutils components.
+
+The ``docutils.core.publish_*`` convenience functions are the normal
+entry points for using Docutils as a library.
+
+See `Inside A Docutils Command-Line Front-End Tool`_ for an overview
+of a typical Docutils front-end tool, including how the Publisher
+class is used.
+
+.. _PEP 258: ../peps/pep-0258.html
+.. _Inside A Docutils Command-Line Front-End Tool: ./cmdline-tool.html
+
+
+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 several 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.
+  See `publish_parts Details`_ below.
+
+  There are usage examples in the `docutils/examples.py`_ module.
+
+:_`publish_doctree`: for programmatic use with string input; returns a
+  Docutils document tree data structure (doctree).  The doctree can be
+  modified, pickled & unpickled, etc., and then reprocessed with
+  `publish_from_doctree`_.
+
+:_`publish_from_doctree`: for programmatic use to render from an
+  existing document tree data structure (doctree); returns the encoded
+  output as a string.
+
+:_`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
+.. _docutils/examples.py: ../../docutils/examples.py
+
+
+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 input text, you may have to do a bit more setup.
+Docutils may introduce some non-ASCII text if you use
+`auto-symbol footnotes`_ or the `"contents" directive`_.
+
+.. _auto-symbol footnotes:
+   ../ref/rst/restructuredtext.html#auto-symbol-footnotes
+.. _"contents" directive:
+   ../ref/rst/directives.html#table-of-contents
+
+
+``publish_parts`` Details
+=========================
+
+The ``docutils.core.publish_parts`` convenience function returns a
+dictionary of document parts.  Dictionary keys are the names of parts,
+and values are Unicode strings.
+
+Each Writer component may publish a different set of document parts,
+described below.  Not all writers implement all parts.
+
+
+Parts Provided By All Writers
+-----------------------------
+
+_`encoding`
+    The output encoding setting.
+
+_`version`
+    The version of Docutils used.
+
+_`whole`
+    ``parts['whole']`` contains the entire formatted document.
+
+
+.. _HTML writer:
+
+Parts Provided By the HTML Writer
+---------------------------------
+
+_`body`
+    ``parts['body']`` is equivalent to parts['fragment_'].  It is
+    *not* equivalent to parts['html_body_'].
+
+_`body_prefix`
+    ``parts['body_prefix']`` contains::
+
+        </head>
+        <body>
+        <div class="document" ...>
+
+    and, if applicable::
+
+        <div class="header">
+        ...
+        </div>
+
+_`body_pre_docinfo`
+    ``parts['body_pre_docinfo]`` contains (as applicable)::
+
+        <h1 class="title">...</h1>
+        <h2 class="subtitle" id="...">...</h2>
+
+_`body_suffix`
+    ``parts['body_suffix']`` contains::
+
+        </div>
+
+    (the end-tag for ``<div class="document">``), the footer division
+    if applicable::
+
+        <div class="footer">
+        ...
+        </div>
+
+    and::
+
+        </body>
+        </html>
+
+_`docinfo`
+    ``parts['docinfo']`` contains the document bibliographic data, the
+    docinfo field list rendered as a table.
+
+_`footer`
+    ``parts['footer']`` contains the document footer content, meant to
+    appear at the bottom of a web page, or repeated at the bottom of
+    every printed page.
+
+_`fragment`
+    ``parts['fragment']`` contains the document body (*not* the HTML
+    ``<body>``).  In other words, it contains the entire document,
+    less the document title, subtitle, docinfo, header, and footer.
+
+_`head`
+    ``parts['head']`` contains ``<meta ... />`` tags and the document
+    ``<title>...</title>``.
+
+_`head_prefix`
+    ``parts['head_prefix']`` contains the XML declaration, the DOCTYPE
+    declaration, the ``<html ...>`` start tag and the ``<head>`` start
+    tag.
+
+_`header`
+    ``parts['header']`` contains the document header content, meant to
+    appear at the top of a web page, or repeated at the top of every
+    printed page.
+
+_`html_body`
+    ``parts['html_body']`` contains the HTML ``<body>`` content, less
+    the ``<body>`` and ``</body>`` tags themselves.
+
+_`html_head`
+    ``parts['html_head']`` contains the HTML ``<head>`` content, less
+    the stylesheet link and the ``<head>`` and ``</head>`` tags
+    themselves.  Since ``publish_parts`` returns Unicode strings and
+    does not know about the output encoding, the "Content-Type" meta
+    tag's "charset" value is left unresolved, as "%s"::
+
+        <meta http-equiv="Content-Type" content="text/html; charset=%s" />
+
+    The interpolation should be done by client code.
+
+_`html_prolog`
+    ``parts['html_prolog]`` contains the XML declaration and the
+    doctype declaration.  The XML declaration's "encoding" attribute's
+    value is left unresolved, as "%s"::
+
+        <?xml version="1.0" encoding="%s" ?>
+
+    The interpolation should be done by client code.
+
+_`html_subtitle`
+    ``parts['html_subtitle']`` contains the document subtitle,
+    including the enclosing ``<h2 class="subtitle">`` & ``</h2>``
+    tags.
+
+_`html_title`
+    ``parts['html_title']`` contains the document title, including the
+    enclosing ``<h1 class="title">`` & ``</h1>`` tags.
+
+_`meta`
+    ``parts['meta']`` contains all ``<meta ... />`` tags.
+
+_`stylesheet`
+    ``parts['stylesheet']`` contains the embedded stylesheet or
+    stylesheet link.
+
+_`subtitle`
+    ``parts['subtitle']`` contains the document subtitle text and any
+    inline markup.  It does not include the enclosing ``<h2>`` &
+    ``</h2>`` tags.
+
+_`title`
+    ``parts['title']`` contains the document title text and any inline
+    markup.  It does not include the enclosing ``<h1>`` & ``</h1>``
+    tags.
+
+
+Parts Provided by the PEP/HTML Writer
+`````````````````````````````````````
+
+The PEP/HTML writer provides the same parts as the `HTML writer`_,
+plus the following:
+
+_`pepnum`
+    ``parts['pepnum']`` contains
+
+
+Parts Provided by the S5/HTML Writer
+````````````````````````````````````
+
+The S5/HTML writer provides the same parts as the `HTML writer`_.
+
+
+Parts Provided by the LaTeX2e Writer
+------------------------------------
+
+See the template files for examples how these parts can be combined
+into a valid LaTeX document.
+
+abstract
+    ``parts['abstract']`` contains the formatted content of the
+    'abstract' docinfo field.
+
+body
+    ``parts['body']`` contains the document's content. In other words, it
+    contains the entire document, except the document title, subtitle, and
+    docinfo.
+
+    This part can be included into another LaTeX document body using the
+    ``\input{}`` command.
+
+body_pre_docinfo
+    ``parts['body_pre_docinfo]`` contains the ``\maketitle`` command.
+
+dedication
+    ``parts['dedication']`` contains the formatted content of the
+    'dedication' docinfo field.
+
+docinfo
+    ``parts['docinfo']`` contains the document bibliographic data, the
+    docinfo field list rendered as a table.
+
+    With ``--use-latex-docinfo`` 'author', 'organization', 'contact',
+    'address' and 'date' info is moved to titledata.
+
+    'dedication' and 'abstract' are always moved to separate parts.
+
+fallbacks
+    ``parts['fallbacks']`` contains fallback definitions for
+    Docutils-specific commands and environments.
+
+head_prefix
+    ``parts['head_prefix']`` contains the declaration of
+    documentclass and document options.
+
+latex_preamble
+    ``parts['latex_preamble']`` contains the argument of the
+    ``--latex-preamble`` option.
+
+pdfsetup
+     ``parts['pdfsetup']`` contains the PDF properties
+     ("hyperref" package setup).
+
+requirements
+    ``parts['requirements']`` contains required packages and setup
+    before the stylesheet inclusion.
+
+stylesheet
+    ``parts['stylesheet']`` contains the embedded stylesheet(s) or
+    stylesheet loading command(s).
+
+subtitle
+    ``parts['subtitle']`` contains the document subtitle text and any
+    inline markup.
+
+title
+    ``parts['title']`` contains the document title text and any inline
+    markup.
+
+titledata
+    ``parts['titledata]`` contains the combined title data in
+    ``\title``, ``\author``, and ``\data`` macros.
+
+    With ``--use-latex-docinfo``, this includes the 'author',
+    'organization', 'contact', 'address' and 'date' docinfo items.

docs/api/runtime-settings.txt

@@ -0,0 +1,192 @@
+===========================
+ Docutils Runtime Settings
+===========================
+
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:Revision: $Revision: 7302 $
+: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):
+
+* The ``settings`` parameter is a runtime settings
+  (``docutils.frontend.Values``) object which, if present, is assumed
+  to be complete (it must include all runtime settings).  Also, if the
+  ``settings`` parameter is present, no further runtime settings
+  processing is done.  In other words, the other parameters, described
+  below, will have no effect.
+
+* ``settings_spec``, a `docutils.SettingsSpec` subclass or object, is
+  treated like a fourth component (after the Parser, Reader, and
+  Writer).  In other words, it's the settings specification for the
+  "Application" itself.
+
+* ``settings_overrides`` is a dictionary which will override the
+  defaults of the components (from their settings specs).
+
+* ``config_section`` specifies the name of 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.py`` 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/config.html
+
+
+Runtime Settings Processing From Applications
+=============================================
+
+Applications process runtime settings in a 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 no command-line processing.  Instead of calling
+``docutils.Publisher.process_command_line`` (as ``publish_cmdline``
+does, via ``docutils.Publisher.publish``),
+``docutils.Publisher.process_programmatic_settings`` is called to set
+up the runtime settings.
+
+.. copy & modify the list from command-line tools?
+
+
+.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop

docs/dev/distributing.txt

@@ -0,0 +1,143 @@
+===============================
+ Docutils_ Distributor's Guide
+===============================
+
+:Author: Lea Wiemann
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 7889 $
+:Date: $Date: 2015-05-08 17:56:32 +0200 (Fr, 08 Mai 2015) $
+:Copyright: This document has been placed in the public domain.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+.. contents::
+
+This document describes how to create packages of Docutils (e.g. for
+shipping with a Linux distribution).  If you have any questions,
+please direct them to the Docutils-develop_ mailing list.
+
+First, please download the most current `release tarball`_ and unpack
+it.
+
+.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
+.. _release tarball: http://docutils.sourceforge.net/#download
+
+
+Dependencies
+============
+
+Docutils has the following dependencies:
+
+* Python 2.4 or later is required.  Use ">= Python 2.4" in the
+  dependencies.
+
+* Docutils may optionally make use of the PIL (`Python Imaging
+  Library`_).  If PIL is present, it is automatically detected by
+  Docutils.
+
+* Docutils recommends the `Pygments`_ syntax hightlighter. If available, it
+  is used for highlighting the content of `code directives`_ and roles as
+  well as included source code files (with the "code" option to the include_
+  directive).
+
+.. _Python Imaging Library: http://www.pythonware.com/products/pil/
+.. _Pygments: http://pygments.org/
+.. _code directives: ../ref/rst/directives.html#code
+.. _include: ../ref/rst/directives.html#include
+
+
+Python Files
+============
+
+The Docutils Python files must be installed into the
+``site-packages/`` directory of Python.  Running ``python setup.py
+install`` should do the trick, but if you want to place the files
+yourself, you can just install the ``docutils/`` directory of the
+Docutils tarball to ``/usr/lib/python/site-packages/docutils/``.  In
+this case you should also compile the Python files to ``.pyc`` and/or
+``.pyo`` files so that Docutils doesn't need to be recompiled every
+time it's executed.
+
+
+Executables
+===========
+
+The executable front-end tools are located in the ``tools/`` directory
+of the Docutils tarball.
+
+The ``rst2*.py`` tools (except ``rst2newlatex.py``) are intended for
+end-users.  You should install them to ``/usr/bin/``.  You do not need
+to change the names (e.g. to ``docutils-rst2html.py``) because the
+``rst2`` prefix is unique.
+
+
+Documentation
+=============
+
+The documentation should be generated using ``buildhtml.py``.  To
+generate HTML for all documentation files, go to the ``tools/``
+directory and run::
+
+    # Place html4css1.css in base directory.
+    cp ../docutils/writers/html4css1/html4css1.css ..
+    ./buildhtml.py --stylesheet-path=../html4css1.css ..
+
+Then install the following files to ``/usr/share/doc/docutils/`` (or
+wherever you install documentation):
+
+* All ``.html`` and ``.txt`` files in the base directory.
+
+* The ``docs/`` directory.
+
+  Do not install the contents of the ``docs/`` directory directly to
+  ``/usr/share/doc/docutils/``; it's incomplete and would contain
+  invalid references!
+
+* The ``licenses/`` directory.
+
+* ``html4css1.css`` in the base directory.
+
+
+Removing the ``.txt`` Files
+---------------------------
+
+If you are tight with disk space, you can remove all ``.txt`` files in
+the tree except for:
+
+* those in the ``licenses/`` directory because they have not been
+  processed to HTML and
+
+* ``user/rst/cheatsheet.txt`` and ``user/rst/demo.txt``, which should
+  be readable in source form.
+
+Before you remove the ``.txt`` files you should rerun ``buildhtml.py``
+with the ``--no-source-link`` switch to avoid broken references to the
+source files.
+
+
+Other Files
+===========
+
+You may want to install the Emacs-Lisp files
+``tools/editors/emacs/*.el`` into the appropriate directory.
+
+
+Configuration File
+==================
+
+It is possible to have a system-wide configuration file at
+``/etc/docutils.conf``.  However, this is usually not necessary.  You
+should *not* install ``tools/docutils.conf`` into ``/etc/``.
+
+
+Tests
+=====
+
+While you probably do not need to ship the tests with your
+distribution, you can test your package by installing it and then
+running ``alltests.py`` from the ``tests/`` directory of the Docutils
+tarball.
+
+For more information on testing, view the `Docutils Testing`_ page.
+
+.. _Docutils Testing: http://docutils.sourceforge.net/docs/dev/testing.html

docs/dev/enthought-plan.txt

@@ -0,0 +1,480 @@
+===========================================
+ Plan for Enthought API Documentation Tool
+===========================================
+
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:Revision: $Revision: 7302 $
+:Copyright: 2004 by `Enthought, Inc. <http://www.enthought.com>`_
+:License: `Enthought License`_ (BSD-style)
+
+.. _Enthought License: http://docutils.sf.net/licenses/enthought.txt
+
+This document should be read in conjunction with the `Enthought API
+Documentation Tool RFP`__ prepared by Janet Swisher.
+
+__ enthought-rfp.html
+
+.. contents::
+.. sectnum::
+
+
+Introduction
+============
+
+In March 2004 at I met Eric Jones, president and CTO of `Enthought,
+Inc.`_, at `PyCon 2004`_ in Washington DC.  He told me that Enthought
+was using reStructuredText_ for source code documentation, but they
+had some issues.  He asked if I'd be interested in doing some work on
+a customized API documentation tool.  Shortly after PyCon, Janet
+Swisher, Enthought's senior technical writer, contacted me to work out
+details.  Some email, a trip to Austin in May, and plenty of Texas
+hospitality later, we had a project.  This document will record the
+details, milestones, and evolution of the project.
+
+In a nutshell, Enthought is sponsoring the implementation of an open
+source API documentation tool that meets their needs.  Fortuitously,
+their needs coincide well with the "Python Source Reader" description
+in `PEP 258`_.  In other words, Enthought is funding some significant
+improvements to Docutils, improvements that were planned but never
+implemented due to time and other constraints.  The implementation
+will take place gradually over several months, on a part-time basis.
+
+This is an ideal example of cooperation between a corporation and an
+open-source project.  The corporation, the project, I personally, and
+the community all benefit.  Enthought, whose commitment to open source
+is also evidenced by their sponsorship of SciPy_, benefits by
+obtaining a useful piece of software, much more quickly than would
+have been possible without their support.  Docutils benefits directly
+from the implementation of one of its core subsystems.  I benefit from
+the funding, which allows me to justify the long hours to my wife and
+family.  All the corporations, projects, and individuals that make up
+the community will benefit from the end result, which will be great.
+
+All that's left now is to actually do the work!
+
+.. _PyCon 2004: http://pycon.org/dc2004/
+.. _reStructuredText: http://docutils.sf.net/rst.html
+.. _SciPy: http://www.scipy.org/
+
+
+Development Plan
+================
+
+1. Analyze prior art, most notably Epydoc_ and HappyDoc_, to see how
+   they do what they do.  I have no desire to reinvent wheels
+   unnecessarily.  I want to take the best ideas from each tool,
+   combined with the outline in `PEP 258`_ (which will evolve), and
+   build at least the foundation of the definitive Python
+   auto-documentation tool.
+
+   .. _Epydoc: http://epydoc.sourceforge.net/
+   .. _HappyDoc: http://happydoc.sourceforge.net/
+   .. _PEP 258:
+      http://docutils.sf.net/docs/peps/pep-0258.html#python-source-reader
+
+2. Decide on a base platform.  The best way to achieve Enthought's
+   goals in a reasonable time frame may be to extend Epydoc or
+   HappyDoc.  Or it may be necessary to start fresh.
+
+3. Extend the reStructuredText parser.  See `Proposed Changes to
+   reStructuredText`_ below.
+
+4. Depending on the base platform chosen, build or extend the
+   docstring & doc comment extraction tool.  This may be the biggest
+   part of the project, but I won't be able to break it down into
+   details until more is known.
+
+
+Repository
+==========
+
+If possible, all software and documentation files will be stored in
+the Subversion repository of Docutils and/or the base project, which
+are all publicly-available via anonymous pserver access.
+
+The Docutils project is very open about granting Subversion write
+access; so far, everyone who asked has been given access.  Any
+Enthought staff member who would like Subversion write access will get
+it.
+
+If either Epydoc or HappyDoc is chosen as the base platform, I will
+ask the project's administrator for CVS access for myself and any
+Enthought staff member who wants it.  If sufficient access is not
+granted -- although I doubt that there would be any problem -- we may
+have to begin a fork, which could be hosted on SourceForge, on
+Enthought's Subversion server, or anywhere else deemed appropriate.
+
+
+Copyright & License
+===================
+
+Most existing Docutils files have been placed in the public domain, as
+follows::
+
+    :Copyright: This document has been placed in the public domain.
+
+This is in conjunction with the "Public Domain Dedication" section of
+COPYING.txt__.
+
+__ http://docutils.sourceforge.net/COPYING.html
+
+The code and documentation originating from Enthought funding will
+have Enthought's copyright and license declaration.  While I will try
+to keep Enthought-specific code and documentation separate from the
+existing files, there will inevitably be cases where it makes the most
+sense to extend existing files.
+
+I propose the following:
+
+1. New files related to this Enthought-funded work will be identified
+   with the following field-list headers::
+
+       :Copyright: 2004 by Enthought, Inc.
+       :License: Enthought License (BSD Style)
+
+   The license field text will be linked to the license file itself.
+
+2. For significant or major changes to an existing file (more than 10%
+   change), the headers shall change as follows (for example)::
+
+       :Copyright: 2001-2004 by David Goodger
+       :Copyright: 2004 by Enthought, Inc.
+       :License: BSD-style
+
+   If the Enthought-funded portion becomes greater than the previously
+   existing portion, Enthought's copyright line will be shown first.
+
+3. In cases of insignificant or minor changes to an existing file
+   (less than 10% change), the public domain status shall remain
+   unchanged.
+
+A section describing all of this will be added to the Docutils
+`COPYING`__ instructions file.
+
+If another project is chosen as the base project, similar changes
+would be made to their files, subject to negotiation.
+
+__ http://docutils.sf.net/COPYING.html
+
+
+Proposed Changes to reStructuredText
+====================================
+
+Doc Comment Syntax
+------------------
+
+The "traits" construct is implemented as dictionaries, where
+standalone strings would be Python syntax errors.  Therefore traits
+require documentation in comments.  We also need a way to
+differentiate between ordinary "internal" comments and documentation
+comments (doc comments).
+
+Javadoc uses the following syntax for doc comments::
+
+    /**
+     * The first line of a multi-line doc comment begins with a slash
+     * and *two* asterisks.  The doc comment ends normally.
+     */
+
+Python doesn't have multi-line comments; only single-line.  A similar
+convention in Python might look like this::
+
+    ##
+    # The first line of a doc comment begins with *two* hash marks.
+    # The doc comment ends with the first non-comment line.
+    'data' : AnyValue,
+
+    ## The double-hash-marks could occur on the first line of text,
+    #  saving a line in the source.
+    'data' : AnyValue,
+
+How to indicate the end of the doc comment? ::
+
+    ##
+    # The first line of a doc comment begins with *two* hash marks.
+    # The doc comment ends with the first non-comment line, or another
+    # double-hash-mark.
+    ##
+    # This is an ordinary, internal, non-doc comment.
+    'data' : AnyValue,
+
+    ## First line of a doc comment, terse syntax.
+    #  Second (and last) line.  Ends here: ##
+    # This is an ordinary, internal, non-doc comment.
+    'data' : AnyValue,
+
+Or do we even need to worry about this case?  A simple blank line
+could be used::
+
+    ## First line of a doc comment, terse syntax.
+    #  Second (and last) line.  Ends with a blank line.
+
+    # This is an ordinary, internal, non-doc comment.
+    'data' : AnyValue,
+
+Other possibilities::
+
+    #" Instead of double-hash-marks, we could use a hash mark and a
+    #  quotation mark to begin the doc comment.
+    'data' : AnyValue,
+
+    ## We could require double-hash-marks on every line.  This has the
+    ## added benefit of delimiting the *end* of the doc comment, as
+    ## well as working well with line wrapping in Emacs
+    ## ("fill-paragraph" command).
+    # Ordinary non-doc comment.
+    'data' : AnyValue,
+
+    #" A hash mark and a quotation mark on each line looks funny, and
+    #" it doesn't work well with line wrapping in Emacs.
+    'data' : AnyValue,
+
+These styles (repeated on each line) work well with line wrapping in
+Emacs::
+
+    ##  #>  #|  #-  #%  #!  #*
+
+These styles do *not* work well with line wrapping in Emacs::
+
+    #"  #'  #:  #)  #.  #/  #@  #$  #^  #=  #+  #_  #~
+
+The style of doc comment indicator used could be a runtime, global
+and/or per-module setting.  That may add more complexity than it's
+worth though.
+
+
+Recommendation
+``````````````
+
+I recommend adopting "#*" on every line::
+
+    # This is an ordinary non-doc comment.
+
+    #* This is a documentation comment, with an asterisk after the
+    #* hash marks on every line.
+    'data' : AnyValue,
+
+I initially recommended adopting double-hash-marks::
+
+    # This is an ordinary non-doc comment.
+
+    ## This is a documentation comment, with double-hash-marks on
+    ## every line.
+    'data' : AnyValue,
+
+But Janet Swisher rightly pointed out that this could collide with
+ordinary comments that are then block-commented.  This applies to
+double-hash-marks on the first line only as well.  So they're out.
+
+On the other hand, the JavaDoc-comment style ("##" on the first line
+only, "#" after that) is used in Fredrik Lundh's PythonDoc_.  It may
+be worthwhile to conform to this syntax, reinforcing it as a standard.
+PythonDoc does not support terse doc comments (text after "##" on the
+first line).
+
+.. _PythonDoc: http://effbot.org/zone/pythondoc.htm
+
+
+Update
+``````
+
+Enthought's Traits system has switched to a metaclass base, and traits
+are now defined via ordinary attributes.  Therefore doc comments are
+no longer absolutely necessary; attribute docstrings will suffice.
+Doc comments may still be desirable though, since they allow
+documentation to precede the thing being documented.
+
+
+Docstring Density & Whitespace Minimization
+-------------------------------------------
+
+One problem with extensively documented classes & functions, is that
+there is a lot of screen space wasted on whitespace.  Here's some
+current Enthought code (from lib/cp/fluids/gassmann.py)::
+
+    def max_gas(temperature, pressure, api, specific_gravity=.56):
+        """
+        Computes the maximum dissolved gas in oil using Batzle and
+        Wang (1992).
+
+        Parameters
+        ----------
+        temperature : sequence
+            Temperature in degrees Celsius
+        pressure : sequence
+            Pressure in MPa
+        api : sequence
+            Stock tank oil API
+        specific_gravity : sequence
+            Specific gravity of gas at STP, default is .56
+
+        Returns
+        -------
+        max_gor : sequence
+            Maximum dissolved gas in liters/liter
+
+        Description
+        -----------
+        This estimate is based on equations given by Mavko, Mukerji,
+        and Dvorkin, (1998, pp. 218-219, or 2003, p. 236) obtained
+        originally from Batzle and Wang (1992).
+        """
+        code...
+
+The docstring is 24 lines long.
+
+Rather than using subsections, field lists (which exist now) can save
+6 lines::
+
+    def max_gas(temperature, pressure, api, specific_gravity=.56):
+        """
+        Computes the maximum dissolved gas in oil using Batzle and
+        Wang (1992).
+
+        :Parameters:
+            temperature : sequence
+                Temperature in degrees Celsius
+            pressure : sequence
+                Pressure in MPa
+            api : sequence
+                Stock tank oil API
+            specific_gravity : sequence
+                Specific gravity of gas at STP, default is .56
+        :Returns:
+            max_gor : sequence
+                Maximum dissolved gas in liters/liter
+        :Description: This estimate is based on equations given by
+            Mavko, Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003,
+            p. 236) obtained originally from Batzle and Wang (1992).
+        """
+        code...
+
+As with the "Description" field above, field bodies may begin on the
+same line as the field name, which also saves space.
+
+The output for field lists is typically a table structure.  For
+example:
+
+    :Parameters:
+        temperature : sequence
+            Temperature in degrees Celsius
+        pressure : sequence
+            Pressure in MPa
+        api : sequence
+            Stock tank oil API
+        specific_gravity : sequence
+            Specific gravity of gas at STP, default is .56
+    :Returns:
+        max_gor : sequence
+            Maximum dissolved gas in liters/liter
+    :Description:
+        This estimate is based on equations given by Mavko,
+        Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003, p. 236)
+        obtained originally from Batzle and Wang (1992).
+
+But the definition lists describing the parameters and return values
+are still wasteful of space.  There are a lot of half-filled lines.
+
+Definition lists are currently defined as::
+
+    term : classifier
+        definition
+
+Where the classifier part is optional.  Ideas for improvements:
+
+1. We could allow multiple classifiers::
+
+       term : classifier one : two : three ...
+           definition
+
+2. We could allow the definition on the same line as the term, using
+   some embedded/inline markup:
+
+   * "--" could be used, but only in limited and well-known contexts::
+
+         term -- definition
+
+     This is the syntax used by StructuredText (one of
+     reStructuredText's predecessors).  It was not adopted for
+     reStructuredText because it is ambiguous -- people often use "--"
+     in their text, as I just did.  But given a constrained context,
+     the ambiguity would be acceptable (or would it?).  That context
+     would be: in docstrings, within a field list, perhaps only with
+     certain well-defined field names (parameters, returns).
+
+   * The "constrained context" above isn't really enough to make the
+     ambiguity acceptable.  Instead, a slightly more verbose but far
+     less ambiguous syntax is possible::
+
+         term === definition
+
+     This syntax has advantages.  Equals signs lend themselves to the
+     connotation of "definition".  And whereas one or two equals signs
+     are commonly used in program code, three equals signs in a row
+     have no conflicting meanings that I know of.  (Update: there
+     *are* uses out there.)
+
+   The problem with this approach is that using inline markup for
+   structure is inherently ambiguous in reStructuredText.  For
+   example, writing *about* definition lists would be difficult::
+
+       ``term === definition`` is an example of a compact definition list item
+
+   The parser checks for structural markup before it does inline
+   markup processing.  But the "===" should be protected by its inline
+   literal context.
+
+3. We could allow the definition on the same line as the term, using
+   structural markup.  A variation on bullet lists would work well::
+
+       : term :: definition
+       : another term :: and a definition that
+         wraps across lines
+
+   Some ambiguity remains::
+
+       : term ``containing :: double colons`` :: definition
+
+   But the likelihood of such cases is negligible, and they can be
+   covered in the documentation.
+
+   Other possibilities for the definition delimiter include::
+
+       : term : classifier -- definition
+       : term : classifier --- definition
+       : term : classifier : : definition
+       : term : classifier === definition
+
+The third idea currently has the best chance of being adopted and
+implemented.
+
+
+Recommendation
+``````````````
+
+Combining these ideas, the function definition becomes::
+
+    def max_gas(temperature, pressure, api, specific_gravity=.56):
+        """
+        Computes the maximum dissolved gas in oil using Batzle and
+        Wang (1992).
+
+        :Parameters:
+            : temperature : sequence :: Temperature in degrees Celsius
+            : pressure : sequence :: Pressure in MPa
+            : api : sequence :: Stock tank oil API
+            : specific_gravity : sequence :: Specific gravity of gas at
+              STP, default is .56
+        :Returns:
+            : max_gor : sequence :: Maximum dissolved gas in liters/liter
+        :Description: This estimate is based on equations given by
+            Mavko, Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003,
+            p. 236) obtained originally from Batzle and Wang (1992).
+        """
+        code...
+
+The docstring is reduced to 14 lines, from the original 24.  For
+longer docstrings with many parameters and return values, the
+difference would be more significant.

docs/dev/enthought-rfp.txt

@@ -0,0 +1,146 @@
+==================================
+ 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://code.enthought.com/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.

docs/dev/hacking.txt

@@ -0,0 +1,264 @@
+==========================
+ Docutils_ Hacker's Guide
+==========================
+
+:Author: Lea Wiemann
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 7302 $
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:Copyright: This document has been placed in the public domain.
+
+:Abstract: This is the introduction to Docutils for all persons who
+    want to extend Docutils in some way.
+:Prerequisites: You have used reStructuredText_ and played around with
+    the `Docutils front-end tools`_ before.  Some (basic) Python
+    knowledge is certainly helpful (though not necessary, strictly
+    speaking).
+
+.. _Docutils: http://docutils.sourceforge.net/
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _Docutils front-end tools: ../user/tools.html
+
+.. contents::
+
+
+Overview of the Docutils Architecture
+=====================================
+
+To give you an understanding of the Docutils architecture, we'll dive
+right into the internals using a practical example.
+
+Consider the following reStructuredText file::
+
+    My *favorite* language is Python_.
+
+    .. _Python: http://www.python.org/
+
+Using the ``rst2html.py`` front-end tool, you would get an HTML output
+which looks like this::
+
+    [uninteresting HTML code removed]
+    <body>
+    <div class="document">
+    <p>My <em>favorite</em> language is <a class="reference" href="http://www.python.org/">Python</a>.</p>
+    </div>
+    </body>
+    </html>
+
+While this looks very simple, it's enough to illustrate all internal
+processing stages of Docutils.  Let's see how this document is
+processed from the reStructuredText source to the final HTML output:
+
+
+Reading the Document
+--------------------
+
+The **Reader** reads the document from the source file and passes it
+to the parser (see below).  The default reader is the standalone
+reader (``docutils/readers/standalone.py``) which just reads the input
+data from a single text file.  Unless you want to do really fancy
+things, there is no need to change that.
+
+Since you probably won't need to touch readers, we will just move on
+to the next stage:
+
+
+Parsing the Document
+--------------------
+
+The **Parser** analyzes the the input document and creates a **node
+tree** representation.  In this case we are using the
+**reStructuredText parser** (``docutils/parsers/rst/__init__.py``).
+To see what that node tree looks like, we call ``quicktest.py`` (which
+can be found in the ``tools/`` directory of the Docutils distribution)
+with our example file (``test.txt``) as first parameter (Windows users
+might need to type ``python quicktest.py test.txt``)::
+
+    $ quicktest.py test.txt
+    <document source="test.txt">
+        <paragraph>
+            My
+            <emphasis>
+                favorite
+             language is
+            <reference name="Python" refname="python">
+                Python
+            .
+        <target ids="python" names="python" refuri="http://www.python.org/">
+
+Let us now examine the node tree:
+
+The top-level node is ``document``.  It has a ``source`` attribute
+whose value is ``text.txt``.  There are two children: A ``paragraph``
+node and a ``target`` node.  The ``paragraph`` in turn has children: A
+text node ("My "), an ``emphasis`` node, a text node (" language is "),
+a ``reference`` node, and again a ``Text`` node (".").
+
+These node types (``document``, ``paragraph``, ``emphasis``, etc.) are
+all defined in ``docutils/nodes.py``.  The node types are internally
+arranged as a class hierarchy (for example, both ``emphasis`` and
+``reference`` have the common superclass ``Inline``).  To get an
+overview of the node class hierarchy, use epydoc (type ``epydoc
+nodes.py``) and look at the class hierarchy tree.
+
+
+Transforming the Document
+-------------------------
+
+In the node tree above, the ``reference`` node does not contain the
+target URI (``http://www.python.org/``) yet.
+
+Assigning the target URI (from the ``target`` node) to the
+``reference`` node is *not* done by the parser (the parser only
+translates the input document into a node tree).
+
+Instead, it's done by a **Transform**.  In this case (resolving a
+reference), it's done by the ``ExternalTargets`` transform in
+``docutils/transforms/references.py``.
+
+In fact, there are quite a lot of Transforms, which do various useful
+things like creating the table of contents, applying substitution
+references or resolving auto-numbered footnotes.
+
+The Transforms are applied after parsing.  To see how the node tree
+has changed after applying the Transforms, we use the
+``rst2pseudoxml.py`` tool:
+
+.. parsed-literal::
+
+    $ rst2pseudoxml.py test.txt
+    <document source="test.txt">
+        <paragraph>
+            My
+            <emphasis>
+                favorite
+             language is
+            <reference name="Python" **refuri="http://www.python.org/"**>
+                Python
+            .
+        <target ids="python" names="python" ``refuri="http://www.python.org/"``>
+
+For our small test document, the only change is that the ``refname``
+attribute of the reference has been replaced by a ``refuri``
+attribute |---| the reference has been resolved.
+
+While this does not look very exciting, transforms are a powerful tool
+to apply any kind of transformation on the node tree.
+
+By the way, you can also get a "real" XML representation of the node
+tree by using ``rst2xml.py`` instead of ``rst2pseudoxml.py``.
+
+
+Writing the Document
+--------------------
+
+To get an HTML document out of the node tree, we use a **Writer**, the
+HTML writer in this case (``docutils/writers/html4css1.py``).
+
+The writer receives the node tree and returns the output document.
+For HTML output, we can test this using the ``rst2html.py`` tool::
+
+    $ rst2html.py --link-stylesheet test.txt
+    <?xml version="1.0" encoding="utf-8" ?>
+    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+    <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+    <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <meta name="generator" content="Docutils 0.3.10: http://docutils.sourceforge.net/" />
+    <title></title>
+    <link rel="stylesheet" href="../docutils/writers/html4css1/html4css1.css" type="text/css" />
+    </head>
+    <body>
+    <div class="document">
+    <p>My <em>favorite</em> language is <a class="reference" href="http://www.python.org/">Python</a>.</p>
+    </div>
+    </body>
+    </html>
+
+So here we finally have our HTML output.  The actual document contents
+are in the fourth-last line.  Note, by the way, that the HTML writer
+did not render the (invisible) ``target`` node |---| only the
+``paragraph`` node and its children appear in the HTML output.
+
+
+Extending Docutils
+==================
+
+Now you'll ask, "how do I actually extend Docutils?"
+
+First of all, once you are clear about *what* you want to achieve, you
+have to decide *where* to implement it |---| in the Parser (e.g. by
+adding a directive or role to the reStructuredText parser), as a
+Transform, or in the Writer.  There is often one obvious choice among
+those three (Parser, Transform, Writer).  If you are unsure, ask on
+the Docutils-develop_ mailing list.
+
+In order to find out how to start, it is often helpful to look at
+similar features which are already implemented.  For example, if you
+want to add a new directive to the reStructuredText parser, look at
+the implementation of a similar directive in
+``docutils/parsers/rst/directives/``.
+
+
+Modifying the Document Tree Before It Is Written
+------------------------------------------------
+
+You can modify the document tree right before the writer is called.
+One possibility is to use the publish_doctree_ and
+publish_from_doctree_ functions.
+
+To retrieve the document tree, call::
+
+    document = docutils.core.publish_doctree(...)
+
+Please see the docstring of publish_doctree for a list of parameters.
+
+.. XXX Need to write a well-readable list of (commonly used) options
+   of the publish_* functions.  Probably in api/publisher.txt.
+
+``document`` is the root node of the document tree.  You can now
+change the document by accessing the ``document`` node and its
+children |---| see `The Node Interface`_ below.
+
+When you're done with modifying the document tree, you can write it
+out by calling::
+
+    output = docutils.core.publish_from_doctree(document, ...)
+
+.. _publish_doctree: ../api/publisher.html#publish_doctree
+.. _publish_from_doctree: ../api/publisher.html#publish_from_doctree
+
+
+The Node Interface
+------------------
+
+As described in the overview above, Docutils' internal representation
+of a document is a tree of nodes.  We'll now have a look at the
+interface of these nodes.
+
+(To be completed.)
+
+
+What Now?
+=========
+
+This document is not complete.  Many topics could (and should) be
+covered here.  To find out with which topics we should write about
+first, we are awaiting *your* feedback.  So please ask your questions
+on the Docutils-develop_ mailing list.
+
+
+.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
+
+
+.. |---| unicode:: 8212 .. em-dash
+   :trim:
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

docs/dev/policies.txt

@@ -0,0 +1,652 @@
+===========================
+ Docutils Project Policies
+===========================
+
+:Author: David Goodger; open to all Docutils developers
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date: 2017-06-23 01:26:18 +0200 (Fr, 23 Jun 2017) $
+:Revision: $Revision: 8123 $
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+The Docutils project group is a meritocracy based on code contribution
+and lots of discussion [#bcs]_.  A few quotes sum up the policies of
+the Docutils project.  The IETF's classic credo (by MIT professor Dave
+Clark) is an ideal we can aspire to:
+
+    We reject: kings, presidents, and voting.  We believe in: rough
+    consensus and running code.
+
+As architect, chief cook and bottle-washer, David Goodger currently
+functions as BDFN (Benevolent Dictator For Now).  (But he would
+happily abdicate the throne given a suitable candidate.  Any takers?)
+
+Eric S. Raymond, anthropologist of the hacker subculture, writes in
+his essay `The Magic Cauldron`_:
+
+    The number of contributors [to] projects is strongly and inversely
+    correlated with the number of hoops each project makes a user go
+    through to contribute.
+
+We will endeavour to keep the barrier to entry as low as possible.
+The policies below should not be thought of as barriers, but merely as
+a codification of experience to date.  These are "best practices";
+guidelines, not absolutes.  Exceptions are expected, tolerated, and
+used as a source of improvement.  Feedback and criticism is welcome.
+
+As for control issues, Emmett Plant (CEO of the Xiph.org Foundation,
+originators of Ogg Vorbis) put it well when he said:
+
+    Open source dictates that you lose a certain amount of control
+    over your codebase, and that's okay with us.
+
+.. [#bcs] Phrase borrowed from `Ben Collins-Sussman of the Subversion
+   project <http://www.red-bean.com/sussman/svn-anti-fud.html>`__.
+
+.. _The Magic Cauldron:
+   http://www.catb.org/~esr/writings/magic-cauldron/
+
+
+How to get a new feature into Docutils
+========================================
+
+Question:
+   I would very much like to have this new feature in the Docutils core.
+   What exactly do I have to do to make this possible?
+
+* Present your idea at the Docutils-develop_ mailing list,
+
+  +1  usually triggers a fast response,
+  -1  may be forgotten later,
+
+  and/or file a ticket at Docutils' `feature request tracker`_.
+
+  +1  there is a permanent record,
+  -1  it may stay forgotten among all the other feature requests.
+
+* Convince a Docutils developer that this is a valuable addition worth the
+  effort.
+
+* Contribute. The developers will make sure that the contribution fits
+  nicely into Docutils (cf. the `review criteria`_). This might involve
+  discussing (and compromising on) design and implementation details. It
+  might also lead to the conclusion that the addition fits better in the
+  `extensions and related projects`_.
+
+* Be patient, and be persistent.  None of us are paid to do this,
+  it's all in our spare time -- which is precious and rare.
+
+How to make code contributions that are easily accepted:
+
+* Have a look at the `Python coding conventions`_ and `documentation
+  conventions`_ below.
+
+* **Prepare test cases.** This vastly helps when integrating new code. Test
+  cases are also examples and showcases for new features. See `Docutils
+  Testing`_ for a description of the test suite in ``docutils/test/``.
+
+  Ensure the addition works with all `supported Python versions`__.
+
+  __ ../../README.html#requirements
+
+* Look at the Docutils sources to see how similar features are implemented,
+  learn to do it "the Docutils way".
+
+* Prepare the a patch or an addition to the existing documentation.
+  Include links.
+
+* If you are familiar with version control, consider creating a `feature
+  branch`_ in a Docutils repository_ checkout. (Working with branches is
+  *much* easier with git_. You can get a git clone of the repository from
+  http://repo.or.cz/w/docutils.git or with git-svn.)
+
+.. _docutils-develop: ../user/mailing-lists.html#docutils-develop
+.. _feature request tracker:
+   http://sourceforge.net/p/docutils/feature-requests/
+
+.. _git: http://git-scm.com/
+.. _Docutils testing: testing.html
+
+
+Python Coding Conventions
+=========================
+
+Contributed code will not be refused merely because it does not
+strictly adhere to these conditions; as long as it's internally
+consistent, clean, and correct, it probably will be accepted.  But
+don't be surprised if the "offending" code gets fiddled over time to
+conform to these conventions.
+
+The Docutils project shall follow the generic coding conventions as
+specified in the `Style Guide for Python Code`_ and `Docstring
+Conventions`_ PEPs, summarized, clarified, and extended as follows:
+
+* 4 spaces per indentation level.  No hard tabs.
+
+* Use only 7-bit ASCII, no 8-bit strings.  See `Docutils
+  Internationalization`_.
+
+* No one-liner compound statements (i.e., no ``if x: return``: use two
+  lines & indentation), except for degenerate class or method
+  definitions (i.e., ``class X: pass`` is OK.).
+
+* Lines should be no more than 78 characters long.
+
+* Use "StudlyCaps" for class names (except for element classes in
+  docutils.nodes).
+
+* Use "lowercase" or "lowercase_with_underscores" for function,
+  method, and variable names.  For short names, maximum two words,
+  joined lowercase may be used (e.g. "tagname").  For long names with
+  three or more words, or where it's hard to parse the split between
+  two words, use lowercase_with_underscores (e.g.,
+  "note_explicit_target", "explicit_target").  If in doubt, use
+  underscores.
+
+* Avoid lambda expressions, which are inherently difficult to
+  understand.  Named functions are preferable and superior: they're
+  faster (no run-time compilation), and well-chosen names serve to
+  document and aid understanding.
+
+* Avoid functional constructs (filter, map, etc.).  Use list
+  comprehensions instead.
+
+* Avoid ``from __future__ import`` constructs.  They are inappropriate
+  for production code.
+
+* Use 'single quotes' for string literals, and """triple double
+  quotes""" for docstrings.
+
+.. _Style Guide for Python Code:
+   http://www.python.org/peps/pep-0008.html
+.. _Docstring Conventions: http://www.python.org/peps/pep-0257.html
+.. _Docutils Internationalization: ../howto/i18n.html#python-code
+
+
+Documentation Conventions
+=========================
+
+* Docutils documentation is written using reStructuredText, of course.
+
+* Use 7-bit ASCII if at all possible, and Unicode substitutions when
+  necessary.
+
+* Use the following section title adornment styles::
+
+      ================
+       Document Title
+      ================
+
+      --------------------------------------------
+       Document Subtitle, or Major Division Title
+      --------------------------------------------
+
+      Section
+      =======
+
+      Subsection
+      ----------
+
+      Sub-Subsection
+      ``````````````
+
+      Sub-Sub-Subsection
+      ..................
+
+* Use two blank lines before each section/subsection/etc. title.  One
+  blank line is sufficient between immediately adjacent titles.
+
+* Add a bibliographic field list immediately after the document
+  title/subtitle.  See the beginning of this document for an example.
+
+* Add an Emacs "local variables" block in a comment at the end of the
+  document.  See the end of this document for an example.
+
+
+Copyrights and Licensing
+========================
+
+The majority of the Docutils project code and documentation has been
+placed in the public domain.  Unless clearly and explicitly indicated
+otherwise, any patches (modifications to existing files) submitted to
+the project for inclusion (via Subversion, SourceForge trackers,
+mailing lists, or private email) are assumed to be in the public
+domain as well.
+
+Any new files contributed to the project should clearly state their
+intentions regarding copyright, in one of the following ways:
+
+* Public domain (preferred): include the statement "This
+  module/document has been placed in the public domain."
+
+* Copyright & open source license: include a copyright notice, along
+  with either an embedded license statement, a reference to an
+  accompanying license file, or a license URL.
+
+  The license should be well known, simple and compatible with other
+  open source software licenses. To keep the number of different
+  licenses at a minimum, using the `2-Clause BSD license`_
+  is recommended.
+
+2-Clause BSD license
+--------------------
+
+(also known as "Simplified" or `FreeBSD license`)
+
+  If you want a simple, permissive non-copyleft free software license, the
+  FreeBSD license is a reasonable choice. However, please don't call it a
+  “BSD” or “BSD-style” license, because that is likely to cause confusion
+  which could lead to use of the flawed original BSD license.
+
+  -- `Various Licenses and Comments about Them`_
+
+Pros:
+  * clear wording, structured text
+  * license used by the closely related Sphinx project
+  * "2-Clause BSD license" is a non-ambiguous name, used by both, OSI and
+    GNU.
+
+References:
+  * http://www.freebsd.org/copyright/freebsd-license.html
+  * http://www.opensource.org/licenses/BSD-2-Clause
+  * http://www.spdx.org/licenses/BSD-2-Clause
+
+.. _Various Licenses and Comments about Them:
+   http://www.gnu.org/licenses/license-list.html
+.. _OSI Approved Licenses: http://www.opensource.org/licenses/category
+.. _SPDX Open Source License Registry: http://www.spdx.org/licenses/
+
+
+.. _Subversion Repository:
+
+Repository
+==========
+
+Please see the `repository documentation`_ for details on how to
+access Docutils' Subversion repository.  Anyone can access the
+repository anonymously.  Only project developers can make changes.
+(If you would like to become a project developer, just ask!)  Also see
+`Setting Up For Docutils Development`_ below for some useful info.
+
+Unless you really *really* know what you're doing, please do *not* use
+``svn import``.  It's quite easy to mess up the repository with an
+import.
+
+.. _repository documentation: repository.html
+
+
+Branches
+--------
+
+(These branch policies go into effect with Docutils 0.4.)
+
+The "docutils" directory of the **trunk** (a.k.a. the **Docutils
+core**) is used for active -- but stable, fully tested, and reviewed
+-- development.
+
+If we need to cut a bugfix release, we'll create a **maintenance branch**
+based on the latest feature release.  For example, when Docutils 0.5 is
+released, this would be ``branches/docutils-0.5``, any existing 0.4.x
+maintenance branches may be retired.  Maintenance branches will receive bug
+fixes only; no new features will be allowed here.
+
+Obvious and uncontroversial bug fixes *with tests* can be checked in
+directly to the core and to the maintenance branches.  Don't forget to
+add test cases!  Many (but not all) bug fixes will be applicable both
+to the core and to the maintenance branches; these should be applied
+to both.  No patches or dedicated branches are required for bug fixes,
+but they may be used.  It is up to the discretion of project
+developers to decide which mechanism to use for each case.
+
+.. _feature branches:
+.. _feature branch:
+
+Feature additions and API changes will be done in **feature
+branches**.  Feature branches will not be managed in any way.
+Frequent small checkins are encouraged here.  Feature branches must be
+discussed on the `docutils-develop mailing list`_ and reviewed before
+being merged into the core.
+
+.. _docutils-develop mailing list:
+   http://lists.sourceforge.net/lists/listinfo/docutils-develop
+
+
+Review Criteria
+```````````````
+
+Before a new feature, an API change, or a complex, disruptive, or
+controversial bug fix can be checked in to the core or into a
+maintenance branch, it must undergo review.  These are the criteria:
+
+* The branch must be complete, and include full documentation and
+  tests.
+
+* There should ideally be one branch merge commit per feature or
+  change.  In other words, each branch merge should represent a
+  coherent change set.
+
+* The code must be stable and uncontroversial.  Moving targets and
+  features under debate are not ready to be merged.
+
+* The code must work.  The test suite must complete with no failures.
+  See `Docutils Testing`_.
+
+The review process will ensure that at least one other set of eyeballs
+& brains sees the code before it enters the core.  In addition to the
+above, the general `Check-ins`_ policy (below) also applies.
+
+
+Check-ins
+---------
+
+Changes or additions to the Docutils core and maintenance branches
+carry a commitment to the Docutils user community.  Developers must be
+prepared to fix and maintain any code they have committed.
+
+The Docutils core (``trunk/docutils`` directory) and maintenance
+branches should always be kept in a stable state (usable and as
+problem-free as possible).  All changes to the Docutils core or
+maintenance branches must be in `good shape`_, usable_, documented_,
+tested_, and `reasonably complete`_.
+
+* _`Good shape` means that the code is clean, readable, and free of
+  junk code (unused legacy code; by analogy to "junk DNA").
+
+* _`Usable` means that the code does what it claims to do.  An "XYZ
+  Writer" should produce reasonable XYZ output.
+
+* _`Documented`: The more complete the documentation the better.
+  Modules & files must be at least minimally documented internally.
+  `Docutils Front-End Tools`_ should have a new section for any
+  front-end tool that is added.  `Docutils Configuration Files`_
+  should be modified with any settings/options defined.  For any
+  non-trivial change, the HISTORY.txt_ file should be updated.
+
+* _`Tested` means that unit and/or functional tests, that catch all
+  bugs fixed and/or cover all new functionality, have been added to
+  the test suite.  These tests must be checked by running the test
+  suite under all supported Python versions, and the entire test suite
+  must pass.  See `Docutils Testing`_.
+
+* _`Reasonably complete` means that the code must handle all input.
+  Here "handle" means that no input can cause the code to fail (cause
+  an exception, or silently and incorrectly produce nothing).
+  "Reasonably complete" does not mean "finished" (no work left to be
+  done).  For example, a writer must handle every standard element
+  from the Docutils document model; for unimplemented elements, it
+  must *at the very least* warn that "Output for element X is not yet
+  implemented in writer Y".
+
+If you really want to check code directly into the Docutils core,
+you can, but you must ensure that it fulfills the above criteria
+first.  People will start to use it and they will expect it to work!
+If there are any issues with your code, or if you only have time for
+gradual development, you should put it on a branch or in the sandbox
+first.  It's easy to move code over to the Docutils core once it's
+complete.
+
+It is the responsibility and obligation of all developers to keep the
+Docutils core and maintenance branches stable.  If a commit is made to
+the core or maintenance branch which breaks any test, the solution is
+simply to revert the change.  This is not vindictive; it's practical.
+We revert first, and discuss later.
+
+Docutils will pursue an open and trusting policy for as long as
+possible, and deal with any aberrations if (and hopefully not when)
+they happen.  We'd rather see a torrent of loose contributions than
+just a trickle of perfect-as-they-stand changes.  The occasional
+mistake is easy to fix.  That's what version control is for!
+
+.. _Docutils Front-End Tools: ../user/tools.html
+.. _Docutils Configuration Files: ../user/config.html
+.. _HISTORY.txt: ../../HISTORY.txt
+
+
+Version Numbering
+=================
+
+Docutils version numbering uses a ``major.minor.micro`` scheme (x.y.z;
+for example, 0.4.1).
+
+**Major releases** (x.0, e.g. 1.0) will be rare, and will represent major
+changes in API, functionality, or commitment.  When Docutils reaches version
+1.0, the major APIs will be considered frozen and backward compatibility
+will become of paramount importance.
+
+Releases that change the minor number (x.y, e.g. 0.5) will be
+**feature releases**; new features from the `Docutils core`_ will be
+included.
+
+Releases that change the micro number (x.y.z, e.g. 0.4.1) will be
+**bug-fix releases**.  No new features will be introduced in these
+releases; only bug fixes will be included.
+
+This policy was adopted in October 2005, and will take effect with
+Docutils version 0.4.  Prior to version 0.4, Docutils didn't have an
+official version numbering policy, and micro releases contained both
+bug fixes and new features.
+
+See also the `Docutils Release Procedure`_, `docutils.__version__` and
+`docutils.__version_info__`.
+
+.. _Docutils Release Procedure: release.html#version-numbers
+
+Snapshots
+=========
+
+Snapshot tarballs can be downloaded from the repository (see the "download
+snapshot" button in the head of the code listing table).
+
+* the `Docutils core`_, representing the current cutting-edge state of
+  development;
+
+* the `sandbox directory`_ with contributed projects and extensions from
+  `the Sandbox`_;
+
+.. * maintenance branches, for bug fixes;
+
+   TODO: do we have active maintenance branches?
+   (the only branch looking like a maintenance branch is
+   http://sourceforge.net/p/docutils/code/HEAD/tree/branches/docutils-0.4)
+
+* `development branches`_, representing ongoing development efforts to bring
+  new features into Docutils.
+
+.. _Docutils core:
+   http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils
+.. _development branches:
+   http://sourceforge.net/p/docutils/code/HEAD/tree/branches/
+
+
+Setting Up For Docutils Development
+===================================
+
+When making changes to the code, testing is a must.  The code should
+be run to verify that it produces the expected results, and the entire
+test suite should be run too.  The modified Docutils code has to be
+accessible to Python for the tests to have any meaning.  There are two
+ways to keep the Docutils code accessible during development:
+
+1. Update your ``PYTHONPATH`` environment variable so that Python
+   picks up your local working copy of the code.  This is the
+   recommended method.
+
+   We'll assume that the Docutils trunk is checked out under your
+   ~/projects/ directory as follows::
+
+       svn co https://<user>@docutils.svn.sourceforge.net/svnroot/docutils/trunk \
+           docutils
+
+   For the bash shell, add this to your ``~/.profile``::
+
+       PYTHONPATH=$HOME/projects/docutils/docutils
+       PYTHONPATH=$PYTHONPATH:$HOME/projects/docutils/docutils/extras
+       export PYTHONPATH
+
+   The first line points to the directory containing the ``docutils``
+   package.  The second line adds the directory containing the
+   third-party modules Docutils depends on.  The third line exports
+   this environment variable.  You may also wish to add the ``tools``
+   directory to your ``PATH``::
+
+       PATH=$PATH:$HOME/projects/docutils/docutils/tools
+       export PATH
+
+2. Before you run anything, every time you make a change, reinstall
+   Docutils::
+
+       python setup.py install
+
+   .. CAUTION::
+
+      This method is **not** recommended for day-to-day development;
+      it's too easy to forget.  Confusion inevitably ensues.
+
+      If you install Docutils this way, Python will always pick up the
+      last-installed copy of the code.  If you ever forget to
+      reinstall the "docutils" package, Python won't see your latest
+      changes.
+
+A useful addition to the ``docutils`` top-level directory in branches
+and alternate copies of the code is a ``set-PATHS`` file
+containing the following lines::
+
+    # source this file
+    export PYTHONPATH=$PWD:$PWD/extras
+    export PATH=$PWD/tools:$PATH
+
+Open a shell for this branch, ``cd`` to the ``docutils`` top-level
+directory, and "source" this file.  For example, using the bash
+shell::
+
+    $ cd some-branch/docutils
+    $ . set-PATHS
+
+
+Mailing Lists
+=============
+
+Developers are recommended to subscribe to all `Docutils mailing
+lists`_.
+
+.. _Docutils mailing lists: ../user/mailing-lists.html
+
+
+The Wiki
+========
+
+There is a development wiki at http://docutils.python-hosting.com/ as
+a scratchpad for transient notes.  Please use the repository for
+permament document storage.
+
+Extensions and Related Projects
+===============================
+
+The Sandbox
+-----------
+
+The `sandbox directory`_ is a place to play around, to try out and
+share ideas.  It's a part of the Subversion repository but it isn't
+distributed as part of Docutils releases.  Feel free to check in code
+to the sandbox; that way people can try it out but you won't have to
+worry about it working 100% error-free, as is the goal of the Docutils
+core.  A project-specific subdirectory should be created for each new
+project.  Any developer who wants to play in the sandbox may do so,
+but project directories are recommended over personal directories,
+which discourage collaboration.  It's OK to make a mess in the
+sandbox!  But please, play nice.
+
+Please update the `sandbox README`_ file with links and a brief
+description of your work.
+
+In order to minimize the work necessary for others to install and try
+out new, experimental components, the following sandbox directory
+structure is recommended::
+
+    sandbox/
+        project_name/ # For a collaborative project.
+            README.txt  # Describe the requirements, purpose/goals, usage,
+                        # and list the maintainers.
+            docs/
+                ...
+            component.py    # The component is a single module.
+                            # *OR* (but *not* both)
+            component/      # The component is a package.
+                __init__.py  # Contains the Reader/Writer class.
+                other1.py    # Other modules and data files used
+                data.txt     # by this component.
+                ...
+            test/       # Test suite.
+                ...
+            tools/      # For front ends etc.
+                ...
+            setup.py    # Use Distutils to install the component
+                        # code and tools/ files into the right
+                        # places in Docutils.
+        userid/       # For *temporary* personal space.
+
+Some sandbox projects are destined to move to the Docutils core once
+completed.  Others, such as add-ons to Docutils or applications of
+Docutils, may graduate to become `parallel projects`_.
+
+.. _sandbox README: http://docutils.sf.net/sandbox/README.html
+.. _sandbox directory:
+   http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/
+
+
+.. _parallel project:
+
+Parallel Projects
+-----------------
+
+Parallel projects contain useful code that is not central to the
+functioning of Docutils.  Examples are specialized add-ons or
+plug-ins, and applications of Docutils.  They use Docutils, but
+Docutils does not require their presence to function.
+
+An official parallel project will have its own directory beside (or
+parallel to) the main ``docutils`` directory in the Subversion
+repository.  It can have its own web page in the
+docutils.sourceforge.net domain, its own file releases and
+downloadable snapshots, and even a mailing list if that proves useful.
+However, an official parallel project has implications: it is expected
+to be maintained and continue to work with changes to the core
+Docutils.
+
+A parallel project requires a project leader, who must commit to
+coordinate and maintain the implementation:
+
+* Answer questions from users and developers.
+* Review suggestions, bug reports, and patches.
+* Monitor changes and ensure the quality of the code and
+  documentation.
+* Coordinate with Docutils to ensure interoperability.
+* Put together official project releases.
+
+Of course, related projects may be created independently of Docutils.
+The advantage of a parallel project is that the SourceForge
+environment and the developer and user communities are already
+established.  Core Docutils developers are available for consultation
+and may contribute to the parallel project.  It's easier to keep the
+projects in sync when there are changes made to the core Docutils
+code.
+
+Other related projects
+----------------------
+
+Many related but independent projects are listed in the Docutils
+`link list`_. If you want your project to appear there, drop a note at
+the Docutils-develop_ mailing list.
+
+.. _link list: http://docutils.sourceforge.net/docs/user/links.html
+
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

docs/dev/pysource.dtd

@@ -0,0 +1,260 @@
+<!--
+======================================================================
+    Docutils Python Source DTD
+======================================================================
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 7302 $
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+: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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-->
+
+<!-- package's namespace == __init__.py module's namespace -->
+<!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:
+-->

docs/dev/pysource.txt

@@ -0,0 +1,130 @@
+======================
+ Python Source Reader
+======================
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 7302 $
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+: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:

docs/dev/release.txt

@@ -0,0 +1,292 @@
+=============================
+ Docutils_ Release Procedure
+=============================
+
+:Authors: David Goodger; Lea Wiemann; open to all Docutils developers
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date: 2017-08-03 11:00:21 +0200 (Do, 03 Aug 2017) $
+:Revision: $Revision: 8146 $
+:Copyright: This document has been placed in the public domain.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+Assumptions and their failure
+-----------------------------
+
+On the test machine python2.4, 2.5, 2.6, 2.7 and 3.2, 3.3, and 3.4
+are installed.
+Some in /usr/ some under /usr/local.
+
+Assumption: If python2.6 is in /usr/bin/ then site-packages is under
+/usr/local/lib/python2.6.
+
+On new ubuntu 12.10
+
+* python2.7 is here /usr/bin/python2.7.
+* in /usr/lib are python2.7, pymodules and pyshared.
+
+  in /usr/lib/python2.7 no site-packages directory even after installation
+  of docutils
+
+  in /usr/local/lib/python2.7 are dist-packages  site-packages.
+
+  site-packages is empty.
+
+  docutils is installed under dist-packages.
+
+  pymodules has a python2.7 directory.
+
+Releasing
+---------
+
+Version numbers
+~~~~~~~~~~~~~~~
+
+Version numbers shall follow the `Docutils Project Policies`_ and comply
+with `PEP 440`_.
+
+Especially, mark pre-releases and the repository version/snapshots as
+"between" releases (cf. `Feature Request #50`_ and the discussion on
+docutils-devel on May 28 2017), e.g.
+
+|  prev. release  0.13.1,
+|  prerelease     0.14rc1,
+| [prereleases    0.14rc2, ...]
+|  release        0.14,
+|  repo/snapshots 0.15.dev
+| [bugfix relases 0.14.1, ...]  # branches off of the 0.14 release.
+
+The repository version number is always equal to the last released
+version + 1, with a .dev suffix: ``<major>.<minor+1>.dev``.
+(Exception: during "feature freeze" between pre-release and release it may
+point to the next pre-release.)
+
+.. _Docutils Project Policies: policies.html#version-numbers
+.. _Feature Request #50: https://sourceforge.net/p/docutils/feature-requests/50/
+.. _PEP 440: https://www.python.org/dev/peps/pep-0440/
+
+Release steps
+~~~~~~~~~~~~~
+
+REWORK FOR SOURCEFORGE REPO
+
+
+.. WARNING:: Steps in boldface text are *not* covered by the release script
+   at sandbox/infrastructure/release.sh.  "Not covered" means that you
+   aren't even reminded of them.
+
+.. Note:: This document does not cover branching and tagging, but the
+   release script does.
+
+.. Note:: You may want to use ReleaseForge_ instead of using
+   SourceForge's file release system.
+
+   .. _ReleaseForge: http://releaseforge.sourceforge.net/
+
+
+* **On the Docutils-develop mailing list, announce that the release is
+  going to be made, update the release notes and ask for additions.**
+
+  **Announce the date of the feature freeze, at least a week away.**
+
+  Consult HISTORY.TXT for changes.
+
+* **Announce a check-in freeze on Docutils-develop.**
+
+* **Announce the upcoming release at the Sphinx-devel mailing list
+  and ask for testing with Sphinx.**
+  (This step can be skipped for bugfix releases.)
+
+* update `version numbers`_:
+
+  We want pre-release tags ``rcN`` for pre-releases, development release tag
+  ``.dev`` for snapshots and installs from the repository.
+
+  For a prerelease
+
+  0. before release ``<next-release-number>.dev``
+  1. set this to ``<next-release-number>.rc1``
+  2. release
+  3. increase prerelease number in the repository
+
+  For a release
+
+  0. before release ``<next-release-number>.dev`` or
+     ``<next-release-number>.rc<N>``
+  1. set this to ``<next-release-number>`` without prerelease character.
+  2. release
+  3. set to ``<major>.<minor+1>.dev`` in the repository (trunk).
+
+  see what ``sandbox/infrastructure/release.sh`` can aid
+
+  Call ``sandbox/infrastructure/set_release.sh new_version``.
+  For details see the script.
+
+  ``new_version`` is major.minor[.micro][<pre>][.dev]
+
+  .. Note:: *BUG* test tarball requires root password, but it is possible to
+     skip this stage interactively, and testing should be done before
+     release.
+
+* Change ``__version_details__`` in docutils/docutils/__init__.py to
+  "release" (from "repository").
+
+* Check the _`version number` in the following files, should be already
+  correct:
+
+  + docutils/setup.py
+  + docutils/docutils/__init__.py
+  + docutils/test/functional/expected/* ("Generator: Docutils X.Y[.Z]")
+  + docutils/README.txt
+  + web/index.txt
+
+* Close the "Changes Since ..." section in docutils/HISTORY.txt.
+
+* Clear/unset the PYTHONPATH environment variable.
+
+* Create the release tarball:
+
+  (a) Create a new empty directory and ``cd`` into it.
+
+  (b) Get a clean snapshot of the main tree::
+
+          svn export svn://svn.code.sf.net/p/docutils/code/trunk/docutils
+
+      or via the [Download Snapshot] button at
+      http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
+
+  (c) Use Distutils to create the release tarball::
+
+          cd docutils
+          python setup.py sdist
+
+* Expand and _`install` the release tarball in isolation:
+
+  (a) Expand the tarball in a new location, not over any existing
+      files.
+
+  (b) Remove the old installation from site-packages (including
+      roman.py, and optparse.py, textwrap.py).
+
+      "remove" might fail, see _`Assumptions and their failure`
+
+      Install from expanded directory::
+
+          cd docutils-X.Y.Z
+          python setup.py install
+
+      The "install" command may require root permissions.
+
+  (c) Repeat step b) for all supported Python versions.
+
+* Run the _`test suite` from the expanded archive directory with all
+  supported Python versions on all available platforms (GNU/Linux, Mac
+  OS X, Windows)::
+
+      cd test ; python -u alltests.py
+
+* Add a directory X.Y.Z (where X.Y.Z is the current version number
+  of Docutils) in the webroot (i.e. the ``htdocs/`` directory).
+  Put all documentation files into it::
+
+      cd docutils-X.Y.Z
+      rm -rf build
+      cd tools/
+      ./buildhtml.py ..
+      cd ..
+      find -name test -type d -prune -o -name \*.css -print0 \
+          -o -name \*.html -print0 -o -name \*.txt -print0 \
+          | tar -cjvf docutils-docs.tar.bz2 -T - --null
+      scp docutils-docs.tar.bz2 <username>@shell.sourceforge.net:
+
+  Now log in to shell.sourceforge.net and::
+
+      cd /home/groups/d/do/docutils/htdocs/
+      mkdir -m g+rwxs X.Y.Z
+      cd X.Y.Z
+      tar -xjvf ~/docutils-docs.tar.bz2
+      rm ~/docutils-docs.tar.bz2
+
+* Upload the release tarball, release.sh tries with scp.
+
+* Access the _`file release system` on SourceForge (Admin
+  interface).
+
+  ``https://sourceforge.net/projects/docutils/files/docutils/``
+
+  * change into the released version's directory
+  * click ``(i)`` button of the tar.gz-file
+  * select as default download for all operating systems.
+
+* Submit a notification on project news.
+
+* For verifying the integrity of the release, download the release
+  tarball (you may need to wait up to 30 minutes), install_ it, and
+  re-run the `test suite`_.
+
+* Register with PyPI (``python setup.py register``).
+
+  Set the download-url so eggs can access older releases.
+
+* Restore ``__version_details__`` in docutils/docutils/__init__.py to
+  "repository" (from "release").
+
+* Bump the `version number`_ again.
+
+* Add a new empty section "Changes Since ..." in HISTORY.txt.
+
+* Update the web page (web/index.txt).
+
+* Run docutils-update on the server.
+
+* **Run alltests.py with svn version**
+
+* **build wheels**::
+
+    pip wheel docutils
+    pip3 wheel docutils
+
+  This builds wheels_ (`pure Python wheels`_ for Python 2 and 3
+  respectively) by downloading the new release from pypi.
+
+  `Upload the wheels to PyPI`_.
+
+  Question:
+    Can we have an tar.gz (distutil) and a py2-wheel and a py3-wheel
+    on pypi and will installers select the correct files?
+
+    2017-06-09 it seems to according to experience with 0.13.1.
+
+  .. _wheels: https://packaging.python.org/en/latest/distributing.html#wheels
+  .. _pure Python wheels:
+     https://packaging.python.org/en/latest/distributing.html#pure-python-wheels
+  .. _Upload the wheels to PyPI:
+     https://packaging.python.org/en/latest/distributing.html#upload-your-distributions
+
+* **Send announcement email to:**
+
+  * docutils-develop@lists.sourceforge.net (also announcing the end of
+    the check-in freeze)
+  * docutils-users@lists.sourceforge.net
+  * doc-sig@python.org
+  * python-announce@python.org
+
+* **Add a `SourceForge News item`__, with title "Docutils X.Y.Z released"**
+
+  __ https://sourceforge.net/p/docutils/news
+
+  **Mark as default download for all platforms.**
+
+* **Register with freecode.** Add a new release for the
+  `Docutils project`__. (freecode is freshmeat.net's new name)
+
+  __ http://freecode.com/projects/docutils/
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

docs/dev/repository.txt

@@ -0,0 +1,208 @@
+=====================================
+ The Docutils_ Subversion Repository
+=====================================
+
+:Author: Lea Wiemann
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 7800 $
+:Date: $Date: 2015-02-24 14:01:43 +0100 (Di, 24 Feb 2015) $
+:Copyright: This document has been placed in the public domain.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+.. admonition:: Quick Instructions
+
+   To get a checkout of the Docutils source tree (with the
+   sandboxes), type ::
+
+       svn checkout http://svn.code.sf.net/p/docutils/code/trunk docutils-code
+
+
+   If you are going to commit changes to the repository, please read
+   the **whole document**, especially the section "`Information for
+   Developers`_"!
+
+.. important::
+   As of 2013-03-13 the subversion urls have changed.
+
+Docutils uses a Subversion_ repository located at
+``docutils.svn.sourceforge.net``.
+Subversion is exhaustively documented in the `Subversion Book`_ (svnbook).
+
+While Unix and Mac OS X users will probably prefer the standard
+Subversion command line interface, Windows user may want to try
+TortoiseSVN_, a convenient explorer extension.  The instructions apply
+analogously.
+
+There is a git_ mirror at http://repo.or.cz/docutils.git providing
+`web access`_ and the base for `creating a local git clone`_.
+
+For the project policy on repository use (check-in requirements,
+branching, etc.), please see the `Docutils Project Policies`__.
+
+__ policies.html#subversion-repository
+
+.. _Subversion: http://subversion.tigris.org/
+.. _Subversion Book: http://svnbook.red-bean.com/
+.. _TortoiseSVN: http://tortoisesvn.tigris.org/
+.. _SourceForge.net: http://sourceforge.net/
+.. _git: http://git-scm.com/
+
+.. contents::
+
+
+Accessing the Repository
+========================
+
+General Information
+-------------------
+
+Web Access
+~~~~~~~~~~
+
+The repository can be browsed and examined via the web at
+http://sourceforge.net/p/docutils/code
+
+Alternatively, use the web interface of the git mirror at
+http://repo.or.cz/w/docutils.git.
+
+
+Repository Access Methods
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To get a checkout of the Docutils repository, first determine the root
+of the repository depending on your preferred protocol:
+
+anonymous access: (read only)
+    ``http://svn.code.sf.net/p/docutils/code``
+
+`developer access`_: (read and write)
+    ``svn+ssh://<USERNAME>@svn.code.sf.net/p/docutils/code``
+
+.. git clone: (read only)
+    ``git clone git://repo.or.cz/docutils.git``
+
+Checking Out the Repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To check out only the current main source tree of Docutils, type ::
+
+    svn checkout ROOT/trunk/docutils
+
+(Substitute your preferred repository root for ROOT.)  To check out
+everything (main tree, sandboxes, web site, and parallel projects),
+type ::
+
+    svn checkout ROOT/trunk docutils
+
+This will create a working copy of the whole trunk in a new directory
+called ``docutils``.
+
+Note that you probably do *not* want to check out the ROOT itself
+(without "/trunk"), because then you'd end up fetching the whole
+Docutils tree for every branch and tag over and over again.
+
+To update your working copy later on, ``cd`` into the working copy and
+type ::
+
+    svn update
+
+Creating a local git clone
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Users of git_ can clone a mirror of the docutils repository with ::
+
+  git clone git://repo.or.cz/docutils.git
+
+and proceed according to the `git documentation`_.
+
+.. _git documentation: http://git-scm.com/documentation
+
+Switching the Repository Root
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you changed your mind and want to use a different repository root,
+``cd`` into your working copy and type::
+
+    svn switch --relocate OLDROOT NEWROOT
+
+.. _developer access:
+
+Information for Developers
+--------------------------
+
+If you would like to have write access to the repository, register
+with SourceForge.net_ and send your SourceForge.net
+user names to docutils-develop@lists.sourceforge.net.
+(Note that there may be a delay of several hours until you can commit
+changes to the repository.)
+
+Sourceforge subversion access is documented `here`__
+
+__ http://sourceforge.net/p/forge/documentation/svn/
+
+
+Setting Up Your Subversion Client For Development
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before commiting changes to the repository, please ensure that the
+following lines are contained (and uncommented) in your local
+~/.subversion/config file, so that new files are added with the
+correct properties set::
+
+    [miscellany]
+    # For your convenience:
+    global-ignores = ... *.pyc ...
+    # For correct properties:
+    enable-auto-props = yes
+
+    [auto-props]
+    *.py = svn:eol-style=native;svn:keywords=Author Date Id Revision
+    *.txt = svn:eol-style=native;svn:keywords=Author Date Id Revision
+    *.html = svn:eol-style=native;svn:keywords=Author Date Id Revision
+    *.xml = svn:eol-style=native;svn:keywords=Author Date Id Revision
+    *.tex = svn:eol-style=native;svn:keywords=Author Date Id Revision
+    *.css = svn:eol-style=native;svn:keywords=Author Date Id Revision
+    *.patch = svn:eol-style=native
+    *.sh = svn:eol-style=native;svn:executable;svn:keywords=Author Date Id Revision
+    *.png = svn:mime-type=image/png
+    *.jpg = svn:mime-type=image/jpeg
+    *.gif = svn:mime-type=image/gif
+
+
+Repository Layout
+=================
+
+The following tree shows the repository layout::
+
+    docutils/
+    |-- branches/
+    |   |-- branch1/
+    |   |   |-- docutils/
+    |   |   |-- sandbox/
+    |   |   `-- web/
+    |   `-- branch2/
+    |       |-- docutils/
+    |       |-- sandbox/
+    |       `-- web/
+    |-- tags/
+    |   |-- tag1/
+    |   |   |-- docutils/
+    |   |   |-- sandbox/
+    |   |   `-- web/
+    |   `-- tag2/
+    |       |-- docutils/
+    |       |-- sandbox/
+    |       `-- web/
+    `-- trunk/
+        |-- docutils/
+        |-- sandbox/
+        `-- web/
+
+The main source tree lives at ``docutils/trunk/docutils/``, next to
+the sandboxes (``docutils/trunk/sandbox/``) and the web site files
+(``docutils/trunk/web/``).
+
+``docutils/branches/`` and ``docutils/tags/`` contain (shallow) copies
+of either the whole trunk or only the main source tree
+(``docutils/trunk/docutils``).

docs/dev/rst/problems.txt

@@ -0,0 +1,872 @@
+==============================
+ Problems With StructuredText
+==============================
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 7302 $
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:Copyright: This document has been placed in the public domain.
+
+There are several problems, unresolved issues, and areas of
+controversy within StructuredText_ (Classic and Next Generation).  In
+order to resolve all these issues, this analysis brings all of the
+issues out into the open, enumerates all the alternatives, and
+proposes solutions to be incorporated into the reStructuredText_
+specification.
+
+
+.. contents::
+
+
+Formal Specification
+====================
+
+The description in the original StructuredText.py has been criticized
+for being vague.  For practical purposes, "the code *is* the spec."
+Tony Ibbs has been working on deducing a `detailed description`_ from
+the documentation and code of StructuredTextNG_.  Edward Loper's
+STMinus_ is another attempt to formalize a spec.
+
+For this kind of a project, the specification should always precede
+the code.  Otherwise, the markup is a moving target which can never be
+adopted as a standard.  Of course, a specification may be revised
+during lifetime of the code, but without a spec there is no visible
+control and thus no confidence.
+
+
+Understanding and Extending the Code
+====================================
+
+The original StructuredText_ is a dense mass of sparsely commented
+code and inscrutable regular expressions.  It was not designed to be
+extended and is very difficult to understand.  StructuredTextNG_ has
+been designed to allow input (syntax) and output extensions, but its
+documentation (both internal [comments & docstrings], and external) is
+inadequate for the complexity of the code itself.
+
+For reStructuredText to become truly useful, perhaps even part of
+Python's standard library, it must have clear, understandable
+documentation and implementation code.  For the implementation of
+reStructuredText to be taken seriously, it must be a sterling example
+of the potential of docstrings; the implementation must practice what
+the specification preaches.
+
+
+Section Structure via Indentation
+=================================
+
+Setext_ required that body text be indented by 2 spaces.  The original
+StructuredText_ and StructuredTextNG_ require that section structure
+be indicated through indentation, as "inspired by Python".  For
+certain structures with a very limited, local extent (such as lists,
+block quotes, and literal blocks), indentation naturally indicates
+structure or hierarchy.  For sections (which may have a very large
+extent), structure via indentation is unnecessary, unnatural and
+ambiguous.  Rather, the syntax of the section title *itself* should
+indicate that it is a section title.
+
+The original StructuredText states that "A single-line paragraph whose
+immediately succeeding paragraphs are lower level is treated as a
+header." Requiring indentation in this way is:
+
+- Unnecessary.  The vast majority of docstrings and standalone
+  documents will have no more than one level of section structure.
+  Requiring indentation for such docstrings is unnecessary and
+  irritating.
+
+- Unnatural.  Most published works use title style (type size, face,
+  weight, and position) and/or section/subsection numbering rather
+  than indentation to indicate hierarchy.  This is a tradition with a
+  very long history.
+
+- Ambiguous.  A StructuredText header is indistinguishable from a
+  one-line paragraph followed by a block quote (precluding the use of
+  block quotes).  Enumerated section titles are ambiguous (is it a
+  header? is it a list item?).  Some additional adornment must be
+  required to confirm the line's role as a title, both to a parser and
+  to the human reader of the source text.
+
+Python's use of significant whitespace is a wonderful (if not
+original) innovation, however requiring indentation in ordinary
+written text is hypergeneralization.
+
+reStructuredText_ indicates section structure through title adornment
+style (as exemplified by this document).  This is far more natural.
+In fact, it is already in widespread use in plain text documents,
+including in Python's standard distribution (such as the toplevel
+README_ file).
+
+
+Character Escaping Mechanism
+============================
+
+No matter what characters are chosen for markup, some day someone will
+want to write documentation *about* that markup or using markup
+characters in a non-markup context.  Therefore, any complete markup
+language must have an escaping or encoding mechanism.  For a
+lightweight markup system, encoding mechanisms like SGML/XML's '*'
+are out.  So an escaping mechanism is in.  However, with carefully
+chosen markup, it should be necessary to use the escaping mechanism
+only infrequently.
+
+reStructuredText_ needs an escaping mechanism: a way to treat
+markup-significant characters as the characters themselves.  Currently
+there is no such mechanism (although ZWiki uses '!').  What are the
+candidates?
+
+1. ``!``
+   (http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/NGEscaping)
+2. ``\``
+3. ``~``
+4. doubling of characters
+
+The best choice for this is the backslash (``\``).  It's "the single
+most popular escaping character in the world!", therefore familiar and
+unsurprising.  Since characters only need to be escaped under special
+circumstances, which are typically those explaining technical
+programming issues, the use of the backslash is natural and
+understandable.  Python docstrings can be raw (prefixed with an 'r',
+as in 'r""'), which would obviate the need for gratuitous doubling-up
+of backslashes.
+
+(On 2001-03-29 on the Doc-SIG mailing list, GvR endorsed backslash
+escapes, saying, "'nuff said.  Backslash it is." Although neither
+legally binding nor irrevocable nor any kind of guarantee of anything,
+it is a good sign.)
+
+The rule would be: An unescaped backslash followed by any markup
+character escapes the character.  The escaped character represents the
+character itself, and is prevented from playing a role in any markup
+interpretation.  The backslash is removed from the output.  A literal
+backslash is represented by an "escaped backslash," two backslashes in
+a row.
+
+A carefully constructed set of recognition rules for inline markup
+will obviate the need for backslash-escapes in almost all cases; see
+`Delimitation of Inline Markup`_ below.
+
+When an expression (requiring backslashes and other characters used
+for markup) becomes too complicated and therefore unreadable, a
+literal block may be used instead.  Inside literal blocks, no markup
+is recognized, therefore backslashes (for the purpose of escaping
+markup) become unnecessary.
+
+We could allow backslashes preceding non-markup characters to remain
+in the output.  This would make describing regular expressions and
+other uses of backslashes easier.  However, this would complicate the
+markup rules and would be confusing.
+
+
+Blank Lines in Lists
+====================
+
+Oft-requested in Doc-SIG (the earliest reference is dated 1996-08-13)
+is the ability to write lists without requiring blank lines between
+items.  In docstrings, space is at a premium.  Authors want to convey
+their API or usage information in as compact a form as possible.
+StructuredText_ requires blank lines between all body elements,
+including list items, even when boundaries are obvious from the markup
+itself.
+
+In reStructuredText, blank lines are optional between list items.
+However, in order to eliminate ambiguity, a blank line is required
+before the first list item and after the last.  Nested lists also
+require blank lines before the list start and after the list end.
+
+
+Bullet List Markup
+==================
+
+StructuredText_ includes 'o' as a bullet character.  This is dangerous
+and counter to the language-independent nature of the markup.  There
+are many languages in which 'o' is a word.  For example, in Spanish::
+
+    Llamame a la casa
+    o al trabajo.
+
+    (Call me at home or at work.)
+
+And in Japanese (when romanized)::
+
+    Senshuu no doyoubi ni tegami
+    o kakimashita.
+
+    ([I] wrote a letter on Saturday last week.)
+
+If a paragraph containing an 'o' word wraps such that the 'o' is the
+first text on a line, or if a paragraph begins with such a word, it
+could be misinterpreted as a bullet list.
+
+In reStructuredText_, 'o' is not used as a bullet character.  '-',
+'*', and '+' are the possible bullet characters.
+
+
+Enumerated List Markup
+======================
+
+StructuredText enumerated lists are allowed to begin with numbers and
+letters followed by a period or right-parenthesis, then whitespace.
+This has surprising consequences for writing styles.  For example,
+this is recognized as an enumerated list item by StructuredText::
+
+    Mr. Creosote.
+
+People will write enumerated lists in all different ways.  It is folly
+to try to come up with the "perfect" format for an enumerated list,
+and limit the docstring parser's recognition to that one format only.
+
+Rather, the parser should recognize a variety of enumerator styles.
+It is also recommended that the enumerator of the first list item be
+ordinal-1 ('1', 'A', 'a', 'I', or 'i'), as output formats may not be
+able to begin a list at an arbitrary enumeration.
+
+An initial idea was to require two or more consistent enumerated list
+items in a row.  This idea proved impractical and was dropped.  In
+practice, the presence of a proper enumerator is enough to reliably
+recognize an enumerated list item; any ambiguities are reported by the
+parser.  Here's the original idea for posterity:
+
+    The parser should recognize a variety of enumerator styles, mark
+    each block as a potential enumerated list item (PELI), and
+    interpret the enumerators of adjacent PELIs to decide whether they
+    make up a consistent enumerated list.
+
+    If a PELI is labeled with a "1.", and is immediately followed by a
+    PELI labeled with a "2.", we've got an enumerated list.  Or "(A)"
+    followed by "(B)".  Or "i)" followed by "ii)", etc.  The chances
+    of accidentally recognizing two adjacent and consistently labeled
+    PELIs, are acceptably small.
+
+    For an enumerated list to be recognized, the following must be
+    true:
+
+    - the list must consist of multiple adjacent list items (2 or
+      more)
+    - the enumerators must all have the same format
+    - the enumerators must be sequential
+
+
+Definition List Markup
+======================
+
+StructuredText uses ' -- ' (whitespace, two hyphens, whitespace) on
+the first line of a paragraph to indicate a definition list item.  The
+' -- ' serves to separate the term (on the left) from the definition
+(on the right).
+
+Many people use ' -- ' as an em-dash in their text, conflicting with
+the StructuredText usage.  Although the Chicago Manual of Style says
+that spaces should not be used around an em-dash, Peter Funk pointed
+out that this is standard usage in German (according to the Duden, the
+official German reference), and possibly in other languages as well.
+The widespread use of ' -- ' precludes its use for definition lists;
+it would violate the "unsurprising" criterion.
+
+A simpler, and at least equally visually distinctive construct
+(proposed by Guido van Rossum, who incidentally is a frequent user of
+' -- ') would do just as well::
+
+    term 1
+        Definition.
+
+    term 2
+        Definition 2, paragraph 1.
+
+        Definition 2, paragraph 2.
+
+A reStructuredText definition list item consists of a term and a
+definition.  A term is a simple one-line paragraph.  A definition is a
+block indented relative to the term, and may contain multiple
+paragraphs and other body elements.  No blank line precedes a
+definition (this distinguishes definition lists from block quotes).
+
+
+Literal Blocks
+==============
+
+The StructuredText_ specification has literal blocks indicated by
+'example', 'examples', or '::' ending the preceding paragraph.  STNG
+only recognizes '::'; 'example'/'examples' are not implemented.  This
+is good; it fixes an unnecessary language dependency.  The problem is
+what to do with the sometimes- unwanted '::'.
+
+In reStructuredText_ '::' at the end of a paragraph indicates that
+subsequent *indented* blocks are treated as literal text.  No further
+markup interpretation is done within literal blocks (not even
+backslash-escapes).  If the '::' is preceded by whitespace, '::' is
+omitted from the output; if '::' was the sole content of a paragraph,
+the entire paragraph is removed (no 'empty' paragraph remains).  If
+'::' is preceded by a non-whitespace character, '::' is replaced by
+':' (i.e., the extra colon is removed).
+
+Thus, a section could begin with a literal block as follows::
+
+    Section Title
+    -------------
+
+    ::
+
+        print "this is example literal"
+
+
+Tables
+======
+
+The table markup scheme in classic StructuredText was horrible.  Its
+omission from StructuredTextNG is welcome, and its markup will not be
+repeated here.  However, tables themselves are useful in
+documentation.  Alternatives:
+
+1. This format is the most natural and obvious.  It was independently
+   invented (no great feat of creation!), and later found to be the
+   format supported by the `Emacs table mode`_::
+
+       +------------+------------+------------+--------------+
+       |  Header 1  |  Header 2  |  Header 3  |  Header 4    |
+       +============+============+============+==============+
+       |  Column 1  |  Column 2  | Column 3 & 4 span (Row 1) |
+       +------------+------------+------------+--------------+
+       |    Column 1 & 2 span    |  Column 3  | - Column 4   |
+       +------------+------------+------------+ - Row 2 & 3  |
+       |      1     |      2     |      3     | - span       |
+       +------------+------------+------------+--------------+
+
+   Tables are described with a visual outline made up of the
+   characters '-', '=', '|', and '+':
+
+   - The hyphen ('-') is used for horizontal lines (row separators).
+   - The equals sign ('=') is optionally used as a header separator
+     (as of version 1.5.24, this is not supported by the Emacs table
+     mode).
+   - The vertical bar ('|') is used for for vertical lines (column
+     separators).
+   - The plus sign ('+') is used for intersections of horizontal and
+     vertical lines.
+
+   Row and column spans are possible simply by omitting the column or
+   row separators, respectively.  The header row separator must be
+   complete; in other words, a header cell may not span into the table
+   body.  Each cell contains body elements, and may have multiple
+   paragraphs, lists, etc.  Initial spaces for a left margin are
+   allowed; the first line of text in a cell determines its left
+   margin.
+
+2. Below is a simpler table structure.  It may be better suited to
+   manual input than alternative #1, but there is no Emacs editing
+   mode available.  One disadvantage is that it resembles section
+   titles; a one-column table would look exactly like section &
+   subsection titles. ::
+
+       ============ ============ ============ ==============
+         Header 1     Header 2     Header 3     Header 4
+       ============ ============ ============ ==============
+         Column 1     Column 2    Column 3 & 4 span (Row 1)
+       ------------ ------------ ---------------------------
+           Column 1 & 2 span       Column 3    - Column 4
+       ------------------------- ------------  - Row 2 & 3
+             1            2            3       - span
+       ============ ============ ============ ==============
+
+   The table begins with a top border of equals signs with a space at
+   each column boundary (regardless of spans).  Each row is
+   underlined.  Internal row separators are underlines of '-', with
+   spaces at column boundaries.  The last of the optional head rows is
+   underlined with '=', again with spaces at column boundaries.
+   Column spans have no spaces in their underline.  Row spans simply
+   lack an underline at the row boundary.  The bottom boundary of the
+   table consists of '=' underlines.  A blank line is required
+   following a table.
+
+3. A minimalist alternative is as follows::
+
+       ====  =====  ========  ========  =======  ====  =====  =====
+       Old State    Input     Action             New State    Notes
+       -----------  --------  -----------------  -----------
+       ids   types  new type  sys.msg.  dupname  ids   types
+       ====  =====  ========  ========  =======  ====  =====  =====
+       --    --     explicit  --        --       new   True
+       --    --     implicit  --        --       new   False
+       None  False  explicit  --        --       new   True
+       old   False  explicit  implicit  old      new   True
+       None  True   explicit  explicit  new      None  True
+       old   True   explicit  explicit  new,old  None  True   [1]
+       None  False  implicit  implicit  new      None  False
+       old   False  implicit  implicit  new,old  None  False
+       None  True   implicit  implicit  new      None  True
+       old   True   implicit  implicit  new      old   True
+       ====  =====  ========  ========  =======  ====  =====  =====
+
+   The table begins with a top border of equals signs with one or more
+   spaces at each column boundary (regardless of spans).  There must
+   be at least two columns in the table (to differentiate it from
+   section headers).  Each line starts a new row.  The rightmost
+   column is unbounded; text may continue past the edge of the table.
+   Each row/line must contain spaces at column boundaries, except for
+   explicit column spans.  Underlines of '-' can be used to indicate
+   column spans, but should be used sparingly if at all.  Lines
+   containing column span underlines may not contain any other text.
+   The last of the optional head rows is underlined with '=', again
+   with spaces at column boundaries.  The bottom boundary of the table
+   consists of '=' underlines.  A blank line is required following a
+   table.
+
+   This table sums up the features.  Using all the features in such a
+   small space is not pretty though::
+
+       ========  ========  ========
+                 Header 2 & 3 Span
+                 ------------------
+       Header 1  Header 2  Header 3
+       ========  ========  ========
+       Each      line is   a new row.
+       Each row  consists  of one line only.
+       Row       spans     are not possible.
+       The last  column    may spill over to the right.
+       Column spans are possible with an underline joining columns.
+       ----------------------------
+       The span  is        limited to the row above the underline.
+       ========  ========  ========
+
+4. As a variation of alternative 3, bullet list syntax in the first
+   column could be used to indicate row starts.  Multi-line rows are
+   possible, but row spans are not.  For example::
+
+       ===== =====
+       col 1 col 2
+       ===== =====
+       - 1   Second column of row 1.
+       - 2   Second column of row 2.
+             Second line of paragraph.
+       - 3   Second column of row 3.
+
+             Second paragraph of row 3,
+             column 2
+       ===== =====
+
+   Column spans would be indicated on the line after the last line of
+   the row.  To indicate a real bullet list within a first-column
+   cell, simply nest the bullets.
+
+5. In a further variation, we could simply assume that whitespace in
+   the first column implies a multi-line row; the text in other
+   columns is continuation text.  For example::
+
+       ===== =====
+       col 1 col 2
+       ===== =====
+       1     Second column of row 1.
+       2     Second column of row 2.
+             Second line of paragraph.
+       3     Second column of row 3.
+
+             Second paragraph of row 3,
+             column 2
+       ===== =====
+
+   Limitations of this approach:
+
+   - Cells in the first column are limited to one line of text.
+
+   - Cells in the first column *must* contain some text; blank cells
+     would lead to a misinterpretation.  An empty comment ("..") is
+     sufficient.
+
+6. Combining alternative 3 and 4, a bullet list in the first column
+   could mean multi-line rows, and no bullet list means single-line
+   rows only.
+
+Alternatives 1 and 5 has been adopted by reStructuredText.
+
+
+Delimitation of Inline Markup
+=============================
+
+StructuredText specifies that inline markup must begin with
+whitespace, precluding such constructs as parenthesized or quoted
+emphatic text::
+
+    "**What?**" she cried.  (*exit stage left*)
+
+The `reStructuredText markup specification`_ allows for such
+constructs and disambiguates inline markup through a set of
+recognition rules.  These recognition rules define the context of
+markup start-strings and end-strings, allowing markup characters to be
+used in most non-markup contexts without a problem (or a backslash).
+So we can say, "Use asterisks (*) around words or phrases to
+*emphasisze* them." The '(*)' will not be recognized as markup.  This
+reduces the need for markup escaping to the point where an escape
+character is *almost* (but not quite!) unnecessary.
+
+
+Underlining
+===========
+
+StructuredText uses '_text_' to indicate underlining.  To quote David
+Ascher in his 2000-01-21 Doc-SIG mailing list post, "Docstring
+grammar: a very revised proposal":
+
+    The tagging of underlined text with _'s is suboptimal.  Underlines
+    shouldn't be used from a typographic perspective (underlines were
+    designed to be used in manuscripts to communicate to the
+    typesetter that the text should be italicized -- no well-typeset
+    book ever uses underlines), and conflict with double-underscored
+    Python variable names (__init__ and the like), which would get
+    truncated and underlined when that effect is not desired.  Note
+    that while *complete* markup would prevent that truncation
+    ('__init__'), I think of docstring markups much like I think of
+    type annotations -- they should be optional and above all do no
+    harm.  In this case the underline markup does harm.
+
+Underlining is not part of the reStructuredText specification.
+
+
+Inline Literals
+===============
+
+StructuredText's markup for inline literals (text left as-is,
+verbatim, usually in a monospaced font; as in HTML <TT>) is single
+quotes ('literals').  The problem with single quotes is that they are
+too often used for other purposes:
+
+- Apostrophes: "Don't blame me, 'cause it ain't mine, it's Chris'.";
+
+- Quoting text:
+
+      First Bruce: "Well Bruce, I heard the prime minister use it.
+      'S'hot enough to boil a monkey's bum in 'ere your Majesty,' he
+      said, and she smiled quietly to herself."
+
+  In the UK, single quotes are used for dialogue in published works.
+
+- String literals: s = ''
+
+Alternatives::
+
+    'text'    \'text\'    ''text''    "text"    \"text\"    ""text""
+    #text#     @text@      `text`     ^text^    ``text''    ``text``
+
+The examples below contain inline literals, quoted text, and
+apostrophes.  Each example should evaluate to the following HTML::
+
+    Some <TT>code</TT>, with a 'quote', "double", ain't it grand?
+    Does <TT>a[b] = 'c' + "d" + `2^3`</TT> work?
+
+    0. Some code, with a quote, double, ain't it grand?
+       Does a[b] = 'c' + "d" + `2^3` work?
+    1. Some 'code', with a \'quote\', "double", ain\'t it grand?
+       Does 'a[b] = \'c\' + "d" + `2^3`' work?
+    2. Some \'code\', with a 'quote', "double", ain't it grand?
+       Does \'a[b] = 'c' + "d" + `2^3`\' work?
+    3. Some ''code'', with a 'quote', "double", ain't it grand?
+       Does ''a[b] = 'c' + "d" + `2^3`'' work?
+    4. Some "code", with a 'quote', \"double\", ain't it grand?
+       Does "a[b] = 'c' + "d" + `2^3`" work?
+    5. Some \"code\", with a 'quote', "double", ain't it grand?
+       Does \"a[b] = 'c' + "d" + `2^3`\" work?
+    6. Some ""code"", with a 'quote', "double", ain't it grand?
+       Does ""a[b] = 'c' + "d" + `2^3`"" work?
+    7. Some #code#, with a 'quote', "double", ain't it grand?
+       Does #a[b] = 'c' + "d" + `2^3`# work?
+    8. Some @code@, with a 'quote', "double", ain't it grand?
+       Does @a[b] = 'c' + "d" + `2^3`@ work?
+    9. Some `code`, with a 'quote', "double", ain't it grand?
+       Does `a[b] = 'c' + "d" + \`2^3\`` work?
+    10. Some ^code^, with a 'quote', "double", ain't it grand?
+        Does ^a[b] = 'c' + "d" + `2\^3`^ work?
+    11. Some ``code'', with a 'quote', "double", ain't it grand?
+        Does ``a[b] = 'c' + "d" + `2^3`'' work?
+    12. Some ``code``, with a 'quote', "double", ain't it grand?
+        Does ``a[b] = 'c' + "d" + `2^3\``` work?
+
+Backquotes (#9 & #12) are the best choice.  They are unobtrusive and
+relatviely rarely used (more rarely than ' or ", anyhow).  Backquotes
+have the connotation of 'quotes', which other options (like carets,
+#10) don't.
+
+Analogously with ``*emph*`` & ``**strong**``, double-backquotes (#12)
+could be used for inline literals.  If single-backquotes are used for
+'interpreted text' (context-sensitive domain-specific descriptive
+markup) such as function name hyperlinks in Python docstrings, then
+double-backquotes could be used for absolute-literals, wherein no
+processing whatsoever takes place.  An advantage of double-backquotes
+would be that backslash-escaping would no longer be necessary for
+embedded single-backquotes; however, embedded double-backquotes (in an
+end-string context) would be illegal.  See `Backquotes in
+Phrase-Links`__ in `Record of reStructuredText Syntax Alternatives`__.
+
+__ alternatives.html#backquotes-in-phrase-links
+__ alternatives.html
+
+Alternative choices are carets (#10) and TeX-style quotes (#11).  For
+examples of TeX-style quoting, see
+http://www.zope.org/Members/jim/StructuredTextWiki/CustomizingTheDocumentProcessor.
+
+Some existing uses of backquotes:
+
+1. As a synonym for repr() in Python.
+2. For command-interpolation in shell scripts.
+3. Used as open-quotes in TeX code (and carried over into plaintext
+   by TeXies).
+
+The inline markup start-string and end-string recognition rules
+defined by the `reStructuredText markup specification`_ would allow
+all of these cases inside inline literals, with very few exceptions.
+As a fallback, literal blocks could handle all cases.
+
+Outside of inline literals, the above uses of backquotes would require
+backslash-escaping.  However, these are all prime examples of text
+that should be marked up with inline literals.
+
+If either backquotes or straight single-quotes are used as markup,
+TeX-quotes are too troublesome to support, so no special-casing of
+TeX-quotes should be done (at least at first).  If TeX-quotes have to
+be used outside of literals, a single backslash-escaped would suffice:
+\``TeX quote''.  Ugly, true, but very infrequently used.
+
+Using literal blocks is a fallback option which removes the need for
+backslash-escaping::
+
+    like this::
+
+        Here, we can do ``absolutely'' anything `'`'\|/|\ we like!
+
+No mechanism for inline literals is perfect, just as no escaping
+mechanism is perfect.  No matter what we use, complicated inline
+expressions involving the inline literal quote and/or the backslash
+will end up looking ugly.  We can only choose the least often ugly
+option.
+
+reStructuredText will use double backquotes for inline literals, and
+single backqoutes for interpreted text.
+
+
+Hyperlinks
+==========
+
+There are three forms of hyperlink currently in StructuredText_:
+
+1. (Absolute & relative URIs.)  Text enclosed by double quotes
+   followed by a colon, a URI, and concluded by punctuation plus white
+   space, or just white space, is treated as a hyperlink::
+
+       "Python":http://www.python.org/
+
+2. (Absolute URIs only.)  Text enclosed by double quotes followed by a
+   comma, one or more spaces, an absolute URI and concluded by
+   punctuation plus white space, or just white space, is treated as a
+   hyperlink::
+
+       "mail me", mailto:me@mail.com
+
+3. (Endnotes.)  Text enclosed by brackets link to an endnote at the
+   end of the document: at the beginning of the line, two dots, a
+   space, and the same text in brackets, followed by the end note
+   itself::
+
+       Please refer to the fine manual [GVR2001].
+
+       .. [GVR2001] Python Documentation, Release 2.1, van Rossum,
+          Drake, et al., http://www.python.org/doc/
+
+The problem with forms 1 and 2 is that they are neither intuitive nor
+unobtrusive (they break design goals 5 & 2).  They overload
+double-quotes, which are too often used in ordinary text (potentially
+breaking design goal 4).  The brackets in form 3 are also too common
+in ordinary text (such as [nested] asides and Python lists like [12]).
+
+Alternatives:
+
+1. Have no special markup for hyperlinks.
+
+2. A. Interpret and mark up hyperlinks as any contiguous text
+      containing '://' or ':...@' (absolute URI) or '@' (email
+      address) after an alphanumeric word.  To de-emphasize the URI,
+      simply enclose it in parentheses:
+
+          Python (http://www.python.org/)
+
+   B. Leave special hyperlink markup as a domain-specific extension.
+      Hyperlinks in ordinary reStructuredText documents would be
+      required to be standalone (i.e. the URI text inline in the
+      document text).  Processed hyperlinks (where the URI text is
+      hidden behind the link) are important enough to warrant syntax.
+
+3. The original Setext_ introduced a mechanism of indirect hyperlinks.
+   A source link word ('hot word') in the text was given a trailing
+   underscore::
+
+       Here is some text with a hyperlink_ built in.
+
+   The hyperlink itself appeared at the end of the document on a line
+   by itself, beginning with two dots, a space, the link word with a
+   leading underscore, whitespace, and the URI itself::
+
+       .. _hyperlink http://www.123.xyz
+
+   Setext used ``underscores_instead_of_spaces_`` for phrase links.
+
+With some modification, alternative 3 best satisfies the design goals.
+It has the advantage of being readable and relatively unobtrusive.
+Since each source link must match up to a target, the odd variable
+ending in an underscore can be spared being marked up (although it
+should generate a "no such link target" warning).  The only
+disadvantage is that phrase-links aren't possible without some
+obtrusive syntax.
+
+We could achieve phrase-links if we enclose the link text:
+
+1. in double quotes::
+
+       "like this"_
+
+2. in brackets::
+
+       [like this]_
+
+3. or in backquotes::
+
+       `like this`_
+
+Each gives us somewhat obtrusive markup, but that is unavoidable.  The
+bracketed syntax (#2) is reminiscent of links on many web pages
+(intuitive), although it is somewhat obtrusive.  Alternative #3 is
+much less obtrusive, and is consistent with interpreted text: the
+trailing underscore indicates the interpretation of the phrase, as a
+hyperlink.  #3 also disambiguates hyperlinks from footnote references.
+Alternative #3 wins.
+
+The same trailing underscore markup can also be used for footnote and
+citation references, removing the problem with ordinary bracketed text
+and Python lists::
+
+    Please refer to the fine manual [GVR2000]_.
+
+    .. [GVR2000] Python Documentation, van Rossum, Drake, et al.,
+       http://www.python.org/doc/
+
+The two-dots-and-a-space syntax was generalized by Setext for
+comments, which are removed from the (visible) processed output.
+reStructuredText uses this syntax for comments, footnotes, and link
+target, collectively termed "explicit markup".  For link targets, in
+order to eliminate ambiguity with comments and footnotes,
+reStructuredText specifies that a colon always follow the link target
+word/phrase.  The colon denotes 'maps to'.  There is no reason to
+restrict target links to the end of the document; they could just as
+easily be interspersed.
+
+Internal hyperlinks (links from one point to another within a single
+document) can be expressed by a source link as before, and a target
+link with a colon but no URI.  In effect, these targets 'map to' the
+element immediately following.
+
+As an added bonus, we now have a perfect candidate for
+reStructuredText directives, a simple extension mechanism: explicit
+markup containing a single word followed by two colons and whitespace.
+The interpretation of subsequent data on the directive line or
+following is directive-dependent.
+
+To summarize::
+
+    .. This is a comment.
+
+    .. The line below is an example of a directive.
+    .. version:: 1
+
+    This is a footnote [1]_.
+
+    This internal hyperlink will take us to the footnotes_ area below.
+
+    Here is a one-word_ external hyperlink.
+
+    Here is `a hyperlink phrase`_.
+
+    .. _footnotes:
+    .. [1] Footnote text goes here.
+
+    .. external hyperlink target mappings:
+    .. _one-word: http://www.123.xyz
+    .. _a hyperlink phrase: http://www.123.xyz
+
+The presence or absence of a colon after the target link
+differentiates an indirect hyperlink from a footnote, respectively.  A
+footnote requires brackets.  Backquotes around a target link word or
+phrase are required if the phrase contains a colon, optional
+otherwise.
+
+Below are examples using no markup, the two StructuredText hypertext
+styles, and the reStructuredText hypertext style.  Each example
+contains an indirect link, a direct link, a footnote/endnote, and
+bracketed text.  In HTML, each example should evaluate to::
+
+    <P>A <A HREF="http://spam.org">URI</A>, see <A HREF="#eggs2000">
+    [eggs2000]</A> (in Bacon [Publisher]).  Also see
+    <A HREF="http://eggs.org">http://eggs.org</A>.</P>
+
+    <P><A NAME="eggs2000">[eggs2000]</A> "Spam, Spam, Spam, Eggs,
+    Bacon, and Spam"</P>
+
+1. No markup::
+
+       A URI http://spam.org, see eggs2000 (in Bacon [Publisher]).
+       Also see http://eggs.org.
+
+       eggs2000 "Spam, Spam, Spam, Eggs, Bacon, and Spam"
+
+2. StructuredText absolute/relative URI syntax
+   ("text":http://www.url.org)::
+
+       A "URI":http://spam.org, see [eggs2000] (in Bacon [Publisher]).
+       Also see "http://eggs.org":http://eggs.org.
+
+       .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam"
+
+   Note that StructuredText does not recognize standalone URIs,
+   forcing doubling up as shown in the second line of the example
+   above.
+
+3. StructuredText absolute-only URI syntax
+   ("text", mailto:you@your.com)::
+
+       A "URI", http://spam.org, see [eggs2000] (in Bacon
+       [Publisher]).  Also see "http://eggs.org", http://eggs.org.
+
+       .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam"
+
+4. reStructuredText syntax::
+
+    4. A URI_, see [eggs2000]_ (in Bacon [Publisher]).
+       Also see http://eggs.org.
+
+       .. _URI: http:/spam.org
+       .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam"
+
+The bracketed text '[Publisher]' may be problematic with
+StructuredText (syntax 2 & 3).
+
+reStructuredText's syntax (#4) is definitely the most readable.  The
+text is separated from the link URI and the footnote, resulting in
+cleanly readable text.
+
+.. _StructuredText:
+   http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage
+.. _Setext: http://docutils.sourceforge.net/mirror/setext.html
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _detailed description:
+   http://homepage.ntlworld.com/tibsnjoan/docutils/STNG-format.html
+.. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/stminus.html
+.. _StructuredTextNG:
+   http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG
+.. _README: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/~checkout~/
+   python/python/dist/src/README
+.. _Emacs table mode: http://table.sourceforge.net/
+.. _reStructuredText Markup Specification:
+   ../../ref/rst/restructuredtext.html
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

docs/dev/semantics.txt

@@ -0,0 +1,119 @@
+=====================
+ Docstring Semantics
+=====================
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 7302 $
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:Copyright: This document has been placed in the public domain.
+
+These are notes for a possible future PEP providing the final piece of
+the Python docstring puzzle: docstring semantics or documentation
+methodology.  `PEP 257`_, Docstring Conventions, sketches out some
+guidelines, but does not get into methodology details.
+
+I haven't explored documentation methodology more because, in my
+opinion, it is a completely separate issue from syntax, and it's even
+more controversial than syntax.  Nobody wants to be told how to lay
+out their documentation, a la JavaDoc_.  I think the JavaDoc way is
+butt-ugly, but it *is* an established standard for the Java world.
+Any standard documentation methodology has to be formal enough to be
+useful but remain light enough to be usable.  If the methodology is
+too strict, too heavy, or too ugly, many/most will not want to use it.
+
+I think a standard methodology could benefit the Python community, but
+it would be a hard sell.  A PEP would be the place to start.  For most
+human-readable documentation needs, the free-form text approach is
+adequate.  We'd only need a formal methodology if we want to extract
+the parameters into a data dictionary, index, or summary of some kind.
+
+
+PythonDoc
+=========
+
+(Not to be confused with Daniel Larsson's pythondoc_ project.)
+
+A Python version of the JavaDoc_ semantics (not syntax).  A set of
+conventions which are understood by the Docutils.  What JavaDoc has
+done is to establish a syntax that enables a certain documentation
+methodology, or standard *semantics*.  JavaDoc is not just syntax; it
+prescribes a methodology.
+
+- Use field lists or definition lists for "tagged blocks".  By this I
+  mean that field lists can be used similarly to JavaDoc's ``@tag``
+  syntax.  That's actually one of the motivators behind field lists.
+  For example, we could have::
+
+      """
+      :Parameters:
+          - `lines`: a list of one-line strings without newlines.
+          - `until_blank`: Stop collecting at the first blank line if
+            true (1).
+          - `strip_indent`: Strip common leading indent if true (1,
+            default).
+
+      :Return:
+          - a list of indented lines with mininum indent removed;
+          - the amount of the indent;
+          - whether or not the block finished with a blank line or at
+            the end of `lines`.
+      """
+
+  This is taken straight out of docutils/statemachine.py, in which I
+  experimented with a simple documentation methodology.  Another
+  variation I've thought of exploits the Grouch_-compatible
+  "classifier" element of definition lists.  For example::
+
+      :Parameters:
+          `lines` : [string]
+              List of one-line strings without newlines.
+          `until_blank` : boolean
+              Stop collecting at the first blank line if true (1).
+          `strip_indent` : boolean
+              Strip common leading indent if true (1, default).
+
+- Field lists could even be used in a one-to-one correspondence with
+  JavaDoc ``@tags``, although I doubt if I'd recommend it.  Several
+  ports of JavaDoc's ``@tag`` methodology exist in Python, most
+  recently Ed Loper's "epydoc_".
+
+
+Other Ideas
+===========
+
+- Can we extract comments from parsed modules?  Could be handy for
+  documenting function/method parameters::
+
+      def method(self,
+                 source,        # path of input file
+                 dest           # path of output file
+                ):
+
+  This would save having to repeat parameter names in the docstring.
+
+  Idea from Mark Hammond's 1998-06-23 Doc-SIG post, "Re: [Doc-SIG]
+  Documentation tool":
+
+      it would be quite hard to add a new param to this method without
+      realising you should document it
+
+- Frederic Giacometti's `iPhrase Python documentation conventions`_ is
+  an attachment to his Doc-SIG post of 2001-05-30.
+
+
+.. _PEP 257: http://www.python.org/peps/pep-0257.html
+.. _JavaDoc: http://java.sun.com/j2se/javadoc/
+.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/
+.. _Grouch: http://www.mems-exchange.org/software/grouch/
+.. _epydoc: http://epydoc.sf.net/
+.. _iPhrase Python documentation conventions:
+   http://mail.python.org/pipermail/doc-sig/2001-May/001840.html
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

docs/dev/testing.txt

@@ -0,0 +1,290 @@
+===================
+ Docutils_ Testing
+===================
+
+:Authors: Lea Wiemann <LeWiemann@gmail.com>;
+          David Goodger <goodger@python.org>
+:Revision: $Revision: 8051 $
+:Date: $Date: 2017-03-21 16:45:28 +0100 (Di, 21 Mär 2017) $
+:Copyright: This document has been placed in the public domain.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+.. contents::
+
+When adding new functionality (or fixing bugs), be sure to add test
+cases to the test suite.  Practise test-first programming; it's fun,
+it's addictive, and it works!
+
+This document describes how to run the Docutils test suite, how the
+tests are organized and how to add new tests or modify existing tests.
+
+
+Running the Test Suite
+======================
+
+Before checking in any changes, run the entire Docutils test suite to
+be sure that you haven't broken anything.  From a shell::
+
+    cd docutils/test
+    ./alltests.py
+
+For Python 3, the tests must be converted with 2to3. To run the tests with
+Python 3, ``cd`` to the package's root directory and do::
+
+    python3 setup.py build
+    python3 test3/alltests.py
+
+Python Versions
+===============
+
+A docutils release has a commitment to support a minimum version and 
+beyond. Before a release is cut, tests must pass in all supported python
+versions.
+
+The Docutils 0.10 release supports Python 2.4 or later. 
+Versions after 0.12 will drop python 2.4, supporting **2.5** and later.
+
+Therefore, you should install python 2.5, as well as the latest Python 
+(3.4 at the time of this writing) installed and always run the tests on 
+all of them. In a pinch, the edge cases (2.5, and 3.4) should cover most 
+of it.
+
+Good resources covering the differences between Python versions:
+
+* `What's New in Python 2.5`__
+* `What's New in Python 2.6`__
+* `What's New in Python 2.7`__
+* `What's New in Python 3.3`__
+* `What's New in Python 3.4`__
+* `PEP 290 - Code Migration and Modernization`__
+
+__ http://www.python.org/doc/2.5.2/whatsnew/whatsnew25.html
+__ http://docs.python.org/whatsnew/2.6.html
+__ http://docs.python.org/whatsnew/2.7.html
+__ https://docs.python.org/3/whatsnew/3.3.html
+__ https://docs.python.org/3/whatsnew/3.4.html
+__ http://www.python.org/peps/pep-0290.html
+
+.. _Python Check-in Policies: http://www.python.org/dev/tools.html
+.. _sandbox directory:
+   http://docutils.svn.sourceforge.net/svnroot/docutils/trunk/sandbox/
+.. _nightly repository tarball:
+   http://svn.berlios.de/svndumps/docutils-repos.gz
+
+Testing across multiple python versions
+---------------------------------------
+
+`pyenv`_ can be installed and configured (see `installing pyenv`_) to 
+test multiple python versions::
+
+    # assuming your system runs 2.7.x
+    pyenv install 2.6.9
+    pyenv install 3.3.6
+    pyenv install 3.4.3
+    pyenv global system 2.5.6 2.6.9 3.3.6 3.4.3
+
+    # reset your shims
+    rm -rf ~/.pyenv/shims && pyenv rehash
+
+This will give you ``python2.6``, ``python2.7``, ``python3.3`` and
+``python3.4``. Along with that, ``pip2.6``, ``pip2.7`` and so on.
+
+To save time, you can use `tox`_ to test docutils on versions 2.6+. To
+install tox, you can use ``easy_install tox`` or ``pip install tox``.
+From shell::
+
+    cd docutils
+    tox
+
+Note: tox and virtualenv only supports python 2.6 and onward.
+
+.. _tox: https://tox.readthedocs.org/en/latest/
+.. _pyenv: https://github.com/yyuu/pyenv
+.. _installing pyenv: https://github.com/yyuu/pyenv#installation
+
+
+Unit Tests
+==========
+
+Unit tests test single functions or modules (i.e. whitebox testing).
+
+If you are implementing a new feature, be sure to write a test case
+covering its functionality.  It happens very frequently that your
+implementation (or even only a part of it) doesn't work with an older
+(or even newer) Python version, and the only reliable way to detect
+those cases is using tests.
+
+Often, it's easier to write the test first and then implement the
+functionality required to make the test pass.
+
+
+Writing New Tests
+-----------------
+
+When writing new tests, it very often helps to see how a similar test
+is implemented.  For example, the files in the
+``test_parsers/test_rst/`` directory all look very similar.  So when
+adding a test, you don't have to reinvent the wheel.
+
+If there is no similar test, you can write a new test from scratch
+using Python's ``unittest`` module.  For an example, please have a
+look at the following imaginary ``test_square.py``::
+
+    #! /usr/bin/env python
+
+    # $Id: testing.txt 8051 2017-03-21 15:45:28Z milde $
+    # Author: Your Name <your_email_address@example.org>
+    # Copyright: This module has been placed in the public domain.
+
+    """
+    Test module for docutils.square.
+    """
+
+    import unittest
+    import docutils.square
+
+
+    class SquareTest(unittest.TestCase):
+
+        def test_square(self):
+            self.assertEqual(docutils.square.square(0), 0)
+            self.assertEqual(docutils.square.square(5), 25)
+            self.assertEqual(docutils.square.square(7), 49)
+
+        def test_square_root(self):
+            self.assertEqual(docutils.square.sqrt(49), 7)
+            self.assertEqual(docutils.square.sqrt(0), 0)
+            self.assertRaises(docutils.square.SquareRootError,
+                              docutils.square.sqrt, 20)
+
+
+    if __name__ == '__main__':
+        unittest.main()
+
+For more details on how to write tests, please refer to the
+documentation of the ``unittest`` module.
+
+.. Note::
+
+   Unit tests and functional test should generally set ::
+
+     settings_overrides['_disable_config'] = True
+
+   in order to be independent on the users local configuration.
+
+.. _functional:
+
+Functional Tests
+================
+
+The directory ``test/functional/`` contains data for functional tests.
+
+Performing functional testing means testing the Docutils system as a
+whole (i.e. blackbox testing).
+
+
+Directory Structure
+-------------------
+
++ ``functional/`` The main data directory.
+
+  + ``input/`` The input files.
+
+    - ``some_test.txt``, for example.
+
+  + ``output/`` The actual output.
+
+    - ``some_test.html``, for example.
+
+  + ``expected/`` The expected output.
+
+    - ``some_test.html``, for example.
+
+  + ``tests/`` The config files for processing the input files.
+
+    - ``some_test.py``, for example.
+
+    - ``_default.py``, the `default configuration file`_.
+
+
+The Testing Process
+-------------------
+
+When running ``test_functional.py``, all config files in
+``functional/tests/`` are processed.  (Config files whose names begin
+with an underscore are ignored.)  The current working directory is
+always Docutils' main test directory (``test/``).
+
+For example, ``functional/tests/some_test.py`` could read like this::
+
+    # Source and destination file names.
+    test_source = "some_test.txt"
+    test_destination = "some_test.html"
+
+    # Keyword parameters passed to publish_file.
+    reader_name = "standalone"
+    parser_name = "rst"
+    writer_name = "html"
+    settings_overrides['output-encoding'] = 'utf-8'
+    # Relative to main ``test/`` directory.
+    settings_overrides['stylesheet_path'] = '../docutils/writers/html4css1/html4css1.css'
+
+The two variables ``test_source`` and ``test_destination`` contain the
+input file name (relative to ``functional/input/``) and the output
+file name (relative to ``functional/output/`` and
+``functional/expected/``).  Note that the file names can be chosen
+arbitrarily.  However, the file names in ``functional/output/`` *must*
+match the file names in ``functional/expected/``.
+
+If defined, ``_test_more`` must be a function with the following
+signature::
+
+    def _test_more(expected_dir, output_dir, test_case, parameters):
+
+This function is called from the test case to perform tests beyond the
+simple comparison of expected and actual output files.
+
+``test_source`` and ``test_destination`` are removed from the
+namespace, as are all variables whose names begin with an underscore
+("_").  The remaining names are passed as keyword arguments to
+``docutils.core.publish_file``, so you can set reader, parser, writer
+and anything else you want to configure.  Note that
+``settings_overrides`` is already initialized as a dictionary *before*
+the execution of the config file.
+
+
+Creating New Tests
+------------------
+
+In order to create a new test, put the input test file into
+``functional/input/``.  Then create a config file in
+``functional/tests/`` which sets at least input and output file names,
+reader, parser and writer.
+
+Now run ``test_functional.py``.  The test will fail, of course,
+because you do not have an expected output yet.  However, an output
+file will have been generated in ``functional/output/``.  Check this
+output file for validity and correctness.  Then copy the file to
+``functional/expected/``.
+
+If you rerun ``test_functional.py`` now, it should pass.
+
+If you run ``test_functional.py`` later and the actual output doesn't
+match the expected output anymore, the test will fail.
+
+If this is the case and you made an intentional change, check the
+actual output for validity and correctness, copy it to
+``functional/expected/`` (overwriting the old expected output), and
+commit the change.
+
+
+.. _default configuration file:
+
+The Default Configuration File
+------------------------------
+
+The file ``functional/tests/_default.py`` contains default settings.
+It is executed just before the actual configuration files, which has
+the same effect as if the contents of ``_default.py`` were prepended
+to every configuration file.

docs/dev/website.txt

@@ -0,0 +1,107 @@
+===================
+ Docutils Web Site
+===================
+
+:Author: David Goodger; open to all Docutils developers
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date: 2017-07-05 16:33:33 +0200 (Mi, 05 Jul 2017) $
+:Revision: $Revision: 8133 $
+:Copyright: This document has been placed in the public domain.
+
+The Docutils web site, <http://docutils.sourceforge.net/>, is
+maintained by the ``docutils-update.local`` script, run by project 
+maintainers on their local machines.  The script
+will process any .txt file which is newer than the corresponding .html
+file in the local copy of the project's web directory and upload the changes
+to the web site at SourceForge.
+
+..  .. old instructions, for cron job:
+
+    The Docutils web site, <http://docutils.sourceforge.net/>, is
+    maintained automatically by the ``docutils-update`` script, run as an
+    hourly cron job on shell.berlios.de (by user "wiemann").  The script
+    will process any .txt file which is newer than the corresponding .html
+    file in the project's web directory on shell.berlios.de
+    (``/home/groups/docutils/htdocs/aux/htdocs/``) and upload the changes
+    to the web site at SourceForge.
+
+Please **do not** add any generated .html files to the Docutils
+repository.  They will be generated automatically after a one-time
+setup (`described below`__).
+
+__ `Adding .txt Files`_
+
+The docutils-update.local__ script is located at
+``sandbox/infrastructure/docutils-update.local``.
+
+__ http://docutils.sf.net/sandbox/infrastructure/docutils-update.local
+
+If you want to share files via the web, you can upload them using the
+uploaddocutils.sh__ script
+(``sandbox/infrastructure/uploaddocutils.sh``).
+
+__ http://docutils.sf.net/sandbox/infrastructure/uploaddocutils.sh
+
+
+Setting Up
+==========
+
+(TBA)
+
+.. hint:: 
+  Anyone with checkin privileges can be a web-site maintainer. You need to
+  set up the directories for a local website build.
+
+  The procedure for that was on the docutils-devel list a while ago.
+
+
+Adding .txt Files
+=================
+
+User/Contributor
+----------------
+
+When adding a new .txt file that should be converted to HTML:
+
+#. Edit sandbox/infrastructure/htmlfiles.lst, and add the .html file
+   corresponding to the new .txt file (please keep the sorted order).
+
+#. Commit the edited version to the SVN repository.
+
+Maintainer
+----------
+
+#. If there are new directories in the SVN, allow the update script to run
+   once to create the directories in the filesystem before preparing for
+   HTML processing.
+
+#. Run the sandbox/infrastructure/update-htmlfiles shell script to generate
+   .html files::
+
+      cd <DOCUTILS-ROOT>/docutils/
+      sandbox/infrastructure/update-htmlfiles \
+      sandbox/infrastructure/htmlfiles.lst
+
+   (Maybe this should become part of docutils-update.local.)
+
+
+Removing Files & Directories
+============================
+
+#. Remove from SVN
+
+#. Remove to-be-generated HTML files from
+   ``sandbox/infrastructure/htmlfiles.lst``.
+  
+#. Removing files and directories from SVN will not trigger their removal
+   from the web site.  Files and directories must be manually removed from
+   sourceforge.net (under ``/home/project-web/docutils/htdocs/``). 
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

docs/dev/wheeling.txt

@@ -0,0 +1,204 @@
+===========================
+ Docutils_ Building Wheels
+===========================
+
+:Authors: engelbert gruber; open to all Docutils developers
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date: 2015-05-06 18:36:40 +0200 (Mi, 06 Mai 2015) $
+:Revision: $Revision: 7887 $
+:Copyright: This document has been placed in the public domain.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+.. contents::
+
+Abstract
+--------
+
+This document documents trials to build python wheels from Docutils. Once it
+is finished it might be driven into distribution or release documentation.
+
+Requests
+--------
+
+There is `feature request 43`_ :  Make setup.py build wheels.
+
+  Just add this to setup.cfg:
+
+  [bdist_wheel]
+  universal = 1
+
+
+  .. warning:: Docutils is not fit for Universal Wheels. It supports both
+     Python 2 and 3, but with different code (we use “2to3”). This makes it
+     a candidate for `Pure Python wheels`_.
+
+     As "universal" is false by default, no change to setup.cfg is required.
+     The wheel builder detects that the package is pure Python and generates
+     wheels for Py2 and Py3 depending under which python version it runs.
+
+and bugs275_ : Upload wheels to pypi
+
+  Currently docutils does not publish any wheels on pypi. Wheels make docutils
+  faster to install (no need to run setup.py, which for a large number of
+  packages can take some time), and is no more difficult than uploading an
+  sdist (see https://packaging.python.org/en/latest/distributing.html#wheels
+  for instructions).
+
+Logbook
+-------
+
+1. Add ``[bdist_wheel] universal = 0`` to setup.cfg.
+2. Run ``python setup.py bdist_wheel``::
+
+     error: invalid command 'bdist_wheel'
+
+3. setuptools is too old. Install the new one by wheel or source or pip or
+   easy...
+
+4. try wheel ... first get wheel tar.gz and unpack.
+
+5. try ::
+
+     python2.7 wheel-0.24.0/wheel install setuptools-15.0-py2.py3-none-any.whl
+
+   no error. But still ``error: invalid command 'bdist_wheel'``::
+
+     $ python2.7 setup.py --version
+     0.12
+
+   Did wheel install ? If no, why no error, if yes in which place ?
+
+
+Logbook: with setuptools branch
+-------------------------------
+
+`gitpull/setuptools`_ sandbox branch introduces `setuptools`_ in ``setup.py``.
+
+As of 2015-04-16: **Not working yet**, ``import docutils`` will raise an
+``ImportError``. Need to get packages detected correctly.
+
+Install::
+
+    $ svn checkout svn://svn.code.sf.net/p/docutils/code/trunk/sandbox/gitpull/setuptools docutils-setuptools
+    $ cd setuptools
+    # create a virtualenv (however you like)
+    $ pip install -e .
+
+This includes support for generate ``python setup.py bdist_wheel``::
+
+    $ python setup.py bdist_wheel
+    running bdist_wheel
+    running build
+    running build_scripts
+    installing to build/bdist.linux-x86_64/wheel
+    running install
+    running install_egg_info
+    running egg_info
+    writing docutils.egg-info/PKG-INFO
+    writing top-level names to docutils.egg-info/top_level.txt
+    writing dependency_links to docutils.egg-info/dependency_links.txt
+    reading manifest file 'docutils.egg-info/SOURCES.txt'
+    reading manifest template 'MANIFEST.in'
+    warning: no files found matching 'MANIFEST'
+    warning: no files found matching '*' under directory 'extras'
+    warning: no previously-included files matching '.cvsignore' found under directory '*'
+    warning: no previously-included files matching '*~' found under directory '*'
+    warning: no previously-included files matching '.DS_Store' found under directory '*'
+    writing manifest file 'docutils.egg-info/SOURCES.txt'
+    Copying docutils.egg-info to build/bdist.linux-x86_64/wheel/docutils-0.13.data/purelib/docutils-0.13-py2.7.egg-info
+    running install_scripts
+    creating build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
+    copying build/scripts-2.7/rst2pseudoxml.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
+    copying build/scripts-2.7/rst2man.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
+    copying build/scripts-2.7/rst2odt.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
+    copying build/scripts-2.7/rst2latex.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
+    copying build/scripts-2.7/rstpep2html.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
+    copying build/scripts-2.7/rst2s5.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
+    copying build/scripts-2.7/rst2odt_prepstyles.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
+    copying build/scripts-2.7/rst2html.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
+    copying build/scripts-2.7/rst2html5.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
+    copying build/scripts-2.7/rst2xml.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
+    copying build/scripts-2.7/rst2xetex.py -> build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts
+    changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2pseudoxml.py to 755
+    changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2man.py to 755
+    changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2odt.py to 755
+    changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2latex.py to 755
+    changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rstpep2html.py to 755
+    changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2s5.py to 755
+    changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2odt_prepstyles.py to 755
+    changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2html.py to 755
+    changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2html5.py to 755
+    changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2xml.py to 755
+    changing mode of build/bdist.linux-x86_64/wheel/docutils-0.13.data/scripts/rst2xetex.py to 755
+    creating build/bdist.linux-x86_64/wheel/docutils-0.13.dist-info/WHEEL
+
+Installation::
+
+    # create a fresh virtualenv
+    $ pip install -U dist/docutils-0.13-cp27-none-linux_x86_64.whl
+    Processing ./dist/docutils-0.13-cp27-none-linux_x86_64.whl
+    Installing collected packages: docutils
+    Found existing installation: docutils 0.13
+    Uninstalling docutils-0.13:
+    Successfully uninstalled docutils-0.13
+    Successfully installed docutils-0.13
+    
+    
+Logbook with "pip"
+------------------
+
+Docutils' "setup.py" imports from the stdlib's "distutils" module
+instead of the 3rd party "setuptools". "distutils" cannot build wheels. [#]_
+
+OTOH, pip_ internally uses "setuptools" instead of "distutils". This way, it
+can generate wheels without changes to "setup.py".
+
+1. Install "pip" and "wheels"
+
+   Under Debian Gnu/Linux: ``aptitude install python-pip python3-pip``
+
+2. In the repository root directory, run ::
+
+      #> pip wheel ./docutils/
+      Unpacking ./docutils
+        Running setup.py (path:/tmp/pip-Ym9hKL-build/setup.py) egg_info for package from file:///[...]docutils-svn/docutils
+
+          warning: no previously-included files matching '.DS_Store' found under directory '*'
+      Building wheels for collected packages: docutils
+        Running setup.py bdist_wheel for docutils
+        Destination directory: /home/milde/Code/Python/docutils-svn/wheelhouse
+      Successfully built docutils
+      Cleaning up...
+
+3. There is a "pure Python" wheel under
+   ``wheelhouse/docutils-0.13-py2-none-any.whl``
+
+4. Repeat with::
+
+     #> pip3 wheel ./docutils/
+     
+   to get ``wheelhouse/docutils-0.13-py3-none-any.whl``
+
+You can also generate wheels for Docutils 0.12 with ``pip wheel docutils``
+and ``pip3 wheel docutils``. The 0.12 archive is downloaded from PIP and
+re-packed as wheel. With "pip3" this includes the 2to3 conversion.
+
+Summary:
+  With the "pip" utility, it is possible to generate wheels for Python 2
+  and 3 for both, the released and the repository version of Docutils
+  without changes to the code base.
+
+  The generated wheel can be installed. Installing the Py3k version happens
+  "instantaneously".
+
+.. [#] Docutils uses the batteries included with Python and avoids external
+   dependencies.  
+
+.. _bugs275: https://sourceforge.net/p/docutils/bugs/275/
+.. _pure python wheels:
+    https://packaging.python.org/en/latest/distributing.html#pure-python-wheels
+.. _feature request 43: https://sourceforge.net/p/docutils/feature-requests/43/
+.. _gitpull/setuptools: https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/gitpull/setuptools/
+.. _setuptools: https://pythonhosted.org/setuptools/
+.. _pip: http://pip.readthedocs.org/en/latest/

docs/howto/html-stylesheets.txt

@@ -0,0 +1,95 @@
+==============================================
+ Writing HTML (CSS) Stylesheets for Docutils_
+==============================================
+
+:Author: Lea Wiemann
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date: 2016-11-29 13:00:39 +0100 (Di, 29 Nov 2016) $
+:Revision: $Revision: 7977 $
+:Copyright: This document has been placed in the public domain.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+
+The look of Docutils' HTML output is customizable via CSS stylesheets.
+The default stylesheets can be found in the
+``docutils/writers/html*/`` directories of the ``html4css1`` and
+``html-base`` writers in the Docutils installation.  Use the front-end
+command (``rst2html.py`` or ``rst2html5.py``) with the
+``--help`` option and look at the description of the ``--stylesheet-path``
+command-line option for the exact machine-specific location.
+
+To customize the look of HTML documents, you can override the settings
+of the default stylesheet in your own stylesheet. Specify both, the
+default stylesheet and your stylesheet to the ``--stylesheet`` or
+``--stylesheet-path`` command line option (or the corresponding
+settings in a configuration_ file), e.g. ::
+
+  rst2html.py --stylesheet=html4css1.css,transition-stars.css
+
+This is the preferable approach if you want to embed the stylesheet(s), as
+this ensures that an up-to-date version of ``html4css1.css`` is embedded.
+
+Alternatively, copy the default style sheet to the same place as your
+output HTML files will go and place a new file (e.g. called
+``my-docutils.css``) in the same directory and use the following
+template::
+
+    /*
+    :Author: Your Name
+    :Contact: Your Email Address
+    :Copyright: This stylesheet has been placed in the public domain.
+
+    Stylesheet for use with Docutils.  [Optionally place a more
+    detailed description here.]
+    */
+
+    @import url(html4css1.css);
+
+    /* Your customizations go here.  For example: */
+
+    h1, h2, h3, h4, h5, h6, p.topic-title {
+      font-family: sans-serif }
+
+For help on the CSS syntax, please see `the WDG's guide to Cascading
+Style Sheets`__ and, in particular, their `list of CSS properties`__.
+Another good reference site is http://selfhtml.org (German and French).
+
+__ http://www.htmlhelp.com/reference/css/
+__ http://www.htmlhelp.com/reference/css/all-properties.html
+
+It is important that you do not edit a copy of ``html4css1.css``
+directly because ``html4css1.css`` is frequently updated with each new
+release of Docutils.
+
+Also make sure that you import ``html4css1.css`` (using "``@import
+url(html4css1.css);``") because the definitions contained in the
+default stylesheet are required for correct rendering (margins,
+alignment, etc.).
+
+If you think your stylesheet is fancy and you would like to let others
+benefit from your efforts, you are encouraged to post the stylesheet to the
+Docutils-users_ mailing list. It might find its place in the `stylesheet
+collection`_ in the Docutils Sandbox_.
+
+If you decide to share your stylesheet with other users of Docutils,
+please keep website-specific customizations not applicable to
+Docutils' HTML code in a separate stylesheet.
+
+.. base for relative links is /docutils/docs/howto/
+
+.. _Docutils-users: ../user/mailing-lists.html#docutils-users
+.. _configuration: ../user/config.txt
+.. _sandbox: ../../../sandbox
+.. _stylesheet collection: ../../../sandbox/stylesheets/
+
+
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

docs/howto/i18n.txt

@@ -0,0 +1,196 @@
+================================
+ Docutils_ Internationalization
+================================
+
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date: 2014-07-07 05:12:02 +0200 (Mo, 07 Jul 2014) $
+:Revision: $Revision: 7769 $
+:Copyright: This document has been placed in the public domain.
+
+
+.. contents::
+
+
+This document describes the internationalization facilities of the
+Docutils_ project.  `Introduction to i18n`_ by Tomohiro KUBOTA is a
+good general reference.  "Internationalization" is often abbreviated
+as "i18n": "i" + 18 letters + "n".
+
+.. Note::
+
+   The i18n facilities of Docutils should be considered a "first
+   draft".  They work so far, but improvements are welcome.
+   Specifically, standard i18n facilities like "gettext" have yet to
+   be explored.
+
+Docutils is designed to work flexibly with text in multiple languages
+(one language at a time).  Language-specific features are (or should
+be [#]_) fully parameterized.  To enable a new language, two modules
+have to be added to the project: one for Docutils itself (the
+`Docutils Language Module`_) and one for the reStructuredText parser
+(the `reStructuredText Language Module`_).
+
+.. [#] If anything in Docutils is insufficiently parameterized, it
+   should be considered a bug.  Please report bugs to the Docutils
+   project bug tracker on SourceForge at
+   http://sourceforge.net/p/docutils/bugs/
+
+.. _Docutils: http://docutils.sourceforge.net/
+.. _Introduction to i18n:
+   http://www.debian.org/doc/manuals/intro-i18n/
+
+
+Language Module Names
+=====================
+
+Language modules are named using `language tags`_ as defined in
+`BCP 47`_. [#]_ in lowercase, converting hyphens to underscores [#]_.
+
+A typical language identifier consists of a 2-letter language code
+from `ISO 639`_ (3-letter codes can be used if no 2-letter code
+exists). The language identifier can have an optional subtag,
+typically for variations based on country (from `ISO 3166`_ 2-letter
+country codes).  If no language identifier is specified, the default
+is "en" for English.  Examples of module names include ``en.py``,
+``fr.py``, ``ja.py``, and ``pt_br.py``.
+
+.. [#] BCP stands for 'Best Current Practice', and is a persistent
+   name for a series of RFCs whose numbers change as they are updated.
+   The latest RFC describing language tag syntax is RFC 5646, Tags for
+   the Identification of Languages, and it obsoletes the older RFCs
+   4646, 3066 and 1766.
+
+.. [#] Subtags are separated from primary tags by underscores instead
+   of hyphens, to conform to Python naming rules.
+
+.. _language tags: http://www.w3.org/International/articles/language-tags/
+.. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt
+.. _ISO 639: http://www.loc.gov/standards/iso639-2/php/English_list.php
+.. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/
+   02iso-3166-code-lists/index.html
+
+
+Python Code
+===========
+
+Generally Python code in Docutils is ASCII-only.  In language modules,
+Unicode-escapes can be used for non-ASCII characters.
+
+`PEP 263`_ introduces source code encodings to Python modules,
+implemented beginning in Python 2.3.  Especially for languages with
+non-Latin scripts, using UTF-8 encoded literal Unicode strings increases the
+readability. Start the source code file with the magic comment::
+
+  # -*- coding: utf-8 -*-
+
+As mentioned in the note above, developers are invited to explore
+"gettext" and other i18n technologies.
+
+.. _PEP 263: http://www.python.org/peps/pep-0263.html
+
+
+Docutils Language Module
+========================
+
+Modules in ``docutils/languages`` contain language mappings for
+markup-independent language-specific features of Docutils.  To make a
+new language module, just copy the ``en.py`` file, rename it with the
+code for your language (see `Language Module Names`_ above), and
+translate the terms as described below.
+
+Each Docutils language module contains three module attributes:
+
+``labels``
+    This is a mapping of node class names to language-dependent
+    boilerplate label text.  The label text is used by Writer
+    components when they encounter document tree elements whose class
+    names are the mapping keys.
+
+    The entry values (*not* the keys) should be translated to the
+    target language.
+
+``bibliographic_fields``
+    This is a mapping of language-dependent field names (converted to
+    lower case) to canonical field names (keys of
+    ``DocInfo.biblio_notes`` in ``docutils.transforms.frontmatter``).
+    It is used when transforming bibliographic fields.
+
+    The keys should be translated to the target language.
+
+``author_separators``
+    This is a list of strings used to parse the 'Authors'
+    bibliographic field.  They separate individual authors' names, and
+    are tried in order (i.e., earlier items take priority, and the
+    first item that matches wins).  The English-language module
+    defines them as ``[';', ',']``; semi-colons can be used to
+    separate names like "Arthur Pewtie, Esq.".
+
+    Most languages won't have to "translate" this list.
+
+
+reStructuredText Language Module
+================================
+
+Modules in ``docutils/parsers/rst/languages`` contain language
+mappings for language-specific features of the reStructuredText
+parser.  To make a new language module, just copy the ``en.py`` file,
+rename it with the code for your language (see `Language Module
+Names`_ above), and translate the terms as described below.
+
+Each reStructuredText language module contains two module attributes:
+
+``directives``
+    This is a mapping from language-dependent directive names to
+    canonical directive names.  The canonical directive names are
+    registered in ``docutils/parsers/rst/directives/__init__.py``, in
+    ``_directive_registry``.
+
+    The keys should be translated to the target language.  Synonyms
+    (multiple keys with the same values) are allowed; this is useful
+    for abbreviations.
+
+``roles``
+    This is a mapping language-dependent role names to canonical role
+    names for interpreted text.  The canonical directive names are
+    registered in ``docutils/parsers/rst/states.py``, in
+    ``Inliner._interpreted_roles`` (this may change).
+
+    The keys should be translated to the target language.  Synonyms
+    (multiple keys with the same values) are allowed; this is useful
+    for abbreviations.
+
+
+Testing the Language Modules
+============================
+
+Whenever a new language module is added or an existing one modified,
+the unit tests should be run.  The test modules can be found in the
+docutils/test directory from code_ or from the `latest snapshot`_.
+
+The ``test_language.py`` module can be run as a script.  With no
+arguments, it will test all language modules.  With one or more
+language codes, it will test just those languages.  For example::
+
+    $ python test_language.py en
+    ..
+    ----------------------------------------
+    Ran 2 tests in 0.095s
+
+    OK
+
+Use the "alltests.py" script to run all test modules, exhaustively
+testing the parser and other parts of the Docutils system.
+
+.. _code: https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/
+.. _latest snapshot: https://sourceforge.net/p/docutils/code/HEAD/tarball
+
+
+Submitting the Language Modules
+===============================
+
+If you do not have repository write access and want to contribute your
+language modules, feel free to submit them via the `SourceForge patch
+tracker`__.
+
+__ http://sourceforge.net/p/docutils/patches/

docs/howto/rst-directives.txt

@@ -0,0 +1,430 @@
+=======================================
+ Creating reStructuredText_ Directives
+=======================================
+
+:Authors: Dethe Elza, David Goodger, Lea Wiemann
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:Revision: $Revision: 7302 $
+:Copyright: This document has been placed in the public domain.
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+
+
+Directives are the primary extension mechanism of reStructuredText.
+This document aims to make the creation of new directives as easy and
+understandable as possible.  There are only a couple of
+reStructuredText-specific features the developer needs to know to
+create a basic directive.
+
+The syntax of directives is detailed in the `reStructuredText Markup
+Specification`_, and standard directives are described in
+`reStructuredText Directives`_.
+
+Directives are a reStructuredText markup/parser concept.  There is no
+"directive" document tree element, no single element that corresponds
+exactly to the concept of directives.  Instead, choose the most
+appropriate elements from the existing Docutils elements.  Directives
+build structures using the existing building blocks.  See `The
+Docutils Document Tree`_ and the ``docutils.nodes`` module for more
+about the building blocks of Docutils documents.
+
+.. _reStructuredText Markup Specification:
+   ../ref/rst/restructuredtext.html#directives
+.. _reStructuredText Directives: ../ref/rst/directives.html
+.. _The Docutils Document Tree: ../ref/doctree.html
+
+
+.. contents:: Table of Contents
+
+
+The Directive Class
+===================
+
+Directives are created by defining a directive class that inherits
+from ``docutils.parsers.rst.Directive``::
+
+    from docutils.parsers import rst
+
+    class MyDirective(rst.Directive):
+
+        ...
+
+To understand how to implement the directive, let's have a look at the
+docstring of the ``Directive`` base class::
+
+    >>> from docutils.parsers import rst
+    >>> print rst.Directive.__doc__
+
+        Base class for reStructuredText directives.
+
+        The following attributes may be set by subclasses.  They are
+        interpreted by the directive parser (which runs the directive
+        class):
+
+        - `required_arguments`: The number of required arguments (default:
+          0).
+
+        - `optional_arguments`: The number of optional arguments (default:
+          0).
+
+        - `final_argument_whitespace`: A boolean, indicating if the final
+          argument may contain whitespace (default: False).
+
+        - `option_spec`: A dictionary, mapping known option names to
+          conversion functions such as `int` or `float` (default: {}, no
+          options).  Several conversion functions are defined in the
+          directives/__init__.py module.
+
+          Option conversion functions take a single parameter, the option
+          argument (a string or ``None``), validate it and/or convert it
+          to the appropriate form.  Conversion functions may raise
+          `ValueError` and `TypeError` exceptions.
+
+        - `has_content`: A boolean; True if content is allowed.  Client
+          code must handle the case where content is required but not
+          supplied (an empty content list will be supplied).
+
+        Arguments are normally single whitespace-separated words.  The
+        final argument may contain whitespace and/or newlines if
+        `final_argument_whitespace` is True.
+
+        If the form of the arguments is more complex, specify only one
+        argument (either required or optional) and set
+        `final_argument_whitespace` to True; the client code must do any
+        context-sensitive parsing.
+
+        When a directive implementation is being run, the directive class
+        is instantiated, and the `run()` method is executed.  During
+        instantiation, the following instance variables are set:
+
+        - ``name`` is the directive type or name (string).
+
+        - ``arguments`` is the list of positional arguments (strings).
+
+        - ``options`` is a dictionary mapping option names (strings) to
+          values (type depends on option conversion functions; see
+          `option_spec` above).
+
+        - ``content`` is a list of strings, the directive content line by line.
+
+        - ``lineno`` is the line number of the first line of the directive.
+
+        - ``content_offset`` is the line offset of the first line of the content from
+          the beginning of the current input.  Used when initiating a nested parse.
+
+        - ``block_text`` is a string containing the entire directive.
+
+        - ``state`` is the state which called the directive function.
+
+        - ``state_machine`` is the state machine which controls the state which called
+          the directive function.
+
+        Directive functions return a list of nodes which will be inserted
+        into the document tree at the point where the directive was
+        encountered.  This can be an empty list if there is nothing to
+        insert.
+
+        For ordinary directives, the list must contain body elements or
+        structural elements.  Some directives are intended specifically
+        for substitution definitions, and must return a list of `Text`
+        nodes and/or inline elements (suitable for inline insertion, in
+        place of the substitution reference).  Such directives must verify
+        substitution definition context, typically using code like this::
+
+            if not isinstance(state, states.SubstitutionDef):
+                error = state_machine.reporter.error(
+                    'Invalid context: the "%s" directive can only be used '
+                    'within a substitution definition.' % (name),
+                    nodes.literal_block(block_text, block_text), line=lineno)
+                return [error]
+
+    >>>
+
+
+Option Conversion Functions
+===========================
+
+An option specification (``Directive.option_spec``) must be defined
+detailing the options available to the directive.  An option spec is a
+mapping of option name to conversion function; conversion functions
+are applied to each option value to check validity and convert them to
+the expected type.  Python's built-in conversion functions are often
+usable for this, such as ``int``, ``float``.  Other useful conversion
+functions are included in the ``docutils.parsers.rst.directives``
+package (in the ``__init__.py`` module):
+
+- ``flag``: For options with no option arguments.  Checks for an
+  argument (raises ``ValueError`` if found), returns ``None`` for
+  valid flag options.
+
+- ``unchanged_required``: Returns the text argument, unchanged.
+  Raises ``ValueError`` if no argument is found.
+
+- ``unchanged``: Returns the text argument, unchanged.  Returns an
+  empty string ("") if no argument is found.
+
+- ``path``: Returns the path argument unwrapped (with newlines
+  removed).  Raises ``ValueError`` if no argument is found.
+
+- ``uri``: Returns the URI argument with whitespace removed.  Raises
+  ``ValueError`` if no argument is found.
+
+- ``nonnegative_int``: Checks for a nonnegative integer argument,
+  and raises ``ValueError`` if not.
+
+- ``class_option``: Converts the argument into an ID-compatible
+  string and returns it.  Raises ``ValueError`` if no argument is
+  found.
+
+- ``unicode_code``: Convert a Unicode character code to a Unicode
+  character.
+
+- ``single_char_or_unicode``: A single character is returned as-is.
+  Unicode characters codes are converted as in ``unicode_code``.
+
+- ``single_char_or_whitespace_or_unicode``: As with
+  ``single_char_or_unicode``, but "tab" and "space" are also
+  supported.
+
+- ``positive_int``: Converts the argument into an integer.  Raises
+  ValueError for negative, zero, or non-integer values.
+
+- ``positive_int_list``: Converts a space- or comma-separated list
+  of integers into a Python list of integers.  Raises ValueError for
+  non-positive-integer values.
+
+- ``encoding``: Verfies the encoding argument by lookup.  Raises
+  ValueError for unknown encodings.
+
+A further utility function, ``choice``, is supplied to enable
+options whose argument must be a member of a finite set of possible
+values.  A custom conversion function must be written to use it.
+For example::
+
+    from docutils.parsers.rst import directives
+
+    def yesno(argument):
+        return directives.choice(argument, ('yes', 'no'))
+
+For example, here is an option spec for a directive which allows two
+options, "name" and "value", each with an option argument::
+
+    option_spec = {'name': unchanged, 'value': int}
+
+
+Error Handling
+==============
+
+If your directive implementation encounters an error during
+processing, you should call ``self.error()`` inside the ``run()``
+method::
+
+    if error_condition:
+        raise self.error('Error message.')
+
+The ``self.error()`` method will immediately raise an exception that
+will be caught by the reStructuredText directive handler.  The
+directive handler will then insert an error-level system message in
+the document at the place where the directive occurred.
+
+Instead of ``self.error``, you can also use ``self.severe`` and
+``self.warning`` for more or less severe problems.
+
+If you want to return a system message *and* document contents, you need to
+create the system message yourself instead of using the ``self.error``
+convenience method::
+
+    def run(self):
+        # Create node(s).
+        node = nodes.paragraph(...)
+        # Node list to return.
+        node_list = [node]
+        if error_condition:
+             # Create system message.
+             error = self.reporter.error(
+                 'Error in "%s" directive: Your error message.' % self.name,
+                 nodes.literal_block(block_text, block_text), line=lineno)
+             node_list.append(error)
+        return node_list
+
+
+Register the Directive
+======================
+
+* If the directive is a general-use **addition to the Docutils core**,
+  it must be registered with the parser and language mappings added:
+
+  1. Register the new directive using its canonical name in
+     ``docutils/parsers/rst/directives/__init__.py``, in the
+     ``_directive_registry`` dictionary.  This allows the
+     reStructuredText parser to find and use the directive.
+
+  2. Add an entry to the ``directives`` dictionary in
+     ``docutils/parsers/rst/languages/en.py`` for the directive, mapping
+     the English name to the canonical name (both lowercase).  Usually
+     the English name and the canonical name are the same.
+
+  3. Update all the other language modules as well.  For languages in
+     which you are proficient, please add translations.  For other
+     languages, add the English directive name plus "(translation
+     required)".
+
+* If the directive is **application-specific**, use the
+  ``register_directive`` function::
+
+      from docutils.parsers.rst import directives
+      directives.register_directive(directive_name, directive_class)
+
+
+Examples
+========
+
+For the most direct and accurate information, "Use the Source, Luke!".
+All standard directives are documented in `reStructuredText
+Directives`_, and the source code implementing them is located in the
+``docutils/parsers/rst/directives`` package.  The ``__init__.py``
+module contains a mapping of directive name to module and function
+name.  Several representative directives are described below.
+
+
+Admonitions
+-----------
+
+`Admonition directives`__, such as "note" and "caution", are quite
+simple.  They have no directive arguments or options.  Admonition
+directive content is interpreted as ordinary reStructuredText.
+
+__ ../ref/rst/directives.html#specific-admonitions
+
+The resulting document tree for a simple reStructuredText line
+"``.. note:: This is a note.``" looks as follows:
+
+    <note>
+        <paragraph>
+            This is a note.
+
+The directive class for the "note" directive simply derives from a
+generic admonition directive class::
+
+    class Note(BaseAdmonition):
+
+        node_class = nodes.note
+
+Note that the only thing distinguishing the various admonition
+directives is the element (node class) generated.  In the code above,
+the node class is set as a class attribute and is read by the
+``run()`` method of ``BaseAdmonition``, where the actual processing
+takes place::
+
+    # Import Docutils document tree nodes module.
+    from docutils import nodes
+    # Import Directive base class.
+    from docutils.parsers.rst import Directive
+
+    class BaseAdmonition(Directive):
+
+        required_arguments = 0
+        optional_arguments = 0
+        final_argument_whitespace = True
+        option_spec = {}
+        has_content = True
+
+        node_class = None
+        """Subclasses must set this to the appropriate admonition node class."""
+
+        def run(self):
+            # Raise an error if the directive does not have contents.
+            self.assert_has_content()
+            text = '\n'.join(self.content)
+            # Create the admonition node, to be populated by `nested_parse`.
+            admonition_node = self.node_class(rawsource=text)
+            # Parse the directive contents.
+            self.state.nested_parse(self.content, self.content_offset,
+                                    admonition_node)
+            return [admonition_node]
+
+Three things are noteworthy in the ``run()`` method above:
+
+* The ``admonition_node = self.node_class(text)`` line creates the
+  wrapper element, using the class set by the specific admonition
+  subclasses (as in note, ``node_class = nodes.note``).
+
+* The call to ``state.nested_parse()`` is what does the actual
+  processing.  It parses the directive content and adds any generated
+  elements as child elements of ``admonition_node``.
+
+* If there was no directive content, the ``assert_has_content()``
+  convenience method raises an error exception by calling
+  ``self.error()`` (see `Error Handling`_ above).
+
+
+"image"
+-------
+
+.. _image: ../ref/rst/directives.html#image
+
+The "image_" directive is used to insert a picture into a document.
+This directive has one argument, the path to the image file, and
+supports several options.  There is no directive content.  Here's an
+early version of the image directive class::
+
+    # Import Docutils document tree nodes module.
+    from docutils import nodes
+    # Import ``directives`` module (contains conversion functions).
+    from docutils.parsers.rst import directives
+    # Import Directive base class.
+    from docutils.parsers.rst import Directive
+
+    def align(argument):
+        """Conversion function for the "align" option.""" 
+        return directives.choice(argument, ('left', 'center', 'right'))
+
+    class Image(Directive):
+
+        required_arguments = 1
+        optional_arguments = 0
+        final_argument_whitespace = True
+        option_spec = {'alt': directives.unchanged,
+                       'height': directives.nonnegative_int,
+                       'width': directives.nonnegative_int,
+                       'scale': directives.nonnegative_int,
+                       'align': align,
+                       }
+        has_content = False
+
+        def run(self):
+            reference = directives.uri(self.arguments[0])
+            self.options['uri'] = reference
+            image_node = nodes.image(rawsource=self.block_text,
+                                     **self.options)
+            return [image_node]
+
+Several things are noteworthy in the code above:
+
+* The "image" directive requires a single argument, which is allowed
+  to contain whitespace (``final_argument_whitespace = True``).  This
+  is to allow for long URLs which may span multiple lines.  The first
+  line of the ``run()`` method joins the URL, discarding any embedded
+  whitespace.
+
+* The reference is added to the ``options`` dictionary under the
+  "uri" key; this becomes an attribute of the ``nodes.image`` element
+  object.  Any other attributes have already been set explicitly in
+  the reStructuredText source text.
+
+
+The Pending Element
+-------------------
+
+Directives that cause actions to be performed *after* the complete
+document tree has been generated can be implemented using a
+``pending`` node.  The ``pending`` node causes a transform_ to be run
+after the document has been parsed.
+
+For an example usage of the ``pending`` node, see the implementation
+of the ``contents`` directive in
+docutils.parsers.rst.directives.parts__.
+
+.. _transform: ../ref/transforms.html
+__ http://docutils.sf.net/docutils/parsers/rst/directives/parts.py

docs/howto/rst-roles.txt

@@ -0,0 +1,228 @@
+==================================================
+ Creating reStructuredText Interpreted Text Roles
+==================================================
+
+:Authors: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:Revision: $Revision: 7302 $
+:Copyright: This document has been placed in the public domain.
+
+Interpreted text roles are an extension mechanism for inline markup in
+reStructuredText.  This document aims to make the creation of new
+roles as easy and understandable as possible.
+
+Standard roles are described in `reStructuredText Interpreted Text
+Roles`_.  See the `Interpreted Text`_ section in the `reStructuredText
+Markup Specification`_ for syntax details.
+
+.. _reStructuredText Interpreted Text Roles: ../ref/rst/roles.html
+.. _Interpreted Text:
+   ../ref/rst/restructuredtext.html#interpreted-text
+.. _reStructuredText Markup Specification:
+   ../ref/rst/restructuredtext.html
+
+
+.. contents::
+
+
+Define the Role Function
+========================
+
+The role function creates and returns inline elements (nodes) and does
+any additional processing required.  Its signature is as follows::
+
+    def role_fn(name, rawtext, text, lineno, inliner,
+                options={}, content=[]):
+        code...
+
+    # Set function attributes for customization:
+    role_fn.options = ...
+    role_fn.content = ...
+
+Function attributes are described below (see `Specify Role Function
+Options and Content`_).  The role function parameters are as follows:
+
+* ``name``: The local name of the interpreted role, the role name
+  actually used in the document.
+
+* ``rawtext``: A string containing the enitre interpreted text input,
+  including the role and markup.  Return it as a ``problematic`` node
+  linked to a system message if a problem is encountered.
+
+* ``text``: The interpreted text content.
+
+* ``lineno``: The line number where the interpreted text begins.
+
+* ``inliner``: The ``docutils.parsers.rst.states.Inliner`` object that
+  called role_fn.  It contains the several attributes useful for error
+  reporting and document tree access.
+
+* ``options``: A dictionary of directive options for customization
+  (from the `"role" directive`_), to be interpreted by the role
+  function.  Used for additional attributes for the generated elements
+  and other functionality.
+
+* ``content``: A list of strings, the directive content for
+  customization (from the `"role" directive`_).  To be interpreted by
+  the role function.
+
+Role functions return a tuple of two values:
+
+* A list of nodes which will be inserted into the document tree at the
+  point where the interpreted role was encountered (can be an empty
+  list).
+
+* A list of system messages, which will be inserted into the document tree
+  immediately after the end of the current block (can also be empty).
+
+
+Specify Role Function Options and Content
+=========================================
+
+Function attributes are for customization, and are interpreted by the
+`"role" directive`_.  If unspecified, role function attributes are
+assumed to have the value ``None``.  Two function attributes are
+recognized:
+
+- ``options``: The option specification.  All role functions
+  implicitly support the "class" option, unless disabled with an
+  explicit ``{'class': None}``.
+
+  An option specification must be defined detailing the options
+  available to the "role" directive.  An option spec is a mapping of
+  option name to conversion function; conversion functions are applied
+  to each option value to check validity and convert them to the
+  expected type.  Python's built-in conversion functions are often
+  usable for this, such as ``int``, ``float``, and ``bool`` (included
+  in Python from version 2.2.1).  Other useful conversion functions
+  are included in the ``docutils.parsers.rst.directives`` package.
+  For further details, see `Creating reStructuredText Directives`_.
+
+- ``content``: A boolean; true if "role" directive content is allowed.
+  Role functions must handle the case where content is required but
+  not supplied (an empty content list will be supplied).
+
+  As of this writing, no roles accept directive content.
+
+Note that unlike directives, the "arguments" function attribute is not
+supported for role customization.  Directive arguments are handled by
+the "role" directive itself.
+
+.. _"role" directive: ../ref/rst/directives.html#role
+.. _Creating reStructuredText Directives:
+   rst-directives.html#specify-directive-arguments-options-and-content
+
+
+Register the Role
+=================
+
+If the role is a general-use addition to the Docutils core, it must be
+registered with the parser and language mappings added:
+
+1. Register the new role using the canonical name::
+
+       from docutils.parsers.rst import roles
+       roles.register_canonical_role(name, role_function)
+
+   This code is normally placed immediately after the definition of
+   the role funtion.
+
+2. Add an entry to the ``roles`` dictionary in
+   ``docutils/parsers/rst/languages/en.py`` for the role, mapping the
+   English name to the canonical name (both lowercase).  Usually the
+   English name and the canonical name are the same.  Abbreviations
+   and other aliases may also be added here.
+
+3. Update all the other language modules as well.  For languages in
+   which you are proficient, please add translations.  For other
+   languages, add the English role name plus "(translation required)".
+
+If the role is application-specific, use the ``register_local_role``
+function::
+
+    from docutils.parsers.rst import roles
+    roles.register_local_role(name, role_function)
+
+
+Examples
+========
+
+For the most direct and accurate information, "Use the Source, Luke!".
+All standard roles are documented in `reStructuredText Interpreted
+Text Roles`_, and the source code implementing them is located in the
+``docutils/parsers/rst/roles.py`` module.  Several representative
+roles are described below.
+
+
+Generic Roles
+-------------
+
+Many roles simply wrap a given element around the text.  There's a
+special helper function, ``register_generic_role``, which generates a
+role function from the canonical role name and node class::
+
+    register_generic_role('emphasis', nodes.emphasis)
+
+For the implementation of ``register_generic_role``, see the
+``docutils.parsers.rst.roles`` module.
+
+
+RFC Reference Role
+------------------
+
+This role allows easy references to RFCs_ (Request For Comments
+documents) by automatically providing the base URL,
+http://www.faqs.org/rfcs/, and appending the RFC document itself
+(rfcXXXX.html, where XXXX is the RFC number).  For example::
+
+    See :RFC:`2822` for information about email headers.
+
+This is equivalent to::
+
+    See `RFC 2822`__ for information about email headers.
+
+    __ http://www.faqs.org/rfcs/rfc2822.html
+
+Here is the implementation of the role::
+
+    def rfc_reference_role(role, rawtext, text, lineno, inliner,
+                           options={}, content=[]):
+        try:
+            rfcnum = int(text)
+            if rfcnum <= 0:
+                raise ValueError
+        except ValueError:
+            msg = inliner.reporter.error(
+                'RFC number must be a number greater than or equal to 1; '
+                '"%s" is invalid.' % text, line=lineno)
+            prb = inliner.problematic(rawtext, rawtext, msg)
+            return [prb], [msg]
+        # Base URL mainly used by inliner.rfc_reference, so this is correct:
+        ref = inliner.document.settings.rfc_base_url + inliner.rfc_url % rfcnum
+        set_classes(options)
+        node = nodes.reference(rawtext, 'RFC ' + utils.unescape(text), refuri=ref,
+                               **options)
+        return [node], []
+
+    register_canonical_role('rfc-reference', rfc_reference_role)
+
+Noteworthy in the code above are:
+
+1. The interpreted text itself should contain the RFC number.  The
+   ``try`` clause verifies by converting it to an integer.  If the
+   conversion fails, the ``except`` clause is executed: a system
+   message is generated, the entire interpreted text construct (in
+   ``rawtext``) is wrapped in a ``problematic`` node (linked to the
+   system message), and the two are returned.
+
+2. The RFC reference itself is constructed from a stock URI, set as
+   the "refuri" attribute of a "reference" element.
+
+3. The ``options`` function parameter, a dictionary, may contain a
+   "class" customization attribute; it is interpreted and replaced
+   with a "classes" attribute by the ``set_classes()`` function.  The
+   resulting "classes" attribute is passed through to the "reference"
+   element node constructor.
+
+.. _RFCs: http://foldoc.doc.ic.ac.uk/foldoc/foldoc.cgi?query=rfc&action=Search&sourceid=Mozilla-search

docs/howto/security.txt

@@ -0,0 +1,168 @@
+=============================
+ Deploying Docutils Securely
+=============================
+
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:Revision: $Revision: 7302 $
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+Introduction
+============
+
+Initially, Docutils was intended for command-line tools and
+single-user applications.  Through-the-web editing and processing was
+not envisaged, therefore web security was not a consideration.  Once
+Docutils/reStructuredText started being incorporated into an
+ever-increasing number of web applications (blogs__, wikis__, content
+management systems, and others), several security issues arose and
+have been addressed.  This document provides instructions to help you
+secure the Docutils software in your applications.
+
+Docutils does not come in a through-the-web secure state, because this
+would inconvenience ordinary users
+
+__ ../../FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
+__ ../../FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
+
+
+The Issues
+==========
+
+External Data Insertion
+-----------------------
+
+There are several `reStructuredText directives`_ that can insert
+external data (files and URLs) into the immediate document.  These
+directives are:
+
+* "include_", by its very nature
+* "raw_", through its ``:file:`` and ``:url:`` options
+* "csv-table_", through its ``:file:`` and ``:url:`` options
+
+The "include_" directive and the other directives' file insertion
+features can be disabled by setting "file_insertion_enabled_" to
+0/false.
+
+.. _reStructuredText directives: ../ref/rst/directives.html
+.. _include: ../ref/rst/directives.html#include
+.. _raw: ../ref/rst/directives.html#raw-directive
+.. _csv-table: ../ref/rst/directives.html#csv-table
+.. _file_insertion_enabled: ../user/config.html#file-insertion-enabled
+
+
+Raw HTML Insertion
+------------------
+
+The "raw_" directive is intended for the insertion of
+non-reStructuredText data that is passed untouched to the Writer.
+This directive can be abused to bypass site features or insert
+malicious JavaScript code into a web page.  The "raw_" directive can
+be disabled by setting "raw_enabled_" to 0/false.
+
+.. _raw_enabled: ../user/config.html#raw-enabled
+
+
+Securing Docutils
+=================
+
+Programmatically Via Application Default Settings
+-------------------------------------------------
+
+If your application calls Docutils via one of the `convenience
+functions`_, you can pass a dictionary of default settings that
+override the component defaults::
+
+    defaults = {'file_insertion_enabled': 0,
+                'raw_enabled': 0}
+    output = docutils.core.publish_string(
+        ..., settings_overrides=defaults)
+
+Note that these defaults can be overridden by configuration files (and
+command-line options if applicable).  If this is not desired, you can
+disable configuration file processing with the ``_disable_config``
+setting::
+
+    defaults = {'file_insertion_enabled': 0,
+                'raw_enabled': 0,
+                '_disable_config': 1}
+    output = docutils.core.publish_string(
+        ..., settings_overrides=defaults)
+
+.. _convenience functions: ../api/publisher.html
+
+
+Via a Configuration File
+------------------------
+
+You should secure Docutils via a configuration file:
+
+* if your application executes one of the `Docutils front-end tools`_
+  as a separate process;
+* if you cannot or choose not to alter the source code of your
+  application or the component that calls Docutils; or
+* if you want to secure all Docutils deployments system-wide.
+
+If you call Docutils programmatically, it may be preferable to use the
+methods described in section below.
+
+Docutils automatically looks in three places for a configuration file:
+
+* ``/etc/docutils.conf``, for system-wide configuration,
+* ``./docutils.conf`` (in the current working directory), for
+  project-specific configuration, and
+* ``~/.docutils`` (in the user's home directory), for user-specific
+  configuration.
+
+These locations can be overridden by the ``DOCUTILSCONFIG``
+environment variable.  Details about configuration files, the purpose
+of the various locations, and ``DOCUTILSCONFIG`` are available in the
+`"Configuration Files"`_ section of `Docutils Configuration`_.
+
+To fully secure your Docutils installation, the configuration file
+should contain the following lines::
+
+    [general]
+    file-insertion-enabled:
+    raw-enabled:
+
+.. Note:: Due to a bug in the definitions of these security-related
+   settings, the right-hand-side of the above lines (the values)
+   should be left blank, as shown.  The bug was corrected on
+   2006-11-12 and is reflected in Docutils releases 0.4.1 and higher.
+   In these versions, more verbose forms may be used, such as::
+
+       [general]
+       file-insertion-enabled: off
+       raw-enabled: no
+
+.. _Docutils front-end tools: ../user/tools.html
+.. _"Configuration Files": ../user/config.html#configuration-files
+.. _Docutils Configuration: ../user/config.html
+
+
+Version Applicability
+=====================
+
+The ``file_insertion_enabled`` & ``raw_enabled`` settings were added
+to Docutils 0.3.9; previous versions will ignore these settings.  A
+bug existed in the configuration file handling of these settings in
+Docutils 0.4 and earlier.  The bug was fixed with the 0.4.1 release on
+2006-11-12.
+
+
+Related Documents
+=================
+
+`Docutils Runtime Settings`_ explains the relationship between
+component settings specifications, application settings
+specifications, configuration files, and command-line options
+
+`Docutils Configuration`_ describes configuration files (locations,
+structure, and syntax), and lists all settings and command-line
+options.
+
+.. _Docutils Runtime Settings: ../api/runtime-settings.html

docs/index.txt

@@ -0,0 +1,239 @@
+==========================================
+ Docutils_ Project Documentation Overview
+==========================================
+
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date: 2016-01-13 22:09:13 +0100 (Mi, 13 Jan 2016) $
+:Revision: $Revision: 7933 $
+:Copyright: This document has been placed in the public domain.
+
+The latest working documents may be accessed individually below, or
+from the ``docs`` directory of the `Docutils distribution`_.
+
+.. _Docutils: http://docutils.sourceforge.net/
+.. _Docutils distribution: http://docutils.sourceforge.net/#download
+
+.. contents::
+
+
+Docutils Stakeholders
+=====================
+
+Docutils stakeholders can be categorized in several groups:
+
+1. End-users: users of reStructuredText and the Docutils tools.
+   Although some are developers (e.g. Python developers utilizing
+   reStructuredText for docstrings in their source), many are not.
+
+2. Client-developers: developers using Docutils as a library,
+   programmers developing *with* Docutils.
+
+3. Component-developers: those who implement application-specific
+   components, directives, and/or roles, separately from Docutils.
+
+4. Core-developers: developers of the Docutils codebase and
+   participants in the Docutils project community.
+
+5. Re-implementers: developers of alternate implementations of
+   Docutils.
+
+There's a lot of overlap between these groups.  Most (perhaps all)
+core-developers, component-developers, client-developers, and
+re-implementers are also end-users.  Core-developers are also
+client-developers, and may also be component-developers in other
+projects.  Component-developers are also client-developers.
+
+
+Project Fundamentals
+====================
+
+These files are for all Docutils stakeholders.  They are kept at the
+top level of the Docutils project directory.
+
+:README.txt_: Project overview: quick-start, requirements,
+              installation, and usage.
+:COPYING.txt_: Conditions for Docutils redistribution, with links to
+               licenses.
+:FAQ.txt_: Docutils Frequently Asked Questions.  If you have a
+           question or issue, there's a good chance it's already
+           answered here.
+:BUGS.txt_: A list of known bugs, and how to report a bug.
+:RELEASE-NOTES.txt_: Summary of the major changes in recent releases.
+:HISTORY.txt_: Detailed change history log.
+:THANKS.txt_: Acknowledgements.
+
+.. _README.txt: ../README.html
+.. _BUGS.txt: ../BUGS.html
+.. _COPYING.txt: ../COPYING.html
+.. _Docutils FAQ:
+.. _FAQ.txt: ../FAQ.html
+.. _RELEASE-NOTES.txt: ../RELEASE-NOTES.html
+.. _HISTORY.txt: ../HISTORY.html
+.. _THANKS.txt: ../THANKS.html
+
+
+.. _user:
+
+``user/``: Introductory & Tutorial Material for End-Users
+=========================================================
+
+Docutils-general:
+
+* `Docutils Front-End Tools <user/tools.html>`__
+* `Docutils Configuration <user/config.html>`__
+* `Docutils Mailing Lists <user/mailing-lists.html>`__
+* `Docutils Link List <user/links.html>`__
+
+Writer-specific:
+
+* `Docutils HTML writers <user/html.html>`__
+* `Easy Slide Shows With reStructuredText & S5 <user/slide-shows.html>`__
+* `Docutils LaTeX Writer <user/latex.html>`__
+* `Docutils ODF/OpenOffice/odt Writer <user/odt.html>`__
+
+`reStructuredText <http://docutils.sourceforge.net/rst.html>`_:
+
+* `A ReStructuredText Primer (HTML) <user/rst/quickstart.html>`__ (or
+  `text source <user/rst/quickstart.txt>`__)
+* `Quick reStructuredText <user/rst/quickref.html>`__ (user reference)
+* `reStructuredText Cheat Sheet <user/rst/cheatsheet.txt>`__ (text
+  only; 1 page for syntax, 1 page directive & role reference)
+* `reStructuredText Demonstration <user/rst/demo.html>`_ (a
+  demonstration of most reStructuredText features; you can also have a
+  look at the `text source <user/rst/demo.txt>`__)
+
+Editor support:
+
+* `Emacs support for reStructuredText <user/emacs.html>`_
+
+
+.. _ref:
+
+``ref/``: Reference Material for All Groups
+===========================================
+
+Many of these files began as developer specifications, but now that
+they're mature and used by end-users and client-developers, they have
+become reference material.  Successful specs evolve into refs.
+
+Docutils-general:
+
+* `The Docutils Document Tree <ref/doctree.html>`__ (incomplete)
+* `Docutils Transforms <ref/transforms.html>`__
+* `Docutils Generic DTD <ref/docutils.dtd>`__
+* `OASIS XML Exchange Table Model Declaration Module
+  <ref/soextblx.dtd>`__ (CALS tables DTD module)
+
+Although not in the "ref" directory, `PEP 258`_ is a must-read
+reference for any Docutils developer.
+
+reStructuredText_:
+
+* `An Introduction to reStructuredText <ref/rst/introduction.html>`__
+  (includes the `Goals <ref/rst/introduction.html#goals>`__ and
+  `History <ref/rst/introduction.html#history>`__ of reStructuredText)
+* `reStructuredText Markup Specification <ref/rst/restructuredtext.html>`__
+* `reStructuredText Directives <ref/rst/directives.html>`__
+* `reStructuredText Interpreted Text Roles <ref/rst/roles.html>`__
+* `reStructuredText Standard Definition Files
+  <ref/rst/definitions.html>`_
+
+Prehistoric:
+
+* `Setext Documents Mirror
+  <http://docutils.sourceforge.net/mirror/setext.html>`__
+
+
+.. _peps:
+
+``peps/``: Python Enhancement Proposals
+=======================================
+
+* `PEP 256: Docstring Processing System Framework`__ is a high-level
+  generic proposal.  [`PEP 256`__ in the `master repository`_]
+* `PEP 257: Docstring Conventions`__ addresses docstring style and
+  touches on content.  [`PEP 257`__ in the `master repository`_]
+* `PEP 258: Docutils Design Specification`__ is an overview of the
+  architecture of Docutils.  It documents design issues and
+  implementation details.  [`PEP 258`__ in the `master repository`_]
+* `PEP 287: reStructuredText Docstring Format`__ proposes a standard
+  markup syntax.  [`PEP 287`__ in the `master repository`_]
+
+Please note that PEPs in the `master repository`_ may not be current,
+whereas the local versions are.
+
+__ peps/pep-0256.html
+__ http://www.python.org/peps/pep-0256.html
+__ peps/pep-0257.html
+__ http://www.python.org/peps/pep-0257.html
+.. _PEP 258:
+__ peps/pep-0258.html
+__ http://www.python.org/peps/pep-0258.html
+__ peps/pep-0287.html
+__ http://www.python.org/peps/pep-0287.html
+.. _master repository: http://www.python.org/peps/
+
+
+.. _api:
+
+``api/``: API Reference Material for Client-Developers
+======================================================
+
+* `The Docutils Publisher <api/publisher.html>`__
+* `Inside A Docutils Command-Line Front-End Tool <api/cmdline-tool.html>`__
+* `Docutils Runtime Settings <api/runtime-settings.html>`__
+* (`Docutils Transforms <ref/transforms.html>`__ should be moved here)
+
+`PEP 258`_ is an overview of the architecture of Docutils.
+
+
+.. _howto:
+
+``howto/``: Instructions for Developers
+=======================================
+
+* **Security:** `Deploying Docutils Securely <howto/security.html>`__
+* `Writing HTML (CSS) Stylesheets for Docutils
+  <howto/html-stylesheets.html>`__
+* `Docutils Internationalization <howto/i18n.html>`__
+* `Creating reStructuredText Directives <howto/rst-directives.html>`__
+* `Creating reStructuredText Interpreted Text Roles
+  <howto/rst-roles.html>`__
+
+
+.. _dev:
+
+``dev/``: Development Notes and Plans for Core-Developers
+=========================================================
+
+Docutils-general:
+
+* `Docutils Hacker's Guide <dev/hacking.html>`__
+* `Docutils Distributor's Guide <dev/distributing.html>`__
+* `Docutils To Do List <dev/todo.html>`__
+* `Docutils Project Policies <dev/policies.html>`__
+* `Docutils Web Site <dev/website.html>`__
+* `Docutils Release Procedure <dev/release.html>`__
+* `The Docutils Subversion Repository <dev/repository.html>`__
+* `Docutils Testing <dev/testing.html>`__
+* `Docstring Semantics <dev/semantics.html>`__ (incomplete)
+* `Python Source Reader <dev/pysource.html>`_ (incomplete)
+* `Docutils Python DTD <dev/pysource.dtd>`_ (experimental)
+* `Plan for Enthought API Documentation Tool <dev/enthought-plan.html>`_
+* `Enthought API Documentation Tool RFP <dev/enthought-rfp.html>`_
+
+reStructuredText_:
+
+* `A Record of reStructuredText Syntax Alternatives
+  <dev/rst/alternatives.html>`__
+* `Problems With StructuredText <dev/rst/problems.html>`__
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

docs/peps/pep-0256.txt

@@ -0,0 +1,297 @@
+PEP: 256
+Title: Docstring Processing System Framework
+Version: $Revision: 4564 $
+Last-Modified: $Date: 2006-05-21 22:44:42 +0200 (So, 21 Mai 2006) $
+Author: David Goodger <goodger@python.org>
+Discussions-To: <doc-sig@python.org>
+Status: Draft
+Type: Standards Track
+Content-Type: text/x-rst
+Created: 01-Jun-2001
+Post-History: 13-Jun-2001
+
+
+Abstract
+========
+
+Python lends itself to inline documentation.  With its built-in
+docstring syntax, a limited form of `Literate Programming`_ is easy to
+do in Python.  However, there are no satisfactory standard tools for
+extracting and processing Python docstrings.  The lack of a standard
+toolset is a significant gap in Python's infrastructure; this PEP aims
+to fill the gap.
+
+The issues surrounding docstring processing have been contentious and
+difficult to resolve.  This PEP proposes a generic Docstring
+Processing System (DPS) framework, which separates out the components
+(program and conceptual), enabling the resolution of individual issues
+either through consensus (one solution) or through divergence (many).
+It promotes standard interfaces which will allow a variety of plug-in
+components (input context readers, markup parsers, and output format
+writers) to be used.
+
+The concepts of a DPS framework are presented independently of
+implementation details.
+
+
+Road Map to the Docstring PEPs
+==============================
+
+There are many aspects to docstring processing.  The "Docstring PEPs"
+have broken up the issues in order to deal with each of them in
+isolation, or as close as possible.  The individual aspects and
+associated PEPs are as follows:
+
+* Docstring syntax.  PEP 287, "reStructuredText Docstring Format"
+  [#PEP-287]_, proposes a syntax for Python docstrings, PEPs, and
+  other uses.
+
+* Docstring semantics consist of at least two aspects:
+
+  - Conventions: the high-level structure of docstrings.  Dealt with
+    in PEP 257, "Docstring Conventions" [#PEP-257]_.
+
+  - Methodology: rules for the informational content of docstrings.
+    Not addressed.
+
+* Processing mechanisms.  This PEP (PEP 256) outlines the high-level
+  issues and specification of an abstract docstring processing system
+  (DPS).  PEP 258, "Docutils Design Specification" [#PEP-258]_, is an
+  overview of the design and implementation of one DPS under
+  development.
+
+* Output styles: developers want the documentation generated from
+  their source code to look good, and there are many different ideas
+  about what that means.  PEP 258 touches on "Stylist Transforms".
+  This aspect of docstring processing has yet to be fully explored.
+
+By separating out the issues, we can form consensus more easily
+(smaller fights ;-), and accept divergence more readily.
+
+
+Rationale
+=========
+
+There are standard inline documentation systems for some other
+languages.  For example, Perl has POD_ ("Plain Old Documentation") and
+Java has Javadoc_, but neither of these mesh with the Pythonic way.
+POD syntax is very explicit, but takes after Perl in terms of
+readability.  Javadoc is HTML-centric; except for "``@field``" tags,
+raw HTML is used for markup.  There are also general tools such as
+Autoduck_ and Web_ (Tangle & Weave), useful for multiple languages.
+
+There have been many attempts to write auto-documentation systems
+for Python (not an exhaustive list):
+
+- Marc-Andre Lemburg's doc.py_
+
+- Daniel Larsson's pythondoc_ & gendoc_
+
+- Doug Hellmann's HappyDoc_
+
+- Laurence Tratt's Crystal (no longer available on the web)
+
+- Ka-Ping Yee's pydoc_ (pydoc.py is now part of the Python standard
+  library; see below)
+
+- Tony Ibbs' docutils_ (Tony has donated this name to the `Docutils
+  project`_)
+
+- Edward Loper's STminus_ formalization and related efforts
+
+These systems, each with different goals, have had varying degrees of
+success.  A problem with many of the above systems was over-ambition
+combined with inflexibility.  They provided a self-contained set of
+components: a docstring extraction system, a markup parser, an
+internal processing system and one or more output format writers with
+a fixed style.  Inevitably, one or more aspects of each system had
+serious shortcomings, and they were not easily extended or modified,
+preventing them from being adopted as standard tools.
+
+It has become clear (to this author, at least) that the "all or
+nothing" approach cannot succeed, since no monolithic self-contained
+system could possibly be agreed upon by all interested parties.  A
+modular component approach designed for extension, where components
+may be multiply implemented, may be the only chance for success.
+Standard inter-component APIs will make the DPS components
+comprehensible without requiring detailed knowledge of the whole,
+lowering the barrier for contributions, and ultimately resulting in a
+rich and varied system.
+
+Each of the components of a docstring processing system should be
+developed independently.  A "best of breed" system should be chosen,
+either merged from existing systems, and/or developed anew.  This
+system should be included in Python's standard library.
+
+
+PyDoc & Other Existing Systems
+------------------------------
+
+PyDoc became part of the Python standard library as of release 2.1.
+It extracts and displays docstrings from within the Python interactive
+interpreter, from the shell command line, and from a GUI window into a
+web browser (HTML).  Although a very useful tool, PyDoc has several
+deficiencies, including:
+
+- In the case of the GUI/HTML, except for some heuristic hyperlinking
+  of identifier names, no formatting of the docstrings is done.  They
+  are presented within ``<p><small><tt>`` tags to avoid unwanted line
+  wrapping.  Unfortunately, the result is not attractive.
+
+- PyDoc extracts docstrings and structural information (class
+  identifiers, method signatures, etc.) from imported module objects.
+  There are security issues involved with importing untrusted code.
+  Also, information from the source is lost when importing, such as
+  comments, "additional docstrings" (string literals in non-docstring
+  contexts; see PEP 258 [#PEP-258]_), and the order of definitions.
+
+The functionality proposed in this PEP could be added to or used by
+PyDoc when serving HTML pages.  The proposed docstring processing
+system's functionality is much more than PyDoc needs in its current
+form.  Either an independent tool will be developed (which PyDoc may
+or may not use), or PyDoc could be expanded to encompass this
+functionality and *become* the docstring processing system (or one
+such system).  That decision is beyond the scope of this PEP.
+
+Similarly for other existing docstring processing systems, their
+authors may or may not choose compatibility with this framework.
+However, if this framework is accepted and adopted as the Python
+standard, compatibility will become an important consideration in
+these systems' future.
+
+
+Specification
+=============
+
+The docstring processing system framework is broken up as follows:
+
+1. Docstring conventions.  Documents issues such as:
+
+   - What should be documented where.
+
+   - First line is a one-line synopsis.
+
+   PEP 257 [#PEP-257]_ documents some of these issues.
+
+2. Docstring processing system design specification.  Documents
+   issues such as:
+
+   - High-level spec: what a DPS does.
+
+   - Command-line interface for executable script.
+
+   - System Python API.
+
+   - Docstring extraction rules.
+
+   - Readers, which encapsulate the input context.
+
+   - Parsers.
+
+   - Document tree: the intermediate internal data structure.  The
+     output of the Parser and Reader, and the input to the Writer all
+     share the same data structure.
+
+   - Transforms, which modify the document tree.
+
+   - Writers for output formats.
+
+   - Distributors, which handle output management (one file, many
+     files, or objects in memory).
+
+   These issues are applicable to any docstring processing system
+   implementation.  PEP 258 [#PEP-258]_ documents these issues.
+
+3. Docstring processing system implementation.
+
+4. Input markup specifications: docstring syntax.  PEP 287 [#PEP-287]_
+   proposes a standard syntax.
+
+5. Input parser implementations.
+
+6. Input context readers ("modes": Python source code, PEP, standalone
+   text file, email, etc.) and implementations.
+
+7. Stylists: certain input context readers may have associated
+   stylists which allow for a variety of output document styles.
+
+8. Output formats (HTML, XML, TeX, DocBook, info, etc.) and writer
+   implementations.
+
+Components 1, 2/3/5, and 4 are the subject of individual companion
+PEPs.  If there is another implementation of the framework or
+syntax/parser, additional PEPs may be required.  Multiple
+implementations of each of components 6 and 7 will be required; the
+PEP mechanism may be overkill for these components.
+
+
+Project Web Site
+================
+
+A SourceForge project has been set up for this work at
+http://docutils.sourceforge.net/.
+
+
+References and Footnotes
+========================
+
+.. [#PEP-287] PEP 287, reStructuredText Docstring Format, Goodger
+   (http://www.python.org/peps/pep-0287.html)
+
+.. [#PEP-257] PEP 257, Docstring Conventions, Goodger, Van Rossum
+   (http://www.python.org/peps/pep-0257.html)
+
+.. [#PEP-258] PEP 258, Docutils Design Specification, Goodger
+   (http://www.python.org/peps/pep-0258.html)
+
+.. _Literate Programming: http://www.literateprogramming.com/
+
+.. _POD: http://perldoc.perl.org/perlpod.html
+
+.. _Javadoc: http://java.sun.com/j2se/javadoc/
+
+.. _Autoduck:
+   http://www.helpmaster.com/hlp-developmentaids-autoduck.htm
+
+.. _Web: http://www-cs-faculty.stanford.edu/~knuth/cweb.html
+
+.. _doc.py:
+   http://www.egenix.com/files/python/SoftwareDescriptions.html#doc.py
+
+.. _pythondoc:
+.. _gendoc: http://starship.python.net/crew/danilo/pythondoc/
+
+.. _HappyDoc: http://happydoc.sourceforge.net/
+
+.. _pydoc: http://www.python.org/doc/current/lib/module-pydoc.html
+
+.. _docutils: http://www.tibsnjoan.co.uk/docutils.html
+
+.. _Docutils project: http://docutils.sourceforge.net/
+
+.. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/
+
+.. _Python Doc-SIG: http://www.python.org/sigs/doc-sig/
+
+
+Copyright
+=========
+
+This document has been placed in the public domain.
+
+
+Acknowledgements
+================
+
+This document borrows ideas from the archives of the `Python
+Doc-SIG`_.  Thanks to all members past & present.
+
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

docs/peps/pep-0257.txt

@@ -0,0 +1,328 @@
+PEP: 257
+Title: Docstring Conventions
+Version: $Revision: 4564 $
+Last-Modified: $Date: 2006-05-21 22:44:42 +0200 (So, 21 Mai 2006) $
+Authors: David Goodger <goodger@python.org>,
+         Guido van Rossum <guido@python.org>
+Discussions-To: doc-sig@python.org
+Status: Active
+Type: Informational
+Content-Type: text/x-rst
+Created: 29-May-2001
+Post-History: 13-Jun-2001
+
+
+Abstract
+========
+
+This PEP documents the semantics and conventions associated with
+Python docstrings.
+
+
+Rationale
+=========
+
+The aim of this PEP is to standardize the high-level structure of
+docstrings: what they should contain, and how to say it (without
+touching on any markup syntax within docstrings).  The PEP contains
+conventions, not laws or syntax.
+
+    "A universal convention supplies all of maintainability, clarity,
+    consistency, and a foundation for good programming habits too.
+    What it doesn't do is insist that you follow it against your will.
+    That's Python!"
+
+    -- Tim Peters on comp.lang.python, 2001-06-16
+
+If you violate these conventions, the worst you'll get is some dirty
+looks.  But some software (such as the Docutils_ docstring processing
+system [1]_ [2]_) will be aware of the conventions, so following them
+will get you the best results.
+
+
+Specification
+=============
+
+What is a Docstring?
+--------------------
+
+A docstring is a string literal that occurs as the first statement in
+a module, function, class, or method definition.  Such a docstring
+becomes the ``__doc__`` special attribute of that object.
+
+All modules should normally have docstrings, and all functions and
+classes exported by a module should also have docstrings.  Public
+methods (including the ``__init__`` constructor) should also have
+docstrings.  A package may be documented in the module docstring of
+the ``__init__.py`` file in the package directory.
+
+String literals occurring elsewhere in Python code may also act as
+documentation.  They are not recognized by the Python bytecode
+compiler and are not accessible as runtime object attributes (i.e. not
+assigned to ``__doc__``), but two types of extra docstrings may be
+extracted by software tools:
+
+1. String literals occurring immediately after a simple assignment at
+   the top level of a module, class, or ``__init__`` method are called
+   "attribute docstrings".
+
+2. String literals occurring immediately after another docstring are
+   called "additional docstrings".
+
+Please see PEP 258, "Docutils Design Specification" [2]_, for a
+detailed description of attribute and additional docstrings.
+
+XXX Mention docstrings of 2.2 properties.
+
+For consistency, always use ``"""triple double quotes"""`` around
+docstrings.  Use ``r"""raw triple double quotes"""`` if you use any
+backslashes in your docstrings.  For Unicode docstrings, use
+``u"""Unicode triple-quoted strings"""``.
+
+There are two forms of docstrings: one-liners and multi-line
+docstrings.
+
+
+One-line Docstrings
+--------------------
+
+One-liners are for really obvious cases.  They should really fit on
+one line.  For example::
+
+    def kos_root():
+        """Return the pathname of the KOS root directory."""
+        global _kos_root
+        if _kos_root: return _kos_root
+        ...
+
+Notes:
+
+- Triple quotes are used even though the string fits on one line.
+  This makes it easy to later expand it.
+
+- The closing quotes are on the same line as the opening quotes.  This
+  looks better for one-liners.
+
+- There's no blank line either before or after the docstring.
+
+- The docstring is a phrase ending in a period.  It prescribes the
+  function or method's effect as a command ("Do this", "Return that"),
+  not as a description; e.g. don't write "Returns the pathname ...".
+
+- The one-line docstring should NOT be a "signature" reiterating the
+  function/method parameters (which can be obtained by introspection).
+  Don't do::
+
+      def function(a, b):
+          """function(a, b) -> list"""
+
+  This type of docstring is only appropriate for C functions (such as
+  built-ins), where introspection is not possible.  However, the
+  nature of the *return value* cannot be determined by introspection,
+  so it should be mentioned.  The preferred form for such a docstring
+  would be something like::
+
+      def function(a, b):
+          """Do X and return a list."""
+
+  (Of course "Do X" should be replaced by a useful description!)
+
+
+Multi-line Docstrings
+----------------------
+
+Multi-line docstrings consist of a summary line just like a one-line
+docstring, followed by a blank line, followed by a more elaborate
+description.  The summary line may be used by automatic indexing
+tools; it is important that it fits on one line and is separated from
+the rest of the docstring by a blank line.  The summary line may be on
+the same line as the opening quotes or on the next line.  The entire
+docstring is indented the same as the quotes at its first line (see
+example below).
+
+Insert a blank line before and after all docstrings (one-line or
+multi-line) that document a class -- generally speaking, the class's
+methods are separated from each other by a single blank line, and the
+docstring needs to be offset from the first method by a blank line;
+for symmetry, put a blank line between the class header and the
+docstring.  Docstrings documenting functions or methods generally
+don't have this requirement, unless the function or method's body is
+written as a number of blank-line separated sections -- in this case,
+treat the docstring as another section, and precede it with a blank
+line.
+
+The docstring of a script (a stand-alone program) should be usable as
+its "usage" message, printed when the script is invoked with incorrect
+or missing arguments (or perhaps with a "-h" option, for "help").
+Such a docstring should document the script's function and command
+line syntax, environment variables, and files.  Usage messages can be
+fairly elaborate (several screens full) and should be sufficient for a
+new user to use the command properly, as well as a complete quick
+reference to all options and arguments for the sophisticated user.
+
+The docstring for a module should generally list the classes,
+exceptions and functions (and any other objects) that are exported by
+the module, with a one-line summary of each.  (These summaries
+generally give less detail than the summary line in the object's
+docstring.)  The docstring for a package (i.e., the docstring of the
+package's ``__init__.py`` module) should also list the modules and
+subpackages exported by the package.
+
+The docstring for a function or method should summarize its behavior
+and document its arguments, return value(s), side effects, exceptions
+raised, and restrictions on when it can be called (all if applicable).
+Optional arguments should be indicated.  It should be documented
+whether keyword arguments are part of the interface.
+
+The docstring for a class should summarize its behavior and list the
+public methods and instance variables.  If the class is intended to be
+subclassed, and has an additional interface for subclasses, this
+interface should be listed separately (in the docstring).  The class
+constructor should be documented in the docstring for its ``__init__``
+method.  Individual methods should be documented by their own
+docstring.
+
+If a class subclasses another class and its behavior is mostly
+inherited from that class, its docstring should mention this and
+summarize the differences.  Use the verb "override" to indicate that a
+subclass method replaces a superclass method and does not call the
+superclass method; use the verb "extend" to indicate that a subclass
+method calls the superclass method (in addition to its own behavior).
+
+*Do not* use the Emacs convention of mentioning the arguments of
+functions or methods in upper case in running text.  Python is case
+sensitive and the argument names can be used for keyword arguments, so
+the docstring should document the correct argument names.  It is best
+to list each argument on a separate line.  For example::
+
+    def complex(real=0.0, imag=0.0):
+        """Form a complex number.
+
+        Keyword arguments:
+        real -- the real part (default 0.0)
+        imag -- the imaginary part (default 0.0)
+
+        """
+        if imag == 0.0 and real == 0.0: return complex_zero
+        ...
+
+The BDFL [3]_ recommends inserting a blank line between the last
+paragraph in a multi-line docstring and its closing quotes, placing
+the closing quotes on a line by themselves.  This way, Emacs'
+``fill-paragraph`` command can be used on it.
+
+
+Handling Docstring Indentation
+------------------------------
+
+Docstring processing tools will strip a uniform amount of indentation
+from the second and further lines of the docstring, equal to the
+minimum indentation of all non-blank lines after the first line.  Any
+indentation in the first line of the docstring (i.e., up to the first
+newline) is insignificant and removed.  Relative indentation of later
+lines in the docstring is retained.  Blank lines should be removed
+from the beginning and end of the docstring.
+
+Since code is much more precise than words, here is an implementation
+of the algorithm::
+
+    def trim(docstring):
+        if not docstring:
+            return ''
+        # Convert tabs to spaces (following the normal Python rules)
+        # and split into a list of lines:
+        lines = docstring.expandtabs().splitlines()
+        # Determine minimum indentation (first line doesn't count):
+        indent = sys.maxint
+        for line in lines[1:]:
+            stripped = line.lstrip()
+            if stripped:
+                indent = min(indent, len(line) - len(stripped))
+        # Remove indentation (first line is special):
+        trimmed = [lines[0].strip()]
+        if indent < sys.maxint:
+            for line in lines[1:]:
+                trimmed.append(line[indent:].rstrip())
+        # Strip off trailing and leading blank lines:
+        while trimmed and not trimmed[-1]:
+            trimmed.pop()
+        while trimmed and not trimmed[0]:
+            trimmed.pop(0)
+        # Return a single string:
+        return '\n'.join(trimmed)
+
+The docstring in this example contains two newline characters and is
+therefore 3 lines long.  The first and last lines are blank::
+
+    def foo():
+        """
+        This is the second line of the docstring.
+        """
+
+To illustrate::
+
+    >>> print repr(foo.__doc__)
+    '\n    This is the second line of the docstring.\n    '
+    >>> foo.__doc__.splitlines()
+    ['', '    This is the second line of the docstring.', '    ']
+    >>> trim(foo.__doc__)
+    'This is the second line of the docstring.'
+
+Once trimmed, these docstrings are equivalent::
+
+    def foo():
+        """A multi-line
+        docstring.
+        """
+
+    def bar():
+        """
+        A multi-line
+        docstring.
+        """
+
+
+References and Footnotes
+========================
+
+.. [1] PEP 256, Docstring Processing System Framework, Goodger
+   (http://www.python.org/peps/pep-0256.html)
+
+.. [2] PEP 258, Docutils Design Specification, Goodger
+   (http://www.python.org/peps/pep-0258.html)
+
+.. [3] Guido van Rossum, Python's creator and Benevolent Dictator For
+   Life.
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+.. _Python Style Guide:
+   http://www.python.org/doc/essays/styleguide.html
+
+.. _Doc-SIG: http://www.python.org/sigs/doc-sig/
+
+
+Copyright
+=========
+
+This document has been placed in the public domain.
+
+
+Acknowledgements
+================
+
+The "Specification" text comes mostly verbatim from the `Python Style
+Guide`_ essay by Guido van Rossum.
+
+This document borrows ideas from the archives of the Python Doc-SIG_.
+Thanks to all members past and present.
+
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   fill-column: 70
+   sentence-end-double-space: t
+   End:

docs/peps/pep-0287.txt

@@ -0,0 +1,815 @@
+PEP: 287
+Title: reStructuredText Docstring Format
+Version: $Revision: 4564 $
+Last-Modified: $Date: 2006-05-21 22:44:42 +0200 (So, 21 Mai 2006) $
+Author: David Goodger <goodger@python.org>
+Discussions-To: <doc-sig@python.org>
+Status: Draft
+Type: Informational
+Content-Type: text/x-rst
+Created: 25-Mar-2002
+Post-History: 02-Apr-2002
+Replaces: 216
+
+
+Abstract
+========
+
+When plaintext hasn't been expressive enough for inline documentation,
+Python programmers have sought out a format for docstrings.  This PEP
+proposes that the `reStructuredText markup`_ be adopted as a standard
+markup format for structured plaintext documentation in Python
+docstrings, and for PEPs and ancillary documents as well.
+reStructuredText is a rich and extensible yet easy-to-read,
+what-you-see-is-what-you-get plaintext markup syntax.
+
+Only the low-level syntax of docstrings is addressed here.  This PEP
+is not concerned with docstring semantics or processing at all (see
+PEP 256 for a "Road Map to the Docstring PEPs").  Nor is it an attempt
+to deprecate pure plaintext docstrings, which are always going to be
+legitimate.  The reStructuredText markup is an alternative for those
+who want more expressive docstrings.
+
+
+Benefits
+========
+
+Programmers are by nature a lazy breed.  We reuse code with functions,
+classes, modules, and subsystems.  Through its docstring syntax,
+Python allows us to document our code from within.  The "holy grail"
+of the Python Documentation Special Interest Group (Doc-SIG_) has been
+a markup syntax and toolset to allow auto-documentation, where the
+docstrings of Python systems can be extracted in context and processed
+into useful, high-quality documentation for multiple purposes.
+
+Document markup languages have three groups of customers: the authors
+who write the documents, the software systems that process the data,
+and the readers, who are the final consumers and the most important
+group.  Most markups are designed for the authors and software
+systems; readers are only meant to see the processed form, either on
+paper or via browser software.  ReStructuredText is different: it is
+intended to be easily readable in source form, without prior knowledge
+of the markup.  ReStructuredText is entirely readable in plaintext
+format, and many of the markup forms match common usage (e.g.,
+``*emphasis*``), so it reads quite naturally.  Yet it is rich enough
+to produce complex documents, and extensible so that there are few
+limits.  Of course, to write reStructuredText documents some prior
+knowledge is required.
+
+The markup offers functionality and expressivity, while maintaining
+easy readability in the source text.  The processed form (HTML etc.)
+makes it all accessible to readers: inline live hyperlinks; live links
+to and from footnotes; automatic tables of contents (with live
+links!); tables; images for diagrams etc.; pleasant, readable styled
+text.
+
+The reStructuredText parser is available now, part of the Docutils_
+project.  Standalone reStructuredText documents and PEPs can be
+converted to HTML; other output format writers are being worked on and
+will become available over time.  Work is progressing on a Python
+source "Reader" which will implement auto-documentation from
+docstrings.  Authors of existing auto-documentation tools are
+encouraged to integrate the reStructuredText parser into their
+projects, or better yet, to join forces to produce a world-class
+toolset for the Python standard library.
+
+Tools will become available in the near future, which will allow
+programmers to generate HTML for online help, XML for multiple
+purposes, and eventually PDF, DocBook, and LaTeX for printed
+documentation, essentially "for free" from the existing docstrings.
+The adoption of a standard will, at the very least, benefit docstring
+processing tools by preventing further "reinventing the wheel".
+
+Eventually PyDoc, the one existing standard auto-documentation tool,
+could have reStructuredText support added.  In the interim it will
+have no problem with reStructuredText markup, since it treats all
+docstrings as preformatted plaintext.
+
+
+Goals
+=====
+
+These are the generally accepted goals for a docstring format, as
+discussed in the Doc-SIG:
+
+1. It must be readable in source form by the casual observer.
+
+2. It must be easy to type with any standard text editor.
+
+3. It must not need to contain information which can be deduced from
+   parsing the module.
+
+4. It must contain sufficient information (structure) so it can be
+   converted to any reasonable markup format.
+
+5. It must be possible to write a module's entire documentation in
+   docstrings, without feeling hampered by the markup language.
+
+reStructuredText meets and exceeds all of these goals, and sets its
+own goals as well, even more stringent.  See `Docstring-Significant
+Features`_ below.
+
+The goals of this PEP are as follows:
+
+1. To establish reStructuredText as a standard structured plaintext
+   format for docstrings (inline documentation of Python modules and
+   packages), PEPs, README-type files and other standalone documents.
+   "Accepted" status will be sought through Python community consensus
+   and eventual BDFL pronouncement.
+
+   Please note that reStructuredText is being proposed as *a*
+   standard, not *the only* standard.  Its use will be entirely
+   optional.  Those who don't want to use it need not.
+
+2. To solicit and address any related concerns raised by the Python
+   community.
+
+3. To encourage community support.  As long as multiple competing
+   markups are out there, the development community remains fractured.
+   Once a standard exists, people will start to use it, and momentum
+   will inevitably gather.
+
+4. To consolidate efforts from related auto-documentation projects.
+   It is hoped that interested developers will join forces and work on
+   a joint/merged/common implementation.
+
+Once reStructuredText is a Python standard, effort can be focused on
+tools instead of arguing for a standard.  Python needs a standard set
+of documentation tools.
+
+With regard to PEPs, one or both of the following strategies may be
+applied:
+
+a) Keep the existing PEP section structure constructs (one-line
+   section headers, indented body text).  Subsections can either be
+   forbidden, or supported with reStructuredText-style underlined
+   headers in the indented body text.
+
+b) Replace the PEP section structure constructs with the
+   reStructuredText syntax.  Section headers will require underlines,
+   subsections will be supported out of the box, and body text need
+   not be indented (except for block quotes).
+
+Strategy (b) is recommended, and its implementation is complete.
+
+Support for RFC 2822 headers has been added to the reStructuredText
+parser for PEPs (unambiguous given a specific context: the first
+contiguous block of the document).  It may be desired to concretely
+specify what over/underline styles are allowed for PEP section
+headers, for uniformity.
+
+
+Rationale
+=========
+
+The lack of a standard syntax for docstrings has hampered the
+development of standard tools for extracting and converting docstrings
+into documentation in standard formats (e.g., HTML, DocBook, TeX).
+There have been a number of proposed markup formats and variations,
+and many tools tied to these proposals, but without a standard
+docstring format they have failed to gain a strong following and/or
+floundered half-finished.
+
+Throughout the existence of the Doc-SIG, consensus on a single
+standard docstring format has never been reached.  A lightweight,
+implicit markup has been sought, for the following reasons (among
+others):
+
+1. Docstrings written within Python code are available from within the
+   interactive interpreter, and can be "print"ed.  Thus the use of
+   plaintext for easy readability.
+
+2. Programmers want to add structure to their docstrings, without
+   sacrificing raw docstring readability.  Unadorned plaintext cannot
+   be transformed ("up-translated") into useful structured formats.
+
+3. Explicit markup (like XML or TeX) is widely considered unreadable
+   by the uninitiated.
+
+4. Implicit markup is aesthetically compatible with the clean and
+   minimalist Python syntax.
+
+Many alternative markups for docstrings have been proposed on the
+Doc-SIG over the years; a representative sample is listed below.  Each
+is briefly analyzed in terms of the goals stated above.  Please note
+that this is *not* intended to be an exclusive list of all existing
+markup systems; there are many other markups (Texinfo, Doxygen, TIM,
+YODL, AFT, ...) which are not mentioned.
+
+- XML_, SGML_, DocBook_, HTML_, XHTML_
+
+  XML and SGML are explicit, well-formed meta-languages suitable for
+  all kinds of documentation.  XML is a variant of SGML.  They are
+  best used behind the scenes, because to untrained eyes they are
+  verbose, difficult to type, and too cluttered to read comfortably as
+  source.  DocBook, HTML, and XHTML are all applications of SGML
+  and/or XML, and all share the same basic syntax and the same
+  shortcomings.
+
+- TeX_
+
+  TeX is similar to XML/SGML in that it's explicit, but not very easy
+  to write, and not easy for the uninitiated to read.
+
+- `Perl POD`_
+
+  Most Perl modules are documented in a format called POD (Plain Old
+  Documentation).  This is an easy-to-type, very low level format with
+  strong integration with the Perl parser.  Many tools exist to turn
+  POD documentation into other formats: info, HTML and man pages,
+  among others.  However, the POD syntax takes after Perl itself in
+  terms of readability.
+
+- JavaDoc_
+
+  Special comments before Java classes and functions serve to document
+  the code.  A program to extract these, and turn them into HTML
+  documentation is called javadoc, and is part of the standard Java
+  distribution.  However, JavaDoc has a very intimate relationship
+  with HTML, using HTML tags for most markup.  Thus it shares the
+  readability problems of HTML.
+
+- Setext_, StructuredText_
+
+  Early on, variants of Setext (Structure Enhanced Text), including
+  Zope Corp's StructuredText, were proposed for Python docstring
+  formatting.  Hereafter these variants will collectively be called
+  "STexts".  STexts have the advantage of being easy to read without
+  special knowledge, and relatively easy to write.
+
+  Although used by some (including in most existing Python
+  auto-documentation tools), until now STexts have failed to become
+  standard because:
+
+  - STexts have been incomplete.  Lacking "essential" constructs that
+    people want to use in their docstrings, STexts are rendered less
+    than ideal.  Note that these "essential" constructs are not
+    universal; everyone has their own requirements.
+
+  - STexts have been sometimes surprising.  Bits of text are
+    unexpectedly interpreted as being marked up, leading to user
+    frustration.
+
+  - SText implementations have been buggy.
+
+  - Most STexts have have had no formal specification except for the
+    implementation itself.  A buggy implementation meant a buggy spec,
+    and vice-versa.
+
+  - There has been no mechanism to get around the SText markup rules
+    when a markup character is used in a non-markup context.  In other
+    words, no way to escape markup.
+
+Proponents of implicit STexts have vigorously opposed proposals for
+explicit markup (XML, HTML, TeX, POD, etc.), and the debates have
+continued off and on since 1996 or earlier.
+
+reStructuredText is a complete revision and reinterpretation of the
+SText idea, addressing all of the problems listed above.
+
+
+Specification
+=============
+
+The specification and user documentaton for reStructuredText is
+quite extensive.  Rather than repeating or summarizing it all
+here, links to the originals are provided.
+
+Please first take a look at `A ReStructuredText Primer`_, a short and
+gentle introduction.  The `Quick reStructuredText`_ user reference
+quickly summarizes all of the markup constructs.  For complete and
+extensive details, please refer to the following documents:
+
+- `An Introduction to reStructuredText`_
+
+- `reStructuredText Markup Specification`_
+
+- `reStructuredText Directives`_
+
+In addition, `Problems With StructuredText`_ explains many markup
+decisions made with regards to StructuredText, and `A Record of
+reStructuredText Syntax Alternatives`_ records markup decisions made
+independently.
+
+
+Docstring-Significant Features
+==============================
+
+- A markup escaping mechanism.
+
+  Backslashes (``\``) are used to escape markup characters when needed
+  for non-markup purposes.  However, the inline markup recognition
+  rules have been constructed in order to minimize the need for
+  backslash-escapes.  For example, although asterisks are used for
+  *emphasis*, in non-markup contexts such as "*" or "(*)" or "x * y",
+  the asterisks are not interpreted as markup and are left unchanged.
+  For many non-markup uses of backslashes (e.g., describing regular
+  expressions), inline literals or literal blocks are applicable; see
+  the next item.
+
+- Markup to include Python source code and Python interactive
+  sessions: inline literals, literal blocks, and doctest blocks.
+
+  Inline literals use ``double-backquotes`` to indicate program I/O or
+  code snippets.  No markup interpretation (including backslash-escape
+  [``\``] interpretation) is done within inline literals.
+
+  Literal blocks (block-level literal text, such as code excerpts or
+  ASCII graphics) are indented, and indicated with a double-colon
+  ("::") at the end of the preceding paragraph (right here -->)::
+
+      if literal_block:
+          text = 'is left as-is'
+          spaces_and_linebreaks = 'are preserved'
+          markup_processing = None
+
+  Doctest blocks begin with ">>> " and end with a blank line.  Neither
+  indentation nor literal block double-colons are required.  For
+  example::
+
+      Here's a doctest block:
+
+      >>> print 'Python-specific usage examples; begun with ">>>"'
+      Python-specific usage examples; begun with ">>>"
+      >>> print '(cut and pasted from interactive sessions)'
+      (cut and pasted from interactive sessions)
+
+- Markup that isolates a Python identifier: interpreted text.
+
+  Text enclosed in single backquotes is recognized as "interpreted
+  text", whose interpretation is application-dependent.  In the
+  context of a Python docstring, the default interpretation of
+  interpreted text is as Python identifiers.  The text will be marked
+  up with a hyperlink connected to the documentation for the
+  identifier given.  Lookup rules are the same as in Python itself:
+  LGB namespace lookups (local, global, builtin).  The "role" of the
+  interpreted text (identifying a class, module, function, etc.) is
+  determined implicitly from the namespace lookup.  For example::
+
+      class Keeper(Storer):
+
+          """
+          Keep data fresher longer.
+
+          Extend `Storer`.  Class attribute `instances` keeps track
+          of the number of `Keeper` objects instantiated.
+          """
+
+          instances = 0
+          """How many `Keeper` objects are there?"""
+
+          def __init__(self):
+              """
+              Extend `Storer.__init__()` to keep track of
+              instances.  Keep count in `self.instances` and data
+              in `self.data`.
+              """
+              Storer.__init__(self)
+              self.instances += 1
+
+              self.data = []
+              """Store data in a list, most recent last."""
+
+          def storedata(self, data):
+              """
+              Extend `Storer.storedata()`; append new `data` to a
+              list (in `self.data`).
+              """
+              self.data = data
+
+  Each piece of interpreted text is looked up according to the local
+  namespace of the block containing its docstring.
+
+- Markup that isolates a Python identifier and specifies its type:
+  interpreted text with roles.
+
+  Although the Python source context reader is designed not to require
+  explicit roles, they may be used.  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 syntax chosen for roles is verbose, but necessarily so (if
+  anyone has a better alternative, please post it to the Doc-SIG_).
+  The intention of the markup is that there should be little need to
+  use explicit roles; their use is to be kept to an absolute minimum.
+
+- Markup for "tagged lists" or "label lists": field lists.
+
+  Field lists represent a mapping from field name to field body.
+  These are mostly used for extension syntax, such as "bibliographic
+  field lists" (representing document metadata such as author, date,
+  and version) and extension attributes for directives (see below).
+  They may be used to implement methodologies (docstring semantics),
+  such as identifying parameters, exceptions raised, etc.; such usage
+  is beyond the scope of this PEP.
+
+  A modified RFC 2822 syntax is used, with a colon *before* as well as
+  *after* the field name.  Field bodies are more versatile as well;
+  they may contain multiple field bodies (even nested field lists).
+  For example::
+
+      :Date: 2002-03-22
+      :Version: 1
+      :Authors:
+          - Me
+          - Myself
+          - I
+
+  Standard RFC 2822 header syntax cannot be used for this construct
+  because it is ambiguous.  A word followed by a colon at the
+  beginning of a line is common in written text.
+
+- Markup extensibility: directives and substitutions.
+
+  Directives are used as an extension mechanism for reStructuredText,
+  a way of adding support for new block-level constructs without
+  adding new syntax.  Directives for images, admonitions (note,
+  caution, etc.), and tables of contents generation (among others)
+  have been implemented.  For example, here's how to place an image::
+
+      .. image:: mylogo.png
+
+  Substitution definitions allow the power and flexibility of
+  block-level directives to be shared by inline text.  For example::
+
+      The |biohazard| symbol must be used on containers used to
+      dispose of medical waste.
+
+      .. |biohazard| image:: biohazard.png
+
+- Section structure markup.
+
+  Section headers in reStructuredText use adornment via underlines
+  (and possibly overlines) rather than indentation.  For example::
+
+      This is a Section Title
+      =======================
+
+      This is a Subsection Title
+      --------------------------
+
+      This paragraph is in the subsection.
+
+      This is Another Section Title
+      =============================
+
+      This paragraph is in the second section.
+
+
+Questions & Answers
+===================
+
+1. Is reStructuredText rich enough?
+
+   Yes, it is for most people.  If it lacks some construct that is
+   required for a specific application, it can be added via the
+   directive mechanism.  If a useful and common construct has been
+   overlooked and a suitably readable syntax can be found, it can be
+   added to the specification and parser.
+
+2. Is reStructuredText *too* rich?
+
+   For specific applications or individuals, perhaps.  In general, no.
+
+   Since the very beginning, whenever a docstring markup syntax has
+   been proposed on the Doc-SIG_, someone has complained about the
+   lack of support for some construct or other.  The reply was often
+   something like, "These are docstrings we're talking about, and
+   docstrings shouldn't have complex markup."  The problem is that a
+   construct that seems superfluous to one person may be absolutely
+   essential to another.
+
+   reStructuredText takes the opposite approach: it provides a rich
+   set of implicit markup constructs (plus a generic extension
+   mechanism for explicit markup), allowing for all kinds of
+   documents.  If the set of constructs is too rich for a particular
+   application, the unused constructs can either be removed from the
+   parser (via application-specific overrides) or simply omitted by
+   convention.
+
+3. Why not use indentation for section structure, like StructuredText
+   does?  Isn't it more "Pythonic"?
+
+   Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG post:
+
+       I still think that using indentation to indicate sectioning is
+       wrong.  If you look at how real books and other print
+       publications are laid out, you'll notice that indentation is
+       used frequently, but mostly at the intra-section level.
+       Indentation can be used to offset lists, tables, quotations,
+       examples, and the like.  (The argument that docstrings are
+       different because they are input for a text formatter is wrong:
+       the whole point is that they are also readable without
+       processing.)
+
+       I reject the argument that using indentation is Pythonic: text
+       is not code, and different traditions and conventions hold.
+       People have been presenting text for readability for over 30
+       centuries.  Let's not innovate needlessly.
+
+   See `Section Structure via Indentation`__ in `Problems With
+   StructuredText`_ for further elaboration.
+
+   __ http://docutils.sourceforge.net/docs/dev/rst/problems.html
+      #section-structure-via-indentation
+
+4. Why use reStructuredText for PEPs?  What's wrong with the existing
+   standard?
+
+   The existing standard for PEPs is very limited in terms of general
+   expressibility, and referencing is especially lacking for such a
+   reference-rich document type.  PEPs are currently converted into
+   HTML, but the results (mostly monospaced text) are less than
+   attractive, and most of the value-added potential of HTML
+   (especially inline hyperlinks) is untapped.
+
+   Making reStructuredText a standard markup for PEPs will enable much
+   richer expression, including support for section structure, inline
+   markup, graphics, and tables.  In several PEPs there are ASCII
+   graphics diagrams, which are all that plaintext documents can
+   support.  Since PEPs are made available in HTML form, the ability
+   to include proper diagrams would be immediately useful.
+
+   Current PEP practices allow for reference markers in the form "[1]"
+   in the text, and the footnotes/references themselves are listed in
+   a section toward the end of the document.  There is currently no
+   hyperlinking between the reference marker and the
+   footnote/reference itself (it would be possible to add this to
+   pep2html.py, but the "markup" as it stands is ambiguous and
+   mistakes would be inevitable).  A PEP with many references (such as
+   this one ;-) requires a lot of flipping back and forth.  When
+   revising a PEP, often new references are added or unused references
+   deleted.  It is painful to renumber the references, since it has to
+   be done in two places and can have a cascading effect (insert a
+   single new reference 1, and every other reference has to be
+   renumbered; always adding new references to the end is suboptimal).
+   It is easy for references to go out of sync.
+
+   PEPs use references for two purposes: simple URL references and
+   footnotes.  reStructuredText differentiates between the two.  A PEP
+   might contain references like this::
+
+       Abstract
+
+           This PEP proposes adding frungible doodads [1] to the core.
+           It extends PEP 9876 [2] via the BCA [3] mechanism.
+
+       ...
+
+       References and Footnotes
+
+           [1] http://www.example.org/
+
+           [2] PEP 9876, Let's Hope We Never Get Here
+               http://www.python.org/peps/pep-9876.html
+
+           [3] "Bogus Complexity Addition"
+
+   Reference 1 is a simple URL reference.  Reference 2 is a footnote
+   containing text and a URL.  Reference 3 is a footnote containing
+   text only.  Rewritten using reStructuredText, this PEP could look
+   like this::
+
+       Abstract
+       ========
+
+       This PEP proposes adding `frungible doodads`_ to the core.  It
+       extends PEP 9876 [#pep9876]_ via the BCA [#]_ mechanism.
+
+       ...
+
+       References & Footnotes
+       ======================
+
+       .. _frungible doodads: http://www.example.org/
+
+       .. [#pep9876] PEP 9876, Let's Hope We Never Get Here
+
+       .. [#] "Bogus Complexity Addition"
+
+   URLs and footnotes can be defined close to their references if
+   desired, making them easier to read in the source text, and making
+   the PEPs easier to revise.  The "References and Footnotes" section
+   can be auto-generated with a document tree transform.  Footnotes
+   from throughout the PEP would be gathered and displayed under a
+   standard header.  If URL references should likewise be written out
+   explicitly (in citation form), another tree transform could be
+   used.
+
+   URL references can be named ("frungible doodads"), and can be
+   referenced from multiple places in the document without additional
+   definitions.  When converted to HTML, references will be replaced
+   with inline hyperlinks (HTML <a> tags).  The two footnotes are
+   automatically numbered, so they will always stay in sync.  The
+   first footnote also contains an internal reference name, "pep9876",
+   so it's easier to see the connection between reference and footnote
+   in the source text.  Named footnotes can be referenced multiple
+   times, maintaining consistent numbering.
+
+   The "#pep9876" footnote could also be written in the form of a
+   citation::
+
+       It extends PEP 9876 [PEP9876]_ ...
+
+       .. [PEP9876] PEP 9876, Let's Hope We Never Get Here
+
+   Footnotes are numbered, whereas citations use text for their
+   references.
+
+5. Wouldn't it be better to keep the docstring and PEP proposals
+   separate?
+
+   The PEP markup proposal may be removed if it is deemed that there
+   is no need for PEP markup, or it could be made into a separate PEP.
+   If accepted, PEP 1, PEP Purpose and Guidelines [#PEP-1]_, and PEP
+   9, Sample PEP Template [#PEP-9]_ will be updated.
+
+   It seems natural to adopt a single consistent markup standard for
+   all uses of structured plaintext in Python, and to propose it all
+   in one place.
+
+6. The existing pep2html.py script converts the existing PEP format to
+   HTML.  How will the new-format PEPs be converted to HTML?
+
+   A new version of pep2html.py with integrated reStructuredText
+   parsing has been completed.  The Docutils project supports PEPs
+   with a "PEP Reader" component, including all functionality
+   currently in pep2html.py (auto-recognition of PEP & RFC references,
+   email masking, etc.).
+
+7. Who's going to convert the existing PEPs to reStructuredText?
+
+   PEP authors or volunteers may convert existing PEPs if they like,
+   but there is no requirement to do so.  The reStructuredText-based
+   PEPs will coexist with the old PEP standard.  The pep2html.py
+   mentioned in answer 6 processes both old and new standards.
+
+8. Why use reStructuredText for README and other ancillary files?
+
+   The reasoning given for PEPs in answer 4 above also applies to
+   README and other ancillary files.  By adopting a standard markup,
+   these files can be converted to attractive cross-referenced HTML
+   and put up on python.org.  Developers of other projects can also
+   take advantage of this facility for their own documentation.
+
+9. Won't the superficial similarity to existing markup conventions
+   cause problems, and result in people writing invalid markup (and
+   not noticing, because the plaintext looks natural)?  How forgiving
+   is reStructuredText of "not quite right" markup?
+
+   There will be some mis-steps, as there would be when moving from
+   one programming language to another.  As with any language,
+   proficiency grows with experience.  Luckily, reStructuredText is a
+   very little language indeed.
+
+   As with any syntax, there is the possibility of syntax errors.  It
+   is expected that a user will run the processing system over their
+   input and check the output for correctness.
+
+   In a strict sense, the reStructuredText parser is very unforgiving
+   (as it should be; "In the face of ambiguity, refuse the temptation
+   to guess" [#Zen]_ applies to parsing markup as well as computer
+   languages).  Here's design goal 3 from `An Introduction to
+   reStructuredText`_:
+
+       Unambiguous.  The rules for markup must not be open for
+       interpretation.  For any given input, there should be one and
+       only one possible output (including error output).
+
+   While unforgiving, at the same time the parser does try to be
+   helpful by producing useful diagnostic output ("system messages").
+   The parser reports problems, indicating their level of severity
+   (from least to most: debug, info, warning, error, severe).  The
+   user or the client software can decide on reporting thresholds;
+   they can ignore low-level problems or cause high-level problems to
+   bring processing to an immediate halt.  Problems are reported
+   during the parse as well as included in the output, often with
+   two-way links between the source of the problem and the system
+   message explaining it.
+
+10. Will the docstrings in the Python standard library modules be
+    converted to reStructuredText?
+
+    No.  Python's library reference documentation is maintained
+    separately from the source.  Docstrings in the Python standard
+    library should not try to duplicate the library reference
+    documentation.  The current policy for docstrings in the Python
+    standard library is that they should be no more than concise
+    hints, simple and markup-free (although many *do* contain ad-hoc
+    implicit markup).
+
+11. I want to write all my strings in Unicode.  Will anything
+    break?
+
+    The parser fully supports Unicode.  Docutils supports arbitrary
+    input and output encodings.
+
+12. Why does the community need a new structured text design?
+
+    The existing structured text designs are deficient, for the
+    reasons given in "Rationale" above.  reStructuredText aims to be a
+    complete markup syntax, within the limitations of the "readable
+    plaintext" medium.
+
+13. What is wrong with existing documentation methodologies?
+
+    What existing methodologies?  For Python docstrings, there is
+    **no** official standard markup format, let alone a documentation
+    methodology akin to JavaDoc.  The question of methodology is at a
+    much higher level than syntax (which this PEP addresses).  It is
+    potentially much more controversial and difficult to resolve, and
+    is intentionally left out of this discussion.
+
+
+References & Footnotes
+======================
+
+.. [#PEP-1] PEP 1, PEP Guidelines, Warsaw, Hylton
+   (http://www.python.org/peps/pep-0001.html)
+
+.. [#PEP-9] PEP 9, Sample PEP Template, Warsaw
+   (http://www.python.org/peps/pep-0009.html)
+
+.. [#Zen] From `The Zen of Python (by Tim Peters)`__ (or just
+   "``import this``" in Python)
+
+__ http://www.python.org/doc/Humor.html#zen
+
+.. [#PEP-216] PEP 216, Docstring Format, Zadka
+   (http://www.python.org/peps/pep-0216.html)
+
+.. _reStructuredText markup: http://docutils.sourceforge.net/rst.html
+
+.. _Doc-SIG: http://www.python.org/sigs/doc-sig/
+
+.. _XML: http://www.w3.org/XML/
+
+.. _SGML: http://www.oasis-open.org/cover/general.html
+
+.. _DocBook: http://docbook.org/tdg/en/html/docbook.html
+
+.. _HTML: http://www.w3.org/MarkUp/
+
+.. _XHTML: http://www.w3.org/MarkUp/#xhtml1
+
+.. _TeX: http://www.tug.org/interest.html
+
+.. _Perl POD: http://perldoc.perl.org/perlpod.html
+
+.. _JavaDoc: http://java.sun.com/j2se/javadoc/
+
+.. _Setext: http://docutils.sourceforge.net/mirror/setext.html
+
+.. _StructuredText:
+   http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage
+
+.. _A ReStructuredText Primer:
+   http://docutils.sourceforge.net/docs/user/rst/quickstart.html
+
+.. _Quick reStructuredText:
+   http://docutils.sourceforge.net/docs/user/rst/quickref.html
+
+.. _An Introduction to reStructuredText:
+   http://docutils.sourceforge.net/docs/ref/rst/introduction.html
+
+.. _reStructuredText Markup Specification:
+   http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
+
+.. _reStructuredText Directives:
+   http://docutils.sourceforge.net/docs/ref/rst/directives.html
+
+.. _Problems with StructuredText:
+   http://docutils.sourceforge.net/docs/dev/rst/problems.html
+
+.. _A Record of reStructuredText Syntax Alternatives:
+   http://docutils.sourceforge.net/docs/dev/rst/alternatives.html
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+
+Copyright
+=========
+
+This document has been placed in the public domain.
+
+
+Acknowledgements
+================
+
+Some text is borrowed from PEP 216, Docstring Format [#PEP-216]_, by
+Moshe Zadka.
+
+Special thanks to all members past & present of the Python Doc-SIG_.
+
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

docs/ref/docutils.dtd

@@ -0,0 +1,632 @@
+<!--
+======================================================================
+    Docutils Generic DTD
+======================================================================
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 8031 $
+:Date: $Date: 2017-02-13 10:36:13 +0100 (Mo, 13 Feb 2017) $
+:Copyright: This DTD has been placed in the public domain.
+:Filename: docutils.dtd
+
+More information about this DTD (document type definition) 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/ref/docutils.dtd.
+
+The formal public identifier for this DTD is::
+
+    +//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML
+-->
+
+<!--
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Parameter Entities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Parameter entities are used to simplify the DTD (reduce duplication)
+and to allow the DTD to be customized by wrapper DTDs.  Parameter
+entities beginning with "additional" are meant to allow easy extension
+by wrapper DTDs.
+-->
+
+<!-- Attributes
+================================================================== -->
+
+<!-- Boolean: no if zero(s), yes if any other value. -->
+<!ENTITY % yesorno "NMTOKEN">
+
+<!-- Emphasize that the attribute value must be a number. -->
+<!ENTITY % number  "NMTOKEN">
+
+<!-- A number which may be immediately followed by a unit or percent sign. -->
+<!ENTITY % measure "CDATA">
+
+<!ENTITY % additional.basic.atts "">
+
+<!--
+Attributes shared by all elements in this DTD:
+
+- `ids` are unique identifiers, typically assigned by the system. The NMTOKENS
+  attribute type is used because XML doesn't support a multiple-ID "IDS" type.
+- `names` are identifiers assigned in the markup.
+- `dupnames` is the same as `name`, used when it's a duplicate.
+- `source` is the name of the source of this document or fragment.
+- `classes` is used to transmit individuality information forward.
+-->
+<!ENTITY % basic.atts
+  " ids       NMTOKENS  #IMPLIED
+    names     CDATA     #IMPLIED
+    dupnames  CDATA     #IMPLIED
+    source    CDATA     #IMPLIED
+    classes   NMTOKENS  #IMPLIED
+    %additional.basic.atts; ">
+
+<!-- External reference to a URI/URL. -->
+<!ENTITY % refuri.att
+  " refuri    CDATA     #IMPLIED ">
+
+<!--
+Internal reference to the `ids` attribute of an element. The NMTOKENS
+type is used instead of IDREF, because XML doesn't support a multiple-ID
+"IDS" type.
+-->
+<!ENTITY % refid.att
+  " refid     NMTOKEN     #IMPLIED ">
+
+<!--
+Space-separated list of `ids` references, for backlinks. The NMTOKENS
+type is used instead of IDREF, because XML doesn't support a multiple-ID
+"IDS" type.
+-->
+<!ENTITY % backrefs.att
+  " backrefs  NMTOKENS    #IMPLIED ">
+
+<!--
+Internal reference to the `name` attribute of an element. On a
+'target' element, 'refname' indicates an indirect target which may
+resolve to either an internal or external reference.
+-->
+<!ENTITY % refname.att
+  " refname   NMTOKENS  #IMPLIED ">
+
+<!ENTITY % additional.reference.atts "">
+<!-- Collected hyperlink reference attributes. -->
+<!ENTITY % reference.atts
+  " %refuri.att;
+    %refid.att;
+    %refname.att;
+    %additional.reference.atts; ">
+
+<!-- Unnamed hyperlink. -->
+<!ENTITY % anonymous.att
+  " anonymous %yesorno; #IMPLIED ">
+
+<!-- Auto-numbered footnote or title. -->
+<!ENTITY % auto.att
+  " auto      CDATA     #IMPLIED ">
+
+<!-- XML standard attribute for whitespace-preserving elements. -->
+<!ENTITY % fixedspace.att
+  " xml:space (default | preserve) #FIXED 'preserve' ">
+
+<!ENTITY % align-h.att
+  " align     (left | center | right) #IMPLIED ">
+
+<!ENTITY % align-hv.att
+  " align     (top | middle | bottom | left | center | right) #IMPLIED ">
+
+
+<!-- Element OR-Lists
+============================================================= -->
+
+<!ENTITY % additional.bibliographic.elements "">
+<!ENTITY % bibliographic.elements
+  " author | authors | organization | address | contact
+    | version | revision | status | date | copyright
+    | field
+    %additional.bibliographic.elements; ">
+
+<!ENTITY % additional.section.elements "">
+<!ENTITY % section.elements
+  " section
+    %additional.section.elements; ">
+
+<!ENTITY % additional.body.elements "">
+<!ENTITY % body.elements
+  " paragraph | compound | container | literal_block | doctest_block
+    | math_block | line_block | block_quote
+    | table | figure | image | footnote | citation | rubric
+    | bullet_list | enumerated_list | definition_list | field_list
+    | option_list
+    | attention | caution | danger | error | hint | important | note
+    | tip | warning | admonition
+    | reference | target | substitution_definition | comment | pending
+    | system_message | raw
+    %additional.body.elements; ">
+
+<!ENTITY % additional.inline.elements "">
+<!ENTITY % inline.elements
+  " emphasis | strong | literal | math
+    | reference | footnote_reference | citation_reference
+    | substitution_reference | title_reference
+    | abbreviation | acronym | subscript | superscript
+    | inline | problematic | generated
+    | target | image | raw
+    %additional.inline.elements; ">
+
+
+<!-- Element Content Models
+================================================================== -->
+
+<!-- The structure model may not end with a transition. -->
+<!ENTITY % structure.model
+   " ( ( (%body.elements; | topic | sidebar)+, transition? )*,
+       ( (%section.elements;), (transition?, (%section.elements;) )* )? )">
+
+<!ENTITY % text.model
+  " (#PCDATA | %inline.elements;)* ">
+
+
+<!-- Table Model
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This DTD uses the Exchange subset of the CALS-table model (OASIS
+Technical Memorandum 9901:1999 "XML Exchange Table Model DTD",
+http://www.oasis-open.org/html/tm9901.htm).
+-->
+
+<!ENTITY % calstblx PUBLIC
+    "-//OASIS//DTD XML Exchange Table Model 19990315//EN"
+    "soextblx.dtd">
+
+<!-- These parameter entities customize the table model DTD. -->
+<!ENTITY % bodyatt              " %basic.atts; ">  <!-- table elt -->
+<!-- 1 colspec element is expected per table column: -->
+<!ENTITY % tbl.tgroup.mdl      "colspec+,thead?,tbody">
+<!ENTITY % tbl.tgroup.att       " %basic.atts; ">
+<!ENTITY % tbl.thead.att        " %basic.atts; ">
+<!ENTITY % tbl.tbody.att        " %basic.atts; ">
+<!ENTITY % tbl.colspec.att
+  " %basic.atts;
+    stub      %yesorno; #IMPLIED ">
+<!ENTITY % tbl.row.att          " %basic.atts; ">
+<!-- ``(...)*``: nested tables are supported -->
+<!ENTITY % tbl.entry.mdl        " (%body.elements;)* ">
+<!ENTITY % tbl.entry.att
+  " %basic.atts;
+    morecols  %number;  #IMPLIED ">
+<!ATTLIST table
+    %align-h.att;>
+
+<!--
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Root Element
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-->
+
+<!-- Optional elements may be generated by internal processing. -->
+<!ELEMENT document
+    ( (title, subtitle?)?,
+      decoration?,
+      (docinfo, transition?)?,
+      %structure.model; )>
+<!ATTLIST document
+    %basic.atts;
+    title     CDATA     #IMPLIED>
+
+<!--
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Title Elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-->
+
+<!ELEMENT title %text.model;>
+<!ATTLIST title
+    %basic.atts;
+    %refid.att;
+    %auto.att;>
+
+<!ELEMENT subtitle %text.model;>
+<!ATTLIST subtitle %basic.atts;>
+
+<!--
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Bibliographic Elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-->
+
+<!-- Container for bibliographic elements. May not be empty. -->
+<!ELEMENT docinfo (%bibliographic.elements;)+>
+<!ATTLIST docinfo %basic.atts;>
+
+<!-- Container for bibliographic elements. May not be empty.
+Eventual replacement for docinfo? -->
+<!ELEMENT info (%bibliographic.elements;)+>
+<!ATTLIST info %basic.atts;>
+
+<!ELEMENT author %text.model;>
+<!ATTLIST author %basic.atts;>
+
+<!ELEMENT authors (author, organization?, address?, contact?)+>
+<!ATTLIST authors %basic.atts;>
+
+<!ELEMENT organization %text.model;>
+<!ATTLIST organization %basic.atts;>
+
+<!ELEMENT address %text.model;>
+<!ATTLIST address
+    %basic.atts;
+    %fixedspace.att;>
+
+<!ELEMENT contact %text.model;>
+<!ATTLIST contact %basic.atts;>
+
+<!ELEMENT version %text.model;>
+<!ATTLIST version %basic.atts;>
+
+<!ELEMENT revision %text.model;>
+<!ATTLIST revision %basic.atts;>
+
+<!ELEMENT status %text.model;>
+<!ATTLIST status %basic.atts;>
+
+<!ELEMENT date %text.model;>
+<!ATTLIST date %basic.atts;>
+
+<!ELEMENT copyright %text.model;>
+<!ATTLIST copyright %basic.atts;>
+
+<!--
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Decoration Elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-->
+
+<!ELEMENT decoration (header?, footer?)>
+<!ATTLIST decoration %basic.atts;>
+
+<!ELEMENT header (%body.elements;)+>
+<!ATTLIST header %basic.atts;>
+
+<!ELEMENT footer (%body.elements;)+>
+<!ATTLIST footer %basic.atts;>
+
+<!--
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Structural Elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-->
+
+<!ELEMENT section
+    (title, subtitle?, info?, decoration?, %structure.model;)>
+<!ATTLIST section %basic.atts;>
+
+<!ELEMENT topic (title?, (%body.elements;)+)>
+<!ATTLIST topic %basic.atts;>
+
+<!ELEMENT sidebar (title, subtitle?, (%body.elements; | topic)+)>
+<!ATTLIST sidebar %basic.atts;>
+
+<!ELEMENT transition EMPTY>
+<!ATTLIST transition %basic.atts;>
+
+<!--
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Body Elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-->
+
+<!ELEMENT paragraph %text.model;>
+<!ATTLIST paragraph %basic.atts;>
+
+<!ELEMENT compound (%body.elements;)+>
+<!ATTLIST compound %basic.atts;>
+
+<!ELEMENT container (%body.elements;)+>
+<!ATTLIST container %basic.atts;>
+
+<!ELEMENT bullet_list (list_item+)>
+<!ATTLIST bullet_list
+    %basic.atts;
+    bullet    CDATA     #IMPLIED>
+
+<!ELEMENT enumerated_list (list_item+)>
+<!ATTLIST enumerated_list
+    %basic.atts;
+    enumtype  (arabic | loweralpha | upperalpha
+                      | lowerroman | upperroman)
+                        #IMPLIED
+    prefix    CDATA     #IMPLIED
+    suffix    CDATA     #IMPLIED
+    start     %number;  #IMPLIED>
+
+<!ELEMENT list_item (%body.elements;)*>
+<!ATTLIST list_item %basic.atts;>
+
+<!ELEMENT definition_list (definition_list_item+)>
+<!ATTLIST definition_list %basic.atts;>
+
+<!ELEMENT definition_list_item (term, classifier*, definition)>
+<!ATTLIST definition_list_item %basic.atts;>
+
+<!ELEMENT term %text.model;>
+<!ATTLIST term %basic.atts;>
+
+<!ELEMENT classifier %text.model;>
+<!ATTLIST classifier %basic.atts;>
+
+<!ELEMENT definition (%body.elements;)+>
+<!ATTLIST definition %basic.atts;>
+
+<!ELEMENT field_list (field+)>
+<!ATTLIST field_list %basic.atts;>
+
+<!ELEMENT field (field_name, field_body)>
+<!ATTLIST field %basic.atts;>
+
+<!ELEMENT field_name %text.model;>
+<!ATTLIST field_name %basic.atts;>
+
+<!-- May be empty. -->
+<!ELEMENT field_body (%body.elements;)*>
+<!ATTLIST field_body %basic.atts;>
+
+<!ELEMENT option_list (option_list_item+)>
+<!ATTLIST option_list %basic.atts;>
+
+<!ELEMENT option_list_item (option_group, description)>
+<!ATTLIST option_list_item %basic.atts;>
+
+<!ELEMENT option_group (option+)>
+<!ATTLIST option_group %basic.atts;>
+
+<!ELEMENT option (option_string, option_argument*)>
+<!ATTLIST option %basic.atts;>
+
+<!ELEMENT option_string (#PCDATA)>
+<!ATTLIST option_string %basic.atts;>
+
+<!--
+`delimiter` contains the text preceding the `option_argument`: either
+the text separating it from the `option_string` (typically either "="
+or " ") or the text between option arguments (typically either "," or
+" ").
+-->
+<!ELEMENT option_argument (#PCDATA)>
+<!ATTLIST option_argument
+    %basic.atts;
+    delimiter  CDATA    #IMPLIED>
+
+<!ELEMENT description (%body.elements;)+>
+<!ATTLIST description %basic.atts;>
+
+<!ELEMENT literal_block %text.model;>
+<!ATTLIST literal_block
+    %basic.atts;
+    %fixedspace.att;>
+
+<!--
+`math_block` contains a block of text in "LaTeX math format"
+that is typeset as mathematical notation (display formula).
+-->
+<!ELEMENT math_block (#PCDATA)>
+<!ATTLIST math_block %basic.atts;>
+
+<!ELEMENT line_block (line | line_block)+>
+<!ATTLIST line_block %basic.atts;>
+
+<!ELEMENT line %text.model;>
+<!ATTLIST line %basic.atts;>
+
+<!ELEMENT block_quote ((%body.elements;)+, attribution?)>
+<!ATTLIST block_quote %basic.atts;>
+
+<!ELEMENT attribution %text.model;>
+<!ATTLIST attribution %basic.atts;>
+
+<!ELEMENT doctest_block %text.model;>
+<!ATTLIST doctest_block
+    %basic.atts;
+    %fixedspace.att;>
+
+<!ELEMENT attention (%body.elements;)+>
+<!ATTLIST attention %basic.atts;>
+
+<!ELEMENT caution (%body.elements;)+>
+<!ATTLIST caution %basic.atts;>
+
+<!ELEMENT danger (%body.elements;)+>
+<!ATTLIST danger %basic.atts;>
+
+<!ELEMENT error (%body.elements;)+>
+<!ATTLIST error %basic.atts;>
+
+<!ELEMENT hint (%body.elements;)+>
+<!ATTLIST hint %basic.atts;>
+
+<!ELEMENT important (%body.elements;)+>
+<!ATTLIST important %basic.atts;>
+
+<!ELEMENT note (%body.elements;)+>
+<!ATTLIST note %basic.atts;>
+
+<!ELEMENT tip (%body.elements;)+>
+<!ATTLIST tip %basic.atts;>
+
+<!ELEMENT warning (%body.elements;)+>
+<!ATTLIST warning %basic.atts;>
+
+<!ELEMENT admonition (title, (%body.elements;)+)>
+<!ATTLIST admonition %basic.atts;>
+
+<!ELEMENT footnote (label?, (%body.elements;)+)>
+<!ATTLIST footnote
+    %basic.atts;
+    %backrefs.att;
+    %auto.att;>
+
+<!ELEMENT citation (label, (%body.elements;)+)>
+<!ATTLIST citation
+    %basic.atts;
+    %backrefs.att;>
+
+<!ELEMENT label (#PCDATA)>
+<!ATTLIST label %basic.atts;>
+
+<!ELEMENT rubric %text.model;>
+<!ATTLIST rubric %basic.atts;>
+
+<!-- Empty except when used as an inline element. -->
+<!ELEMENT target %text.model;>
+<!ATTLIST target
+    %basic.atts;
+    %reference.atts;
+    %anonymous.att;>
+
+<!ELEMENT substitution_definition %text.model;>
+<!ATTLIST substitution_definition
+    %basic.atts;
+    ltrim     %yesorno; #IMPLIED
+    rtrim     %yesorno; #IMPLIED>
+
+<!ELEMENT comment (#PCDATA)>
+<!ATTLIST comment
+    %basic.atts;
+    %fixedspace.att;>
+
+<!ELEMENT pending EMPTY>
+<!ATTLIST pending %basic.atts;>
+
+<!ELEMENT figure (image, ((caption, legend?) | legend)) >
+<!ATTLIST figure
+    %basic.atts;
+    %align-h.att;
+    width     %measure;  #IMPLIED>
+
+<!-- Also an inline element. -->
+<!ELEMENT image EMPTY>
+<!ATTLIST image
+    %basic.atts;
+    %align-hv.att;
+    uri       CDATA     #REQUIRED
+    alt       CDATA     #IMPLIED
+    height    %measure; #IMPLIED
+    width     %measure; #IMPLIED
+    scale     %number;  #IMPLIED>
+
+<!ELEMENT caption %text.model;>
+<!ATTLIST caption %basic.atts;>
+
+<!ELEMENT legend (%body.elements;)+>
+<!ATTLIST legend %basic.atts;>
+
+<!--
+Table elements: table, tgroup, colspec, thead, tbody, row, entry.
+-->
+%calstblx;
+
+<!-- Used to record processing information. -->
+<!ELEMENT system_message (%body.elements;)+>
+<!ATTLIST system_message
+    %basic.atts;
+    %backrefs.att;
+    level     %number;  #IMPLIED
+    line      %number;  #IMPLIED
+    type      NMTOKEN   #IMPLIED>
+
+<!-- Used to pass raw data through the system. Also inline. -->
+<!ELEMENT raw %text.model;>
+<!ATTLIST raw
+    %basic.atts;
+    %fixedspace.att;
+    format    NMTOKENS  #IMPLIED>
+
+<!--
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Inline Elements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Inline elements occur within the text contents of body elements. Some
+nesting of inline elements is allowed by these definitions, with the
+following caveats:
+
+- An inline element may not contain a nested element of the same type
+  (e.g. <strong> may not contain another <strong>).
+- Nested inline elements may or may not be supported by individual
+  applications using this DTD.
+- The inline elements <footnote_reference>, <citation_reference>,
+  <math>, and <image> do not support nesting.
+-->
+
+<!ELEMENT emphasis %text.model;>
+<!ATTLIST emphasis %basic.atts;>
+
+<!ELEMENT strong %text.model;>
+<!ATTLIST strong %basic.atts;>
+
+<!ELEMENT literal %text.model;>
+<!ATTLIST literal %basic.atts;>
+
+<!ELEMENT math (#PCDATA)>
+<!ATTLIST math %basic.atts;>
+
+<!-- Can also be a body element, when it contains an "image" element. -->
+<!ELEMENT reference %text.model;>
+<!ATTLIST reference
+    name      CDATA     #IMPLIED
+    %basic.atts;
+    %reference.atts;
+    %anonymous.att;>
+
+<!ELEMENT footnote_reference (#PCDATA)>
+<!ATTLIST footnote_reference
+    %basic.atts;
+    %refid.att;
+    %refname.att;
+    %auto.att;>
+
+<!ELEMENT citation_reference (#PCDATA)>
+<!ATTLIST citation_reference
+    %basic.atts;
+    %refid.att;
+    %refname.att;>
+
+<!ELEMENT substitution_reference %text.model;>
+<!ATTLIST substitution_reference
+    %basic.atts;
+    %refname.att;>
+
+<!ELEMENT title_reference %text.model;>
+<!ATTLIST title_reference %basic.atts;>
+
+<!ELEMENT abbreviation %text.model;>
+<!ATTLIST abbreviation %basic.atts;>
+
+<!ELEMENT acronym %text.model;>
+<!ATTLIST acronym %basic.atts;>
+
+<!ELEMENT superscript %text.model;>
+<!ATTLIST superscript %basic.atts;>
+
+<!ELEMENT subscript %text.model;>
+<!ATTLIST subscript %basic.atts;>
+
+<!ELEMENT inline %text.model;>
+<!ATTLIST inline %basic.atts;>
+
+<!ELEMENT problematic %text.model;>
+<!ATTLIST problematic
+    %basic.atts;
+    %refid.att;>
+
+<!ELEMENT generated %text.model;>
+<!ATTLIST generated %basic.atts;>
+
+<!--
+Local Variables:
+mode: sgml
+indent-tabs-mode: nil
+fill-column: 70
+End:
+-->

docs/ref/rst/definitions.txt

@@ -0,0 +1,180 @@
+============================================
+ reStructuredText Standard Definition Files
+============================================
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 7302 $
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+
+This document describes standard definition files, such as sets of
+substitution definitions and interpreted text roles, that can be
+included in reStructuredText documents.  The `"include" directive`__
+has a special syntax for these standard definition files, angle
+brackets around the file name::
+
+    .. include:: <filename.txt>
+
+__ directives.html#include
+
+The individual data files are stored with the Docutils source code in
+the "docutils" package, in the ``docutils/parsers/rst/include``
+directory.
+
+
+Substitution Definitions
+========================
+
+Many of the standard definition files contain sets of `substitution
+definitions`__, which can be used in documents via `substitution
+references`__.  For example, the copyright symbol is defined in
+``isonum.txt`` as "copy"::
+
+    .. include:: <isonum.txt>
+
+    Copyright |copy| 2003 by John Q. Public, all rights reserved.
+
+__ restructuredtext.html#substitution-definitions
+__ restructuredtext.html#substitution-references
+
+Individual substitution definitions can also be copied from definition
+files and pasted into documents.  This has two advantages: it removes
+dependencies, and it saves processing of unused definitions.  However,
+multiple substitution definitions add clutter to the document.
+
+Substitution references require separation from the surrounding text
+with whitespace or punctuation.  To use a substitution without
+intervening whitespace, you can use the disappearing-whitespace escape
+sequence, backslash-space::
+
+    .. include:: isonum.txt
+
+    Copyright |copy| 2003, BogusMegaCorp\ |trade|.
+
+Custom substitution definitions may use the `"unicode" directive`__.
+Whitespace is ignored and removed, effectively sqeezing together the
+text::
+
+    .. |copy|   unicode:: U+000A9 .. COPYRIGHT SIGN
+    .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
+       .. with trademark sign
+
+    Copyright |copy| 2003, |BogusMegaCorp (TM)|.
+
+__ directives.html#unicode
+
+In addition, the "ltrim", "rtrim", and "trim" options may be used with
+the "unicode" directive to automatically trim spaces from the left,
+right, or both sides (respectively) of substitution references::
+
+    .. |---| unicode:: U+02014 .. em dash
+       :trim:
+
+
+Character Entity Sets
+---------------------
+
+The following files contain substitution definitions corresponding to
+XML character entity sets, from the following standards: ISO 8879 &
+ISO 9573-13 (combined), MathML, and XHTML1.  They were generated by
+the ``tools/dev/unicode2rstsubs.py`` program from the input file
+unicode.xml__, which is maintained as part of the MathML 2
+Recommentation XML source.
+
+__ http://www.w3.org/2003/entities/xml/
+
+===================  =================================================
+Entity Set File      Description
+===================  =================================================
+isoamsa.txt_         Added Mathematical Symbols: Arrows
+isoamsb.txt_         Added Mathematical Symbols: Binary Operators
+isoamsc.txt_         Added Mathematical Symbols: Delimiters
+isoamsn.txt_         Added Mathematical Symbols: Negated Relations
+isoamso.txt_         Added Mathematical Symbols: Ordinary
+isoamsr.txt_         Added Mathematical Symbols: Relations
+isobox.txt_          Box and Line Drawing
+isocyr1.txt_         Russian Cyrillic
+isocyr2.txt_         Non-Russian Cyrillic
+isodia.txt_          Diacritical Marks
+isogrk1.txt_         Greek Letters
+isogrk2.txt_         Monotoniko Greek
+isogrk3.txt_         Greek Symbols
+isogrk4.txt_  [1]_   Alternative Greek Symbols
+isolat1.txt_         Added Latin 1
+isolat2.txt_         Added Latin 2
+isomfrk.txt_  [1]_   Mathematical Fraktur
+isomopf.txt_  [1]_   Mathematical Openface (Double-struck)
+isomscr.txt_  [1]_   Mathematical Script
+isonum.txt_          Numeric and Special Graphic
+isopub.txt_          Publishing
+isotech.txt_         General Technical
+mmlalias.txt_        MathML aliases for entities from other sets
+mmlextra.txt_ [1]_   Extra names added by MathML
+xhtml1-lat1.txt_     XHTML Latin 1
+xhtml1-special.txt_  XHTML Special Characters
+xhtml1-symbol.txt_   XHTML Mathematical, Greek and Symbolic Characters
+===================  =================================================
+
+.. [1] There are ``*-wide.txt`` variants for each of these character
+   entity set files, containing characters outside of the Unicode
+   basic multilingual plane or BMP (wide-Unicode; code points greater
+   than U+FFFF).  Most pre-built Python distributions are "narrow" and
+   do not support wide-Unicode characters.  Python *can* be built with
+   wide-Unicode support though; consult the Python build instructions
+   for details.
+
+For example, the copyright symbol is defined as the XML character
+entity ``&copy;``.  The equivalent reStructuredText substitution
+reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is
+``|copy|``.
+
+.. _isoamsa.txt:        ../../../docutils/parsers/rst/include/isoamsa.txt
+.. _isoamsb.txt:        ../../../docutils/parsers/rst/include/isoamsb.txt
+.. _isoamsc.txt:        ../../../docutils/parsers/rst/include/isoamsc.txt
+.. _isoamsn.txt:        ../../../docutils/parsers/rst/include/isoamsn.txt
+.. _isoamso.txt:        ../../../docutils/parsers/rst/include/isoamso.txt
+.. _isoamsr.txt:        ../../../docutils/parsers/rst/include/isoamsr.txt
+.. _isobox.txt:         ../../../docutils/parsers/rst/include/isobox.txt
+.. _isocyr1.txt:        ../../../docutils/parsers/rst/include/isocyr1.txt
+.. _isocyr2.txt:        ../../../docutils/parsers/rst/include/isocyr2.txt
+.. _isodia.txt:         ../../../docutils/parsers/rst/include/isodia.txt
+.. _isogrk1.txt:        ../../../docutils/parsers/rst/include/isogrk1.txt
+.. _isogrk2.txt:        ../../../docutils/parsers/rst/include/isogrk2.txt
+.. _isogrk3.txt:        ../../../docutils/parsers/rst/include/isogrk3.txt
+.. _isogrk4.txt:        ../../../docutils/parsers/rst/include/isogrk4.txt
+.. _isolat1.txt:        ../../../docutils/parsers/rst/include/isolat1.txt
+.. _isolat2.txt:        ../../../docutils/parsers/rst/include/isolat2.txt
+.. _isomfrk.txt:        ../../../docutils/parsers/rst/include/isomfrk.txt
+.. _isomopf.txt:        ../../../docutils/parsers/rst/include/isomopf.txt
+.. _isomscr.txt:        ../../../docutils/parsers/rst/include/isomscr.txt
+.. _isonum.txt:         ../../../docutils/parsers/rst/include/isonum.txt
+.. _isopub.txt:         ../../../docutils/parsers/rst/include/isopub.txt
+.. _isotech.txt:        ../../../docutils/parsers/rst/include/isotech.txt
+.. _mmlalias.txt:       ../../../docutils/parsers/rst/include/mmlalias.txt
+.. _mmlextra.txt:       ../../../docutils/parsers/rst/include/mmlextra.txt
+.. _xhtml1-lat1.txt:    ../../../docutils/parsers/rst/include/xhtml1-lat1.txt
+.. _xhtml1-special.txt: ../../../docutils/parsers/rst/include/xhtml1-special.txt
+.. _xhtml1-symbol.txt:  ../../../docutils/parsers/rst/include/xhtml1-symbol.txt
+
+
+S5/HTML Definitions
+===================
+
+The "s5defs.txt_" standard definition file contains interpreted text
+roles (classes) and other definitions for documents destined to become
+`S5/HTML slide shows`_.  
+
+.. _s5defs.txt: ../../../docutils/parsers/rst/include/s5defs.txt
+.. _S5/HTML slide shows: ../../user/slide-shows.html
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

docs/ref/rst/introduction.txt

@@ -0,0 +1,314 @@
+=====================================
+ An Introduction to reStructuredText
+=====================================
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 7302 $
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:Copyright: This document has been placed in the public domain.
+
+reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get
+plaintext markup syntax and parser system.  It is useful for inline
+program documentation (such as Python docstrings), for quickly
+creating simple web pages, and for standalone documents.
+reStructuredText_ is a proposed revision and reinterpretation of the
+StructuredText_ and Setext_ lightweight markup systems.
+
+reStructuredText is designed for extensibility for specific
+application domains.  Its parser is a component of Docutils_.
+
+This document defines the goals_ of reStructuredText and provides a
+history_ of the project.  It is written using the reStructuredText
+markup, and therefore serves as an example of its use.  For a gentle
+introduction to using reStructuredText, please read `A
+ReStructuredText Primer`_.  The `Quick reStructuredText`_ user
+reference is also useful.  The `reStructuredText Markup
+Specification`_ is the definitive reference.  There is also an
+analysis of the `Problems With StructuredText`_.
+
+ReStructuredText's web page is
+http://docutils.sourceforge.net/rst.html.
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _StructuredText:
+    http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage
+.. _Setext: http://docutils.sourceforge.net/mirror/setext.html
+.. _Docutils: http://docutils.sourceforge.net/
+.. _A ReStructuredText Primer: ../../user/rst/quickstart.html
+.. _Quick reStructuredText: ../../user/rst/quickref.html
+.. _reStructuredText Markup Specification: restructuredtext.html
+.. _Problems with StructuredText: ../../dev/rst/problems.html
+
+
+Goals
+=====
+
+The primary goal of reStructuredText_ is to define a markup syntax for
+use in Python docstrings and other documentation domains, that is
+readable and simple, yet powerful enough for non-trivial use.  The
+intended purpose of the reStructuredText markup is twofold:
+
+- the establishment of a set of standard conventions allowing the
+  expression of structure within plaintext, and
+
+- the conversion of such documents into useful structured data
+  formats.
+
+The secondary goal of reStructuredText is to be accepted by the Python
+community (by way of being blessed by PythonLabs and the BDFL [#]_) as
+a standard for Python inline documentation (possibly one of several
+standards, to account for taste).
+
+.. [#] Python's creator and "Benevolent Dictator For Life",
+   Guido van Rossum.
+
+To clarify the primary goal, here are specific design goals, in order,
+beginning with the most important:
+
+1. Readable.  The marked-up text must be easy to read without any
+   prior knowledge of the markup language.  It should be as easily
+   read in raw form as in processed form.
+
+2. Unobtrusive.  The markup that is used should be as simple and
+   unobtrusive as possible.  The simplicity of markup constructs
+   should be roughly proportional to their frequency of use.  The most
+   common constructs, with natural and obvious markup, should be the
+   simplest and most unobtrusive.  Less common constructs, for which
+   there is no natural or obvious markup, should be distinctive.
+
+3. Unambiguous.  The rules for markup must not be open for
+   interpretation.  For any given input, there should be one and only
+   one possible output (including error output).
+
+4. Unsurprising.  Markup constructs should not cause unexpected output
+   upon processing.  As a fallback, there must be a way to prevent
+   unwanted markup processing when a markup construct is used in a
+   non-markup context (for example, when documenting the markup syntax
+   itself).
+
+5. Intuitive.  Markup should be as obvious and easily remembered as
+   possible, for the author as well as for the reader.  Constructs
+   should take their cues from such naturally occurring sources as
+   plaintext email messages, newsgroup postings, and text
+   documentation such as README.txt files.
+
+6. Easy.  It should be easy to mark up text using any ordinary text
+   editor.
+
+7. Scalable.  The markup should be applicable regardless of the length
+   of the text.
+
+8. Powerful.  The markup should provide enough constructs to produce a
+   reasonably rich structured document.
+
+9. Language-neutral.  The markup should apply to multiple natural (as
+   well as artificial) languages, not only English.
+
+10. Extensible.  The markup should provide a simple syntax and
+    interface for adding more complex general markup, and custom
+    markup.
+
+11. Output-format-neutral.  The markup will be appropriate for
+    processing to multiple output formats, and will not be biased
+    toward any particular format.
+
+The design goals above were used as criteria for accepting or
+rejecting syntax, or selecting between alternatives.
+
+It is emphatically *not* the goal of reStructuredText to define
+docstring semantics, such as docstring contents or docstring length.
+These issues are orthogonal to the markup syntax and beyond the scope
+of this specification.
+
+Also, it is not the goal of reStructuredText to maintain compatibility
+with StructuredText_ or Setext_.  reStructuredText shamelessly steals
+their great ideas and ignores the not-so-great.
+
+Author's note:
+
+    Due to the nature of the problem we're trying to solve (or,
+    perhaps, due to the nature of the proposed solution), the above
+    goals unavoidably conflict.  I have tried to extract and distill
+    the wisdom accumulated over the years in the Python Doc-SIG_
+    mailing list and elsewhere, to come up with a coherent and
+    consistent set of syntax rules, and the above goals by which to
+    measure them.
+
+    There will inevitably be people who disagree with my particular
+    choices.  Some desire finer control over their markup, others
+    prefer less.  Some are concerned with very short docstrings,
+    others with full-length documents.  This specification is an
+    effort to provide a reasonably rich set of markup constructs in a
+    reasonably simple form, that should satisfy a reasonably large
+    group of reasonable people.
+
+    David Goodger (goodger@python.org), 2001-04-20
+
+.. _Doc-SIG: http://www.python.org/sigs/doc-sig/
+
+
+History
+=======
+
+reStructuredText_, the specification, is based on StructuredText_ and
+Setext_.  StructuredText was developed by Jim Fulton of `Zope
+Corporation`_ (formerly Digital Creations) and first released in 1996.
+It is now released as a part of the open-source "Z Object Publishing
+Environment" (ZOPE_).  Ian Feldman's and Tony Sanders' earlier Setext_
+specification was either an influence on StructuredText or, by their
+similarities, at least evidence of the correctness of this approach.
+
+I discovered StructuredText_ in late 1999 while searching for a way to
+document the Python modules in one of my projects.  Version 1.1 of
+StructuredText was included in Daniel Larsson's pythondoc_.  Although
+I was not able to get pythondoc to work for me, I found StructuredText
+to be almost ideal for my needs.  I joined the Python Doc-SIG_
+(Documentation Special Interest Group) mailing list and found an
+ongoing discussion of the shortcomings of the StructuredText
+"standard".  This discussion has been going on since the inception of
+the mailing list in 1996, and possibly predates it.
+
+I decided to modify the original module with my own extensions and
+some suggested by the Doc-SIG members.  I soon realized that the
+module was not written with extension in mind, so I embarked upon a
+general reworking, including adapting it to the "re" regular
+expression module (the original inspiration for the name of this
+project).  Soon after I completed the modifications, I discovered that
+StructuredText.py was up to version 1.23 in the ZOPE distribution.
+Implementing the new syntax extensions from version 1.23 proved to be
+an exercise in frustration, as the complexity of the module had become
+overwhelming.
+
+In 2000, development on StructuredTextNG_ ("Next Generation") began at
+`Zope Corporation`_ (then Digital Creations).  It seems to have many
+improvements, but still suffers from many of the problems of classic
+StructuredText.
+
+I decided that a complete rewrite was in order, and even started a
+`reStructuredText SourceForge project`_ (now inactive).  My
+motivations (the "itches" I aim to "scratch") are as follows:
+
+- I need a standard format for inline documentation of the programs I
+  write.  This inline documentation has to be convertible to other
+  useful formats, such as HTML.  I believe many others have the same
+  need.
+
+- I believe in the Setext/StructuredText idea and want to help
+  formalize the standard.  However, I feel the current specifications
+  and implementations have flaws that desperately need fixing.
+
+- reStructuredText could form part of the foundation for a
+  documentation extraction and processing system, greatly benefitting
+  Python.  But it is only a part, not the whole.  reStructuredText is
+  a markup language specification and a reference parser
+  implementation, but it does not aspire to be the entire system.  I
+  don't want reStructuredText or a hypothetical Python documentation
+  processor to die stillborn because of over-ambition.
+
+- Most of all, I want to help ease the documentation chore, the bane
+  of many a programmer.
+
+Unfortunately I was sidetracked and stopped working on this project.
+In November 2000 I made the time to enumerate the problems of
+StructuredText and possible solutions, and complete the first draft of
+a specification.  This first draft was posted to the Doc-SIG in three
+parts:
+
+- `A Plan for Structured Text`__
+- `Problems With StructuredText`__
+- `reStructuredText: Revised Structured Text Specification`__
+
+__ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html
+__ http://mail.python.org/pipermail/doc-sig/2000-November/001240.html
+__ http://mail.python.org/pipermail/doc-sig/2000-November/001241.html
+
+In March 2001 a flurry of activity on the Doc-SIG spurred me to
+further revise and refine my specification, the result of which you
+are now reading.  An offshoot of the reStructuredText project has been
+the realization that a single markup scheme, no matter how well
+thought out, may not be enough.  In order to tame the endless debates
+on Doc-SIG, a flexible `Docstring Processing System framework`_ needed
+to be constructed.  This framework has become the more important of
+the two projects; reStructuredText_ has found its place as one
+possible choice for a single component of the larger framework.
+
+The project web site and the first project release were rolled out in
+June 2001, including posting the second draft of the spec [#spec-2]_
+and the first draft of PEPs 256, 257, and 258 [#peps-1]_ to the
+Doc-SIG.  These documents and the project implementation proceeded to
+evolve at a rapid pace.  Implementation history details can be found
+in the `project history file`_.
+
+In November 2001, the reStructuredText parser was nearing completion.
+Development of the parser continued with the addition of small
+convenience features, improvements to the syntax, the filling in of
+gaps, and bug fixes.  After a long holiday break, in early 2002 most
+development moved over to the other Docutils components, the
+"Readers", "Writers", and "Transforms".  A "standalone" reader
+(processes standalone text file documents) was completed in February,
+and a basic HTML writer (producing HTML 4.01, using CSS-1) was
+completed in early March.
+
+`PEP 287`_, "reStructuredText Standard Docstring Format", was created
+to formally propose reStructuredText as a standard format for Python
+docstrings, PEPs, and other files.  It was first posted to
+comp.lang.python_ and the Python-dev_ mailing list on 2002-04-02.
+
+Version 0.4 of the reStructuredText__ and `Docstring Processing
+System`_ projects were released in April 2002.  The two projects were
+immediately merged, renamed to "Docutils_", and a 0.1 release soon
+followed.
+
+.. __: `reStructuredText SourceForge project`_
+
+.. [#spec-2] The second draft of the spec:
+
+   - `An Introduction to reStructuredText`__
+   - `Problems With StructuredText`__
+   - `reStructuredText Markup Specification`__
+   - `Python Extensions to the reStructuredText Markup
+     Specification`__
+
+   __ http://mail.python.org/pipermail/doc-sig/2001-June/001858.html
+   __ http://mail.python.org/pipermail/doc-sig/2001-June/001859.html
+   __ http://mail.python.org/pipermail/doc-sig/2001-June/001860.html
+   __ http://mail.python.org/pipermail/doc-sig/2001-June/001861.html
+
+.. [#peps-1] First drafts of the PEPs:
+
+   - `PEP 256: Docstring Processing System Framework`__
+   - `PEP 258: DPS Generic Implementation Details`__
+   - `PEP 257: Docstring Conventions`__
+
+   Current working versions of the PEPs can be found in
+   http://docutils.sourceforge.net/docs/peps/, and official versions
+   can be found in the `master PEP repository`_.
+
+   __ http://mail.python.org/pipermail/doc-sig/2001-June/001855.html
+   __ http://mail.python.org/pipermail/doc-sig/2001-June/001856.html
+   __ http://mail.python.org/pipermail/doc-sig/2001-June/001857.html
+
+
+.. _Zope Corporation: http://www.zope.com
+.. _ZOPE: http://www.zope.org
+.. _reStructuredText SourceForge project:
+   http://structuredtext.sourceforge.net/
+.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/
+.. _StructuredTextNG:
+   http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG
+.. _project history file: ../../../HISTORY.html
+.. _PEP 287: ../../peps/pep-0287.html
+.. _Docstring Processing System framework: ../../peps/pep-0256.html
+.. _comp.lang.python: news:comp.lang.python
+.. _Python-dev: http://mail.python.org/pipermail/python-dev/
+.. _Docstring Processing System: http://docstring.sourceforge.net/
+.. _master PEP repository: http://www.python.org/peps/
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

docs/ref/rst/roles.txt

@@ -0,0 +1,380 @@
+=========================================
+ reStructuredText Interpreted Text Roles
+=========================================
+
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 7307 $
+:Date: $Date: 2012-01-06 12:11:51 +0100 (Fr, 06 Jan 2012) $
+:Copyright: This document has been placed in the public domain.
+
+This document describes the interpreted text roles implemented in the
+reference reStructuredText parser.
+
+Interpreted text uses backquotes (`) around the text.  An explicit
+role marker may optionally appear before or after the text, delimited
+with colons.  For example::
+
+    This is `interpreted text` using the default role.
+
+    This is :title:`interpreted text` using an explicit role.
+
+A default role may be defined by applications of reStructuredText; it
+is used if no explicit ``:role:`` prefix or suffix is given.  The
+"default default role" is `:title-reference:`_.  It can be changed
+using the default-role_ directive.
+
+See the `Interpreted Text`_ section in the `reStructuredText Markup
+Specification`_ for syntax details.  For details on the hierarchy of
+elements, please see `The Docutils Document Tree`_ and the `Docutils
+Generic DTD`_ XML document type definition.  For interpreted text role
+implementation details, see `Creating reStructuredText Interpreted
+Text Roles`_.
+
+.. _"role" directive: directives.html#role
+.. _default-role: directives.html#default-role
+.. _Interpreted Text: restructuredtext.html#interpreted-text
+.. _reStructuredText Markup Specification: restructuredtext.html
+.. _The Docutils Document Tree: ../doctree.html
+.. _Docutils Generic DTD: ../docutils.dtd
+.. _Creating reStructuredText Interpreted Text Roles:
+   ../../howto/rst-roles.html
+
+
+.. contents::
+
+
+---------------
+ Customization
+---------------
+
+Custom interpreted text roles may be defined in a document with the
+`"role" directive`_.  Customization details are listed with each role.
+
+.. _class:
+
+A ``class`` option is recognized by the "role" directive for most
+interpreted text roles.  A description__ is provided in the `"role"
+directive`_ documentation.
+
+__ directives.html#role-class
+
+
+----------------
+ Standard Roles
+----------------
+
+``:emphasis:``
+==============
+
+:Aliases: None
+:DTD Element: emphasis
+:Customization:
+    :Options: class_.
+    :Content: None.
+
+Implements emphasis.  These are equivalent::
+
+    *text*
+    :emphasis:`text`
+
+
+``:literal:``
+==============
+
+:Aliases: None
+:DTD Element: literal
+:Customization:
+    :Options: class_.
+    :Content: None.
+
+Implements inline literal text.  These are equivalent::
+
+    ``text``
+    :literal:`text`
+
+Care must be taken with backslash-escapes though.  These are *not*
+equivalent::
+
+    ``text \ and \ backslashes``
+    :literal:`text \ and \ backslashes`
+
+The backslashes in the first line are preserved (and do nothing),
+whereas the backslashes in the second line escape the following
+spaces.
+
+
+``:code:``
+==========
+
+:Aliases: None
+:DTD Element: literal
+:Customization:
+    :Options: class_, language
+    :Content: None.
+
+(New in Docutils 0.9.)
+
+The ``code`` role marks its content as code in a formal language.
+
+For syntax highlight of inline code, the `"role" directive`_ can be used to
+build custom roles with the code language specified in the "language"
+option.
+
+For example, the following creates a LaTeX-specific "latex" role::
+
+  .. role:: latex(code)
+     :language: latex
+
+Content of the new role is parsed and tagged by the Pygments_ syntax
+highlighter. See the `code directive`_ for more info on parsing and display
+of code in reStructuredText.
+
+In addition to "class_", the following option is recognized:
+
+``language`` : text
+    Name of the code's language.
+    See `supported languages and markup formats`_ for recognized values.
+
+.. _code directive: directives.html#code
+.. _Pygments: http://pygments.org/
+.. _supported languages and markup formats: http://pygments.org/languages/
+
+
+``:math:``
+==========
+
+:Aliases: None
+:DTD Element: math
+:Customization:
+    :Options: class_
+    :Content: None.
+
+(New in Docutils 0.8.)
+
+The ``math`` role marks its content as mathematical notation (inline
+formula).
+
+The input format is LaTeX math syntax without the “math delimiters“
+(``$ $``), for example::
+
+  The area of a circle is :math:`A_\text{c} = (\pi/4) d^2`.
+
+See the `math directive`_ (producing display formulas) for more info
+on mathematical notation in reStructuredText.
+
+.. _math directive: directives.html#math
+
+
+``:pep-reference:``
+===================
+
+:Aliases: ``:PEP:``
+:DTD Element: reference
+:Customization:
+    :Options: class_.
+    :Content: None.
+
+The ``:pep-reference:`` role is used to create an HTTP reference to a
+PEP (Python Enhancement Proposal).  The ``:PEP:`` alias is usually
+used.  For example::
+
+    See :PEP:`287` for more information about reStructuredText.
+
+This is equivalent to::
+
+    See `PEP 287`__ for more information about reStructuredText.
+
+    __ http://www.python.org/peps/pep-0287.html
+
+
+``:rfc-reference:``
+===================
+
+:Aliases: ``:RFC:``
+:DTD Element: reference
+:Customization:
+    :Options: class_.
+    :Content: None.
+
+The ``:rfc-reference:`` role is used to create an HTTP reference to an
+RFC (Internet Request for Comments).  The ``:RFC:`` alias is usually
+used.  For example::
+
+    See :RFC:`2822` for information about email headers.
+
+This is equivalent to::
+
+    See `RFC 2822`__ for information about email headers.
+
+    __ http://www.faqs.org/rfcs/rfc2822.html
+
+
+``:strong:``
+============
+
+:Aliases: None
+:DTD Element: strong
+:Customization:
+    :Options: class_.
+    :Content: None.
+
+Implements strong emphasis.  These are equivalent::
+
+    **text**
+    :strong:`text`
+
+
+``:subscript:``
+===============
+
+:Aliases: ``:sub:``
+:DTD Element: subscript
+:Customization:
+    :Options: class_.
+    :Content: None.
+
+Implements subscripts.
+
+.. Tip::
+
+   Whitespace or punctuation is required around interpreted text, but
+   often not desired with subscripts & superscripts.
+   Backslash-escaped whitespace can be used; the whitespace will be
+   removed from the processed document::
+
+       H\ :sub:`2`\ O
+       E = mc\ :sup:`2`
+
+   In such cases, readability of the plain text can be greatly
+   improved with substitutions::
+
+       The chemical formula for pure water is |H2O|.
+
+       .. |H2O| replace:: H\ :sub:`2`\ O
+
+   See `the reStructuredText spec`__ for further information on
+   `character-level markup`__ and `the substitution mechanism`__.
+
+   __ restructuredtext.html
+   __ restructuredtext.html#character-level-inline-markup
+   __ restructuredtext.html#substitution-references
+
+
+``:superscript:``
+=================
+
+:Aliases: ``:sup:``
+:DTD Element: superscript
+:Customization:
+    :Options: class_.
+    :Content: None.
+
+Implements superscripts.  See the tip in `:subscript:`_ above.
+
+
+``:title-reference:``
+=====================
+
+:Aliases: ``:title:``, ``:t:``.
+:DTD Element: title_reference
+:Customization:
+    :Options: class_.
+    :Content: None.
+
+The ``:title-reference:`` role is used to describe the titles of
+books, periodicals, and other materials.  It is the equivalent of the
+HTML "cite" element, and it is expected that HTML writers will
+typically render "title_reference" elements using "cite".
+
+Since title references are typically rendered with italics, they are
+often marked up using ``*emphasis*``, which is misleading and vague.
+The "title_reference" element provides accurate and unambiguous
+descriptive markup.
+
+Let's assume ``:title-reference:`` is the default interpreted text
+role (see below) for this example::
+
+    `Design Patterns` [GoF95]_ is an excellent read.
+
+The following document fragment (pseudo-XML_) will result from
+processing::
+
+    <paragraph>
+        <title_reference>
+            Design Patterns
+
+        <citation_reference refname="gof95">
+            GoF95
+         is an excellent read.
+
+``:title-reference:`` is the default interpreted text role in the
+standard reStructuredText parser.  This means that no explicit role is
+required.  Applications of reStructuredText may designate a different
+default role, in which case the explicit ``:title-reference:`` role
+must be used to obtain a ``title_reference`` element.
+
+
+.. _pseudo-XML: ../doctree.html#pseudo-xml
+
+
+-------------------
+ Specialized Roles
+-------------------
+
+``raw``
+=======
+
+:Aliases: None
+:DTD Element: raw
+:Customization:
+    :Options: class_, format
+    :Content: None
+
+.. WARNING::
+
+   The "raw" role is a stop-gap measure allowing the author to bypass
+   reStructuredText's markup.  It is a "power-user" feature that
+   should not be overused or abused.  The use of "raw" ties documents
+   to specific output formats and makes them less portable.
+
+   If you often need to use "raw"-derived interpreted text roles or
+   the "raw" directive, that is a sign either of overuse/abuse or that
+   functionality may be missing from reStructuredText.  Please
+   describe your situation in a message to the Docutils-users_ mailing
+   list.
+
+   .. _Docutils-users: ../../user/mailing-lists.html#docutils-user
+
+The "raw" role indicates non-reStructuredText data that is to be
+passed untouched to the Writer.  It is the inline equivalent of the
+`"raw" directive`_; see its documentation for details on the
+semantics.
+
+.. _"raw" directive: directives.html#raw-directive
+
+The "raw" role cannot be used directly.  The `"role" directive`_ must
+first be used to build custom roles based on the "raw" role.  One or
+more formats (Writer names) must be provided in a "format" option.
+
+For example, the following creates an HTML-specific "raw-html" role::
+
+    .. role:: raw-html(raw)
+       :format: html
+
+This role can now be used directly to pass data untouched to the HTML
+Writer.  For example::
+
+    If there just *has* to be a line break here,
+    :raw-html:`<br />`
+    it can be accomplished with a "raw"-derived role.
+    But the line block syntax should be considered first.
+
+.. Tip:: Roles based on "raw" should clearly indicate their origin, so
+   they are not mistaken for reStructuredText markup.  Using a "raw-"
+   prefix for role names is recommended.
+
+In addition to "class_", the following option is recognized:
+
+``format`` : text
+    One or more space-separated output format names (Writer names).

docs/ref/soextblx.dtd

@@ -0,0 +1,312 @@
+<!--
+===========================================================================
+    OASIS XML Exchange Table Model Declaration Module
+===========================================================================
+:Date: 1999-03-15
+-->
+
+<!-- This set of declarations defines the XML version of the Exchange
+     Table Model as of the date shown in the Formal Public Identifier
+     (FPI) for this entity.
+
+     This set of declarations may be referred to using a public external
+     entity declaration and reference as shown in the following three
+     lines:
+
+     <!ENTITY % calstblx
+       PUBLIC "-//OASIS//DTD XML Exchange Table Model 19990315//EN">
+       %calstblx;
+
+     If various parameter entities used within this set of declarations
+     are to be given non-default values, the appropriate declarations
+     should be given before calling in this package (i.e., before the
+     "%calstblx;" reference).
+-->
+
+<!-- The motivation for this XML version of the Exchange Table Model
+     is simply to create an XML version of the SGML Exchange Table
+     Model. By design, no effort has been made to "improve" the model.
+
+     This XML version incorporates the logical bare minimum changes
+     necessary to make the Exchange Table Model a valid XML DTD.
+-->
+
+<!-- The XML version of the Exchange Table Model differs from
+     the SGML version in the following ways:
+
+     The following parameter entities have been removed:
+
+       - tbl.table.excep, tbl.hdft.excep, tbl.row.excep, tbl.entry.excep
+         There are no exceptions in XML. The following normative statement
+         is made in lieu of exceptions: the exchange table model explicitly
+         forbids a table from occurring within another table. If the
+         content model of an entry includes a table element, then this
+         cannot be enforced by the DTD, but it is a deviation from the
+         exchange table model to include a table within a table.
+
+       - tbl.hdft.name, tbl.hdft.mdl, tbl.hdft.excep, tbl.hdft.att
+         The motivation for these elements was to change the table
+         header/footer elements. Since XML does not allow element declarations
+         to contain name groups, and the exchange table model does not
+         allow a table to contain footers, the continued presence of these
+         attributes seems unnecessary.
+
+     The following parameter entity has been added:
+
+       - tbl.thead.att
+         This entity parameterizes the attributes on thead. It replaces
+         the tbl.hdft.att parameter entity.
+
+     Other miscellaneous changes:
+
+       - Tag ommission indicators have been removed
+       - Comments have been removed from declarations
+       - NUMBER attributes have been changed to NMTOKEN
+       - NUTOKEN attributes have been to changed to NMTOKEN
+       - Removed the grouping characters around the content model
+         parameter entry for the 'entry' element. This is necessary
+         so that an entry can contain #PCDATA and be defined as an
+         optional, repeatable OR group beginning with #PCDATA.
+-->
+
+<!-- This entity includes a set of element and attribute declarations
+     that partially defines the Exchange table model.  However, the model
+     is not well-defined without the accompanying natural language
+     description of the semantics (meanings) of these various elements,
+     attributes, and attribute values.  The semantic writeup, also available
+     from SGML Open, should be used in conjunction with this entity.
+-->
+
+<!-- In order to use the Exchange table model, various parameter entity
+     declarations are required.  A brief description is as follows:
+
+     ENTITY NAME      WHERE USED              WHAT IT IS
+
+     %yesorno         In ATTLIST of:          An attribute declared value
+                      almost all elements     for a "boolean" attribute
+
+     %paracon         In content model of:    The "text" (logical content)
+                      <entry>                 of the model group for <entry>
+
+     %titles          In content model of:    The "title" part of the model
+                      table element           group for the table element
+
+     %tbl.table.name  In declaration of:      The name of the "table"
+                      table element           element
+
+     %tbl.table-titles.mdl In content model of: The model group for the title
+                      table elements          part of the content model for
+                                              table element
+
+     %tbl.table.mdl   In content model of:    The model group for the content
+                      table elements          model for table element,
+                                              often (and by default) defined
+                                              in terms of %tbl.table-titles.mdl
+                                              and tgroup
+
+     %tbl.table.att   In ATTLIST of:          Additional attributes on the
+                      table element           table element
+
+     %bodyatt         In ATTLIST of:          Additional attributes on the
+                      table element           table element (for backward
+                                              compatibility with the SGML
+                                              model)
+
+     %tbl.tgroup.mdl  In content model of:    The model group for the content
+                      <tgroup>                model for <tgroup>
+
+     %tbl.tgroup.att  In ATTLIST of:          Additional attributes on the
+4                      <tgroup>                <tgroup> element
+
+     %tbl.thead.att   In ATTLIST of:          Additional attributes on the
+                      <thead>                 <thead> element
+
+     %tbl.tbody.att   In ATTLIST of:          Additional attributes on the
+                      <tbody>                 <tbody> element
+
+     %tbl.colspec.att In ATTLIST of:          Additional attributes on the
+                      <colspec>               <colspec> element
+
+     %tbl.row.mdl     In content model of:    The model group for the content
+                      <row>                   model for <row>
+
+     %tbl.row.att     In ATTLIST of:          Additional attributes on the
+                      <row>                   <row> element
+
+     %tbl.entry.mdl   In content model of:    The model group for the content
+                      <entry>                 model for <entry>
+
+     %tbl.entry.att   In ATTLIST of:          Additional attributes on the
+                      <entry>                 <entry> element
+
+     This set of declarations will use the default definitions shown below
+     for any of these parameter entities that are not declared before this
+     set of declarations is referenced.
+-->
+
+<!-- These definitions are not directly related to the table model, but are
+     used in the default CALS table model and may be defined elsewhere (and
+     prior to the inclusion of this table module) in the referencing DTD. -->
+
+<!ENTITY % yesorno 'NMTOKEN'> <!-- no if zero(s), yes if any other value -->
+<!ENTITY % titles  'title?'>
+<!ENTITY % paracon '#PCDATA'> <!-- default for use in entry content -->
+
+<!--
+The parameter entities as defined below change and simplify the CALS table
+model as published (as part of the Example DTD) in MIL-HDBK-28001.  The
+resulting simplified DTD has support from the SGML Open vendors and is
+therefore more interoperable among different systems.
+
+These following declarations provide the Exchange default definitions
+for these entities.  However, these entities can be redefined (by giving
+the appropriate parameter entity declaration(s) prior to the reference
+to this Table Model declaration set entity) to fit the needs of the
+current application.
+
+Note, however, that changes may have significant effect on the ability to
+interchange table information.  These changes may manifest themselves
+in useability, presentation, and possible structure information degradation.
+-->
+
+<!ENTITY % tbl.table.name       "table">
+<!ENTITY % tbl.table-titles.mdl "%titles;,">
+<!ENTITY % tbl.table-main.mdl   "tgroup+">
+<!ENTITY % tbl.table.mdl        "%tbl.table-titles.mdl; %tbl.table-main.mdl;">
+<!ENTITY % tbl.table.att        "
+    pgwide      %yesorno;       #IMPLIED ">
+<!ENTITY % bodyatt              "">
+<!ENTITY % tbl.tgroup.mdl       "colspec*,thead?,tbody">
+<!ENTITY % tbl.tgroup.att       "">
+<!ENTITY % tbl.thead.att        "">
+<!ENTITY % tbl.tbody.att        "">
+<!ENTITY % tbl.colspec.att      "">
+<!ENTITY % tbl.row.mdl          "entry+">
+<!ENTITY % tbl.row.att          "">
+<!ENTITY % tbl.entry.mdl        "(%paracon;)*">
+<!ENTITY % tbl.entry.att        "">
+
+<!-- =====  Element and attribute declarations follow. =====  -->
+
+<!--
+     Default declarations previously defined in this entity and
+     referenced below include:
+     ENTITY % tbl.table.name       "table"
+     ENTITY % tbl.table-titles.mdl "%titles;,"
+     ENTITY % tbl.table.mdl        "%tbl.table-titles; tgroup+"
+     ENTITY % tbl.table.att        "
+                        pgwide          %yesorno;       #IMPLIED "
+-->
+
+<!ELEMENT %tbl.table.name; (%tbl.table.mdl;)>
+
+<!ATTLIST %tbl.table.name;
+        frame           (top|bottom|topbot|all|sides|none)      #IMPLIED
+        colsep          %yesorno;                               #IMPLIED
+        rowsep          %yesorno;                               #IMPLIED
+        %tbl.table.att;
+        %bodyatt;
+>
+
+<!--
+     Default declarations previously defined in this entity and
+     referenced below include:
+     ENTITY % tbl.tgroup.mdl    "colspec*,thead?,tbody"
+     ENTITY % tbl.tgroup.att    ""
+-->
+
+<!ELEMENT tgroup (%tbl.tgroup.mdl;) >
+
+<!ATTLIST tgroup
+        cols            NMTOKEN                                 #REQUIRED
+        colsep          %yesorno;                               #IMPLIED
+        rowsep          %yesorno;                               #IMPLIED
+        align           (left|right|center|justify|char)        #IMPLIED
+        %tbl.tgroup.att;
+>
+
+<!--
+     Default declarations previously defined in this entity and
+     referenced below include:
+     ENTITY % tbl.colspec.att   ""
+-->
+
+<!ELEMENT colspec EMPTY >
+
+<!ATTLIST colspec
+        colnum          NMTOKEN                                 #IMPLIED
+        colname         NMTOKEN                                 #IMPLIED
+        colwidth        CDATA                                   #IMPLIED
+        colsep          %yesorno;                               #IMPLIED
+        rowsep          %yesorno;                               #IMPLIED
+        align           (left|right|center|justify|char)        #IMPLIED
+        char            CDATA                                   #IMPLIED
+        charoff         NMTOKEN                                 #IMPLIED
+        %tbl.colspec.att;
+>
+
+<!--
+     Default declarations previously defined in this entity and
+     referenced below include:
+     ENTITY % tbl.thead.att      ""
+-->
+
+<!ELEMENT thead (row+)>
+
+<!ATTLIST thead
+        valign          (top|middle|bottom)                     #IMPLIED
+        %tbl.thead.att;
+>
+
+<!--
+     Default declarations previously defined in this entity and
+     referenced below include:
+     ENTITY % tbl.tbody.att     ""
+-->
+
+<!ELEMENT tbody (row+)>
+
+<!ATTLIST tbody
+        valign          (top|middle|bottom)                     #IMPLIED
+        %tbl.tbody.att;
+>
+
+<!--
+     Default declarations previously defined in this entity and
+     referenced below include:
+     ENTITY % tbl.row.mdl       "entry+"
+     ENTITY % tbl.row.att       ""
+-->
+
+<!ELEMENT row (%tbl.row.mdl;)>
+
+<!ATTLIST row
+        rowsep          %yesorno;                               #IMPLIED
+        valign          (top|middle|bottom)                     #IMPLIED
+        %tbl.row.att;
+>
+
+
+<!--
+     Default declarations previously defined in this entity and
+     referenced below include:
+     ENTITY % paracon           "#PCDATA"
+     ENTITY % tbl.entry.mdl     "(%paracon;)*"
+     ENTITY % tbl.entry.att     ""
+-->
+
+<!ELEMENT entry %tbl.entry.mdl;>
+
+<!ATTLIST entry
+        colname         NMTOKEN                                 #IMPLIED
+        namest          NMTOKEN                                 #IMPLIED
+        nameend         NMTOKEN                                 #IMPLIED
+        morerows        NMTOKEN                                 #IMPLIED
+        colsep          %yesorno;                               #IMPLIED
+        rowsep          %yesorno;                               #IMPLIED
+        align           (left|right|center|justify|char)        #IMPLIED
+        char            CDATA                                   #IMPLIED
+        charoff         NMTOKEN                                 #IMPLIED
+        valign          (top|middle|bottom)                     #IMPLIED
+        %tbl.entry.att;
+>

docs/ref/transforms.txt

@@ -0,0 +1,207 @@
+=====================
+ Docutils Transforms
+=====================
+
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 7530 $
+:Date: $Date: 2012-10-16 14:40:36 +0200 (Di, 16 Okt 2012) $
+:Copyright: This document has been placed in the public domain.
+
+
+.. contents::
+
+Transforms change the document tree in-place, add to the tree, or prune it.
+Transforms resolve references and footnote numbers, process interpreted
+text, and do other context-sensitive processing. Each transform is a
+subclass of ``docutils.tranforms.Transform``.
+
+There are `transforms added by components`_, others (e.g.
+``parts.Contents``) are added by the parser, if a corresponding directive is
+found in the document.
+
+To add a transform, components (objects inheriting from
+Docutils.Component like Readers, Parsers, Writers, Input, Output) overwrite
+the ``get_transforms()`` method of their base class. After the Reader has
+finished processing, the Publisher calls
+``Transformer.populate_from_components()`` with a list of components and all
+transforms returned by the component's ``get_transforms()`` method are
+stored in a `transformer object` attached to the document tree.
+
+
+For more about transforms and the Transformer object, see also `PEP
+258`_. (The ``default_transforms()`` attribute of component classes mentioned
+there is deprecated. Use the ``get_transforms()`` method instead.)
+
+.. _PEP 258: ../peps/pep-0258.html#transformer
+
+
+Transforms Listed in Priority Order
+===================================
+
+Transform classes each have a default_priority attribute which is used by
+the Transformer to apply transforms in order (low to high). The default
+priority can be overridden when adding transforms to the Transformer object.
+
+
+==============================  ============================  ========
+Transform: module.Class         Added By                      Priority
+==============================  ============================  ========
+misc.class                      "class" (d/p)                 210
+
+references.Substitutions        standalone (r), pep (r)       220
+
+references.PropagateTargets     standalone (r), pep (r)       260
+
+frontmatter.DocTitle            standalone (r)                320
+
+frontmatter.DocInfo             standalone (r)                340
+
+frontmatter.SectSubTitle        standalone (r)                350
+
+peps.Headers                    pep (r)                       360
+
+peps.Contents                   pep (r)                       380
+
+universal.StripClasses...       Writer (w)                    420
+
+references.AnonymousHyperlinks  standalone (r), pep (r)       440
+
+references.IndirectHyperlinks   standalone (r), pep (r)       460
+
+peps.TargetNotes                pep (r)                       520
+
+references.TargetNotes          peps.TargetNotes (t/p)        0
+
+misc.CallBack                   peps.TargetNotes (t/p)        1
+
+references.TargetNotes          "target-notes" (d/p)          540
+
+references.Footnotes            standalone (r), pep (r)       620
+
+references.ExternalTargets      standalone (r), pep (r)       640
+
+references.InternalTargets      standalone (r), pep (r)       660
+
+parts.SectNum                   "sectnum" (d/p)               710
+
+parts.Contents                  "contents" (d/p),             720
+                                peps.Contents (t/p)
+
+universal.StripComments         Reader (r)                    740
+
+peps.PEPZero                    peps.Headers (t/p)            760
+
+components.Filter               "meta" (d/p)                  780
+
+universal.Decorations           Reader (r)                    820
+
+misc.Transitions                standalone (r), pep (r)       830
+
+universal.ExposeInternals       Reader (r)                    840
+
+references.DanglingReferences   standalone (r), pep (r)       850
+
+universal.Messages              Writer (w)                    860
+
+universal.FilterMessages        Writer (w)                    870
+
+universal.SmartQuotes           Parser                        850
+
+universal.TestMessages          DocutilsTestSupport           880
+
+writer_aux.Compound             newlatex2e (w)                910
+
+writer_aux.Admonitions          html4css1 (w),                920
+                                latex2e (w)
+
+misc.CallBack                   n/a                           990
+==============================  ============================  ========
+
+Key:
+
+* (r): Reader
+* (w): Writer
+* (d): Directive
+* (t): Transform
+* (/p): Via a "pending" node
+
+
+Transform Priority Range Categories
+===================================
+
+====  ====  ================================================
+ Priority
+----------  ------------------------------------------------
+From   To   Category
+====  ====  ================================================
+   0    99  immediate execution (added by another transform)
+ 100   199  very early (non-standard)
+ 200   299  very early
+ 300   399  early
+ 400   699  main
+ 700   799  late
+ 800   899  very late
+ 900   999  very late (non-standard)
+====  ====  ================================================
+
+
+Transforms added by components
+===============================
+
+
+readers.Reader:
+  | universal.Decorations,
+  | universal.ExposeInternals,
+  | universal.StripComments
+
+readers.ReReader:
+  None
+
+readers.standalone.Reader:
+  | references.Substitutions,
+  | references.PropagateTargets,
+  | frontmatter.DocTitle,
+  | frontmatter.SectionSubTitle,
+  | frontmatter.DocInfo,
+  | references.AnonymousHyperlinks,
+  | references.IndirectHyperlinks,
+  | references.Footnotes,
+  | references.ExternalTargets,
+  | references.InternalTargets,
+  | references.DanglingReferences,
+  | misc.Transitions
+
+readers.pep.Reader:
+  | references.Substitutions,
+  | references.PropagateTargets,
+  | references.AnonymousHyperlinks,
+  | references.IndirectHyperlinks,
+  | references.Footnotes,
+  | references.ExternalTargets,
+  | references.InternalTargets,
+  | references.DanglingReferences,
+  | misc.Transitions,
+  | peps.Headers,
+  | peps.Contents,
+  | peps.TargetNotes
+
+parsers.rst.Parser
+  universal.SmartQuotes
+
+writers.Writer:
+  | universal.Messages,
+  | universal.FilterMessages,
+  | universal.StripClassesAndElements
+
+writers.UnfilteredWriter
+  None
+
+writers.latex2e.Writer
+  writer_aux.Admonitions
+
+writers.html4css1.Writer:
+  writer_aux.Admonitions
+
+writers.odf_odt.Writer:
+  removes references.DanglingReferences

docs/user/Makefile.docutils-update

@@ -0,0 +1,9 @@
+slide-shows.s5.html: slide-shows.txt
+	rst2s5.py slide-shows.txt slide-shows.s5.html \
+		--config ../../tools/docutils.conf \
+		--overwrite-theme-files \
+		--link-stylesheet \
+		--no-generator --no-datestamp --no-source-link
+
+smartquotes.html: smartquotes.txt
+	rst2html.py smartquotes.txt smartquotes.html --smart-quotes=true

docs/user/docutils-05-compat.sty.txt

@@ -0,0 +1,738 @@
+==================================================================
+    Changes to the Docutils latex2e writer since version 0.5
+==================================================================
+
+A backwards compatibility style sheet
+*************************************
+
+:Author:    Guenter Milde
+:Contact:   docutils-develop@lists.sourceforge.net
+:Revision:  $Revision: 7302 $
+:Date:      $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:Copyright: © 2009 Günter Milde,
+:License:   Released under the terms of the `2-Clause BSD license`_, in short:
+
+   Copying and distribution of this file, with or without modification,
+   are permitted in any medium without royalty provided the copyright
+   notice and this notice are preserved.
+   This file is offered as-is, without any warranty.
+
+:Abstract:  This file documents changes and provides a style for best
+            possible compatibility to the behaviour of the `latex2e`
+            writer of Doctutils release 0.5.
+
+.. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause
+
+::
+
+  \NeedsTeXFormat{LaTeX2e}
+  \ProvidesPackage{docutils-05-compat}
+  [2009/03/26 v0.1 compatibility with rst2latex from Docutils 0.5]
+
+.. contents::
+   :depth: 3
+
+Usage
+=====
+
+* To get an (almost) identic look for your old documents,
+  place ``docutils-05-compat.sty`` in the TEXINPUT path (e.g.
+  the current work directory) and pass the
+  ``--stylesheet=docutils-05-compat`` option to ``rst2latex.py``.
+
+* To use your custom stylesheets without change, add them to the
+  compatibility style, e.g.
+  ``--stylesheet="docutils-05-compat,mystyle.tex``.
+
+.. tip:: As the changes include bug fixes that are partly reverted by this
+   style, it is recommended to adapt the stylesheets to the new version or
+   copy just the relevant parts of this style into them.
+
+Changes since 0.5
+=================
+
+Bugfixes
+--------
+
+* Newlines around comments, targets and references prevent run-together
+  paragraphs.
+
+  + An image directive with hyperlink reference or target did not start a
+    new paragraph (e.g. the first two image examples in
+    standalone_rst_latex.tex).
+
+  + Paragraphs were not separated if there was a (hyper) target definition
+    inbetween.
+
+  + Paragraphs did run together, if separated by a comment-paragraph in the
+    rst source.
+
+* Fixed missing and spurious internal links/targets.
+  Internal links now take you to the correct place.
+
+* Verbose and linked system messages.
+
+* `Figure and image alignment`_ now conforms to the rst definition.
+
+* Put `header and footer directive`__ content in \DUheader respective
+  \DUfooter macros (ignored by the default style/template).
+
+  (They were put inside hard-coded markup at the top/bottom of the document
+  without an option to get them on every page.)
+
+__ ../ref/rst/directives.html#document-header-footer
+
+* Render doctest blocks as literal blocks (fixes bug [1586058] doctest block
+  nested in admonition). I.e.
+
+  + indent doctest blocks by nesting in a quote environment. This is also
+    the rendering by the HTML writer (html4css2.css).
+  + apply the ``--literal-block-env`` setting also to doctest blocks.
+
+  .. warning::
+      (``--literal-block-env=verbatim`` and
+      ``--literal-block-env=lstlistings`` fail with literal or doctest
+      blocks nested in an admonition.
+
+* Two-way hyperlinked footnotes and support for symbol footnotes and
+  ``--footnote-references=brackets`` with ``--use-latex-footnotes``.
+
+* The packages `fixltx2e` (providing LaTeX patches and the \textsubscript
+  command) and `cmap` (including character maps in the generated PDF for
+  better search and copy-and-paste operations) are now always loaded
+  (configurable with custom templates_).
+
+Backwards compatibility:
+  "Bug for bug compatibility" is not provided.
+
+
+New configuration setting defaults
+----------------------------------
+
+- font-encoding: "T1" (formerly implicitely set by 'ae').
+- use-latex-toc: true (ToC with page numbers).
+- use-latex-footnotes: true (no mixup with figures).
+
+Backwards compatibility:
+  Reset to the former defaults with:
+
+  | font-encoding: ''
+  | use-latex-toc: False
+  | use-latex-footnotes: False
+
+  (in the config file) or the command line options:
+
+    ``--figure-footnotes --use-docutils-toc  --font-encoding=''``
+
+
+Cleaner LaTeX source
+--------------------
+
+New features:
+  * Remove redundant "double protection" from the encoding of the "special
+    printing characters" and square brackets, e.g. ``\%`` instead of
+    ``{\%}``.
+  * Remove some spurious whitespace, e.g. ``\item [what:] -> \item[what:]``.
+  * Use conventional style for "named" macros, e.g. ``\dots{}`` instead of
+    ``{\dots}``
+
+Backwards compatibility:
+  Changes do not affect the output.
+
+
+LaTeX style sheets
+------------------
+
+New Feature:
+  LaTeX packages can be used as ``--stylesheet`` argument without
+  restriction.
+
+Implementation:
+  Use ``\usepackage`` if style sheet ends with ``.sty`` or has no
+  extension and ``\input`` else.
+
+Rationale:
+  while ``\input`` works with extension as well as without extension,
+  ``\usepackage`` expects the package name without extension. (The latex2e
+  writer will strip a ``.sty`` extension.)
+
+
+Backwards compatibility:
+  Up to Docutils 0.5, if no filename extension is given in the
+  ``stylesheet`` argument, ``.tex`` is assumed (by latex).
+
+  Since Docutils 0.6, a stylesheet without filename extension is assumed to
+  be a LaTeX package (``*.sty``) and referenced with the ``\usepackage``
+  command.
+
+.. important::
+  Always specify the extension if you want the style sheet to be
+  ``\input`` by LaTeX.
+
+
+Templates
+---------
+
+New Feature:
+  Advanced configuration via custom templates.
+
+Implementation:
+  A ``--template`` option and config setting allows specification of a
+  template file.
+
+See the `LaTeX writer documentation`__ for details.
+
+__ latex.html#templates
+
+
+Custom roles
+------------
+
+New Feature: failsave implementation
+  As with classes to HTML objects, class arguments are silently ignored if
+  there is no styling rule for this class in a custom style sheet.
+
+New Feature: custom roles based on standard roles
+  As class support needs to be handled by the LaTeX writer, this feature was
+  not present "automatically" (as in HTML). Modified visit/depart_*()
+  methods for the standard roles now call visit/depart_inline() if there are
+  class arguments to the node.
+
+Backwards compatibility:
+  The implementation is fully backwards compatible. (SVN versions 5742 to
+  5861 contained an implementation that did not work with commands expecting
+  an argument.)
+
+Length units
+------------
+
+New Features:
+  1. Add default unit if none given.
+     A poll on docutils-users favoured ``bp`` (Big Point: 1 bp  = 1/72 in).
+
+  2. Do not change ``px`` to ``pt``.
+
+  3. Lengths specified in the document with unit "pt" will be written with
+     unit "bp" to the LaTeX source.
+
+Rationale:
+  1. prevent LaTeX error "missing unit".
+
+  2. ``px`` is a valid unit in pdftex since version 1.3.0 released on
+     2005-02-04:
+
+       1px defaults to 1bp (or 72dpi), but can be changed with the
+       ``\pdfpxdimen`` primitive.::
+
+          \pdfpxdimen=1in % 1 dpi
+          \divide\pdfpxdimen by 96 % 96 dpi
+
+       --  http://www.tug.org/applications/pdftex/NEWS
+
+     Modern TeX distributions use pdftex also for dvi generation (i.e.
+     ``latex`` actually calls ``pdftex`` with some options).
+
+  3. In Docutils (as well as CSS) the unit symbol "pt" denotes the
+     `Postscript point` or `DTP point` while LaTeX uses "pt" for the `LaTeX
+     point`, which is unknown to Docutils and 0.3 % smaller.
+
+     The `DTP point` is available in LaTeX as "bp" (big point):
+
+       1 pt = 1/72.25 in < 1 bp  = 1/72 in
+
+
+Backwards compatibility:
+  Images with width specification in ``px`` come out slightly (0.3 %) larger:
+
+    1 px = 1 bp  = 1/72 in > 1 pt = 1/72.25 in
+
+  This can be reset with ::
+
+    \pdfpxdimen=1pt
+
+.. caution:: It is impossible to revert the change of lengths specified with
+   "pt" or without unit in a style sheet, however the 0.3 % change will be
+   imperceptible in most cases.
+
+.. admonition:: Error ``illegal unit px``
+
+  The unit ``px`` is not defined in "pure" LaTeX, but introduced by the
+  `pdfTeX` converter on 2005-02-04. `pdfTeX` is used in all modern LaTeX
+  distributions (since ca. 2006) also for conversion into DVI.
+
+  If you convert the LaTeX source with a legacy program, you might get the
+  error ``illegal unit px``.
+
+  If updating LaTeX is not an option, just remove the ``px`` from the length
+  specification. HTML/CSS will default to ``px`` while the `latexe2` writer
+  will add the fallback unit ``bp``.
+
+
+Font encoding
+-------------
+
+New feature:
+  Do not mix font-encoding and font settings: do not load the obsolete
+  `ae` and `aeguill` packages unless explicitely required via the
+  ``--stylesheet`` option.
+
+  :font-encoding = "":  do not load `ae` and `aeguill`, i.e.
+
+                        * do not change font settings,
+                        * do not use the fontenc package
+                          (implicitely loaded via `ae`),
+                        * use LaTeX default font encoding (OT1)
+
+  :font-encoding = "OT1": load `fontenc` with ``\usepackage[OT1]{fontenc}``
+
+Example:
+  ``--font-encoding=LGR,T1`` becomes ``\usepackage[LGR,T1]{fontenc}``
+  (Latin, Latin-1 Supplement, and Greek)
+
+
+Backwards compatibility:
+  Load the ae and aeguill packages if fontenc is not used.
+
+.. tip:: Using `ae` is not recommended. A similar look (but better
+   implementation) can be achieved with the packages `lmodern`, `cmsuper`,
+   or `cmlgr` all providing Computer Modern look-alikes in vector format and
+   T1 encoding, e.g. ``--font-encoding=T1 --stylesheet=lmodern``.
+
+Sub- and superscript as text
+----------------------------
+
+New feature:
+  Set sub- and superscript role argument in text mode not as math.
+
+  Pass the role content to ``\textsubscript`` or ``\textsuperscript``.
+
+Backwards compatibility:
+  The old implementation set the role content in Math mode, where
+
+  * whitespace is ignored,
+  * a different command set and font setting scheme is active,
+  * Latin letters are typeset italic but numbers upright.
+
+  Although it is possible to redefine ``\textsubscript`` and
+  ``\textsuperscript`` to typeset the content in math-mode, this can lead to
+  errors with certain input and is therefore not done in this style sheet.
+
+.. tip:: To get italic subscripts, define and use in your document
+   `custom roles`_ like ``.. role:: sub(subscript)`` and
+   ``.. role:: super(superscript)`` and define the "role commands"::
+
+     \newcommand{\DUrolesub}{\itshape}
+     \newcommand{\DUrolesuper}{\itshape}
+
+   Alternatively, if you want all sub- and superscripts in italic, redefine
+   the macros::
+
+     %% \let\DUsup\textsubscript
+     %% \let\DUsuper\textsuperscript
+     %% \renewcommand*{\textsubscript}{\DUsub\itshape}
+     %% \renewcommand*{\textsuperscript}{\DUsuper\itshape}
+
+   This is not fully backwards compatible, as it will also set numbers in
+   italic shape and not ignore whitespace.
+
+Page layout
+-----------
+
+New features:
+  * Margins are configurable via the ``DIV=...`` document option.
+
+  * The ``\raggedbottom`` setting is no longer inserted into the document. It
+    is the default for article and report classes. If requested in combination
+    with a book class, it can be given in a custom style sheet.
+
+Backwards compatibility:
+  Up to version 0.5, use of `typearea` and a DIV setting of 12 were
+  hard-coded into the latex2e writer ::
+
+    \usepackage{typearea}
+    \typearea{12}
+
+  and the vertical alignment of lower boundary of the text area in book
+  classes disabled via ::
+
+    \raggedbottom
+
+
+ToC and section numbers
+-----------------------
+
+Better conformance to Docutils specifications.
+
+New feature:
+  * The "depth" argument of the "contents" and "sectnum" directives is
+    respected.
+
+  * section numbering independent of 'use-latex-toc':
+
+    + sections are only numbered if there is a "sectnum" directive in the
+      document
+
+    + section numbering by LaTeX if the "sectnum_xforms" config setting is
+      False.
+
+Backwards compatibility:
+
+  The previous behaviour was to always number sections if 'use-latex-toc' is
+  true, using the document class defaults. It cannot be restored
+  universally, the following code sets the default values of the "article"
+  document class::
+
+    \setcounter{secnumdepth}{3}
+    \setcounter{tocdepth}{3}
+
+.. TODO or not to do? (Back-compatibility problems)
+  * The default "depth" of the LaTeX-created ToC and the LaTeX section
+    numbering is increased to the number of supported section levels.
+
+New feature:
+  If 'use-latex-toc' is set, local tables of content are typeset using the
+  'minitoc' package (instead of being ignored).
+
+Backwards compatibility:
+  Disable the creation of local ToCs (ignoring all special commands) by
+  replacing ``\usepackage{minitoc} with ``\usepackage{mtcoff}``.
+
+
+Default font in admonitions and sidebar
+---------------------------------------
+
+New feature:
+  Use default font in admonitions and sidebar.
+
+Backward compatibility:
+  See the fallback definitions for admonitions_, `topic title`_ and
+  `sidebar`_.
+
+
+Figure placement
+----------------
+
+New feature:
+  Use ``\floatplacement`` from the `float` package instead of
+  "hard-coded" optional argument for the global setting.
+
+  Default to ``\floatplacement{figure}{H}`` (here definitely). This
+  corresponds most closely to the source and HTML placement (principle of
+  least surprise).
+
+Backwards compatibility:
+  Set the global default back to the previous used value::
+
+    \usepackage{float}
+    \floatplacement{figure}{htbp} % here, top, bottom, extra-page
+
+
+Figure and image alignment
+--------------------------
+
+New features:
+
+a) Fix behaviour of 'align' argument to a figure (do not align figure
+   contents).
+
+   As the 'figwidth' argument is still ignored and the "natural width" of a
+   figure in LaTeX is 100% \textwidth, setting the 'align' argument of a
+   figure has currently no effect on the LaTeX output.
+
+b) Set default align of image in a figure to 'center'.
+
+c) Also center images that are wider than textwidth.
+
+d) Align images with class "align-[right|center|left]" (allows setting the
+   alignment of an image in a figure).
+
+Backwards compatibility:
+   There is no "automatic" way to reverse these changes via a style sheet.
+
+a) The alignment of the image can be set with the "align-left",
+   "align-center" and "align-right" class arguments.
+
+   As previously, the caption of a figure is aligned according to the
+   document class -- configurable with a style sheet using the "caption"
+   package.
+
+b) See a)
+
+c) Set the alignment of "oversized" images to "left" to get back the
+   old placement.
+
+Shorter preamble
+----------------
+
+New feature:
+  The document preamble is pruned to contain only relevant commands and
+  settings.
+
+Packages that are no longer required
+````````````````````````````````````
+
+The following packages where required in pre-0.5 versions and still loaded
+with version 0.5::
+
+  \usepackage{shortvrb}
+  \usepackage{amsmath}
+
+
+Packages that are conditionally loaded
+``````````````````````````````````````
+
+Additional to the `typearea` for `page layout`_, the following packages are
+only loaded if actually required by doctree elements:
+
+Tables
+^^^^^^
+
+Standard package for tables across several pages::
+
+  \usepackage{longtable}
+
+Extra space between text in tables and the line above them
+('array' is implicitely loaded by 'tabularx', see below)::
+
+  \usepackage{array}
+  \setlength{\extrarowheight}{2pt}
+
+Table cells spanning multiple rows::
+
+  \usepackage{multirow}
+
+Docinfo
+^^^^^^^
+
+One-page tables with auto-width columns::
+
+  \usepackage{tabularx}
+
+Images
+^^^^^^
+Include graphic files::
+
+  \usepackage{graphicx}
+
+Problematic, Sidebar
+^^^^^^^^^^^^^^^^^^^^
+Set text and/or background colour, coloured boxes with ``\colorbox``::
+
+  \usepackage{color}
+
+Floats for footnotes settings
+`````````````````````````````
+
+Settings for the use of floats for footnotes are only included if
+
+* the option "use-latex-footnotes" is False, and
+* there is at least one footnote in the document.
+
+::
+
+  % begin: floats for footnotes tweaking.
+  \setlength{\floatsep}{0.5em}
+  \setlength{\textfloatsep}{\fill}
+  \addtolength{\textfloatsep}{3em}
+  \renewcommand{\textfraction}{0.5}
+  \renewcommand{\topfraction}{0.5}
+  \renewcommand{\bottomfraction}{0.5}
+  \setcounter{totalnumber}{50}
+  \setcounter{topnumber}{50}
+  \setcounter{bottomnumber}{50}
+  % end floats for footnotes
+
+
+Special lengths, commands, and environments
+-------------------------------------------
+
+Removed definitions
+```````````````````
+
+admonition width
+^^^^^^^^^^^^^^^^
+The ``admonitionwith`` lenght is replaced by the more powerful
+``\DUadmonition`` command (see admonitions_).
+
+Backwards compatibility:
+  The default value (90 % of the textwidth) is unchanged.
+
+  To configure the admonition width, you must redefine the ``DUadmonition``
+  command instead of changing the ``admonitionwith`` length value.
+
+
+Renamed definitions (now conditional)
+`````````````````````````````````````
+
+The names for special doctree elements are now prefixed with ``DU``.
+
+Up to version 0.5, all definitions were included in the preamble (before the
+style sheet) of every document -- even if not used in the body. Since
+version 0.6, fallback definitions are included after the style sheet and
+only if required.
+
+Customization is done by an alternative definition in a style sheet with
+``\newcommand`` instead of the former ``\renewcommand``.
+
+The following code provides the old definitions and maps them (or their
+custom variants) to the new interface.
+
+docinfo width
+^^^^^^^^^^^^^
+::
+
+  \newlength{\docinfowidth}
+  \setlength{\docinfowidth}{0.9\textwidth}
+
+  \newlength{\DUdocinfowidth}
+  \AtBeginDocument{\setlength{\DUdocinfowidth}{\docinfowidth}}
+
+line block
+^^^^^^^^^^
+::
+
+  \newlength{\lineblockindentation}
+  \setlength{\lineblockindentation}{2.5em}
+  \newenvironment{lineblock}[1]
+  {\begin{list}{}
+    {\setlength{\partopsep}{\parskip}
+     \addtolength{\partopsep}{\baselineskip}
+     \topsep0pt\itemsep0.15\baselineskip\parsep0pt
+     \leftmargin#1}
+   \raggedright}
+  {\end{list}}
+
+  \newlength{\DUlineblockindent}
+  \AtBeginDocument{\setlength{\DUlineblockindent}{\lineblockindentation}}
+  \newenvironment{DUlineblock}[1]
+    {\begin{lineblock}{#1}}
+    {\end{lineblock}}
+
+local line width
+^^^^^^^^^^^^^^^^
+
+The ``\locallinewidth`` length for internal use in tables is replaced
+by ``\DUtablewidth``. It was never intended for customization::
+
+  \newlength{\locallinewidth}
+
+option lists
+^^^^^^^^^^^^
+::
+
+  \newcommand{\optionlistlabel}[1]{\bf #1 \hfill}
+  \newenvironment{optionlist}[1]
+  {\begin{list}{}
+    {\setlength{\labelwidth}{#1}
+     \setlength{\rightmargin}{1cm}
+     \setlength{\leftmargin}{\rightmargin}
+     \addtolength{\leftmargin}{\labelwidth}
+     \addtolength{\leftmargin}{\labelsep}
+     \renewcommand{\makelabel}{\optionlistlabel}}
+  }{\end{list}}
+
+  \newcommand{\DUoptionlistlabel}{\optionlistlabel}
+  \newenvironment{DUoptionlist}
+    {\begin{optionlist}{3cm}}
+    {\end{optionlist}}
+
+rubric
+^^^^^^
+Now less prominent (not bold, normal size) restore with::
+
+  \newcommand{\rubric}[1]{\subsection*{~\hfill {\it #1} \hfill ~}}
+  \newcommand{\DUrubric}[2][class-arg]{\rubric{#2}}
+
+title reference role
+^^^^^^^^^^^^^^^^^^^^
+::
+
+  \newcommand{\titlereference}[1]{\textsl{#1}}
+  \newcommand{\DUroletitlereference}[1]{\titlereference{#1}}
+
+
+New definitions
+```````````````
+
+New Feature:
+  Enable customization of some more Docutils elements with special commands
+
+  :admonition: ``DUadmonition`` command (replacing ``\admonitionwidth``),
+  :field list: ``DUfieldlist``  environment,
+  :legend:     ``DUlegend``     environment,
+  :sidebar:    ``\DUsidebar``, ``\DUtitle``, and
+               ``DUsubtitle`` commands,
+  :topic:      ``\DUtopic`` and ``\DUtitle`` commands,
+  :transition: ``\DUtransition`` command.
+  :footnotes:  ``\DUfootnotemark`` and ``\DUfootnotetext`` commands with
+               hyperlink support using the Docutils-provided footnote label.
+
+Backwards compatibility:
+  In most cases, the default definition corresponds to the previously used
+  construct. The following definitions restore the old behaviour in case of
+  changes.
+
+admonitions
+^^^^^^^^^^^
+Use sans-serif fonts::
+
+  \newcommand{\DUadmonition}[2][class-arg]{%
+    \begin{center}
+      \fbox{\parbox{0.9\textwidth}{\sffamily #2}}
+    \end{center}
+  }
+
+dedication
+^^^^^^^^^^
+Do not center::
+
+  \newcommand{\DUtopicdedication}[1]{#1}
+
+But center the title::
+
+  \newcommand*{\DUtitlededication}[1]{\centerline{\textbf{#1}}}
+
+sidebar
+^^^^^^^
+Use sans-serif fonts, a frame, and a darker shade of grey::
+
+  \providecommand{\DUsidebar}[2][class-arg]{%
+    \begin{center}
+      \sffamily
+      \fbox{\colorbox[gray]{0.80}{\parbox{0.9\textwidth}{#2}}}
+    \end{center}
+  }
+
+sidebar sub-title
+^^^^^^^^^^^^^^^^^
+Bold instead of emphasized::
+
+  \providecommand*{\DUsubtitlesidebar}[1]{\hspace*{\fill}\\
+    \textbf{#1}\smallskip}
+
+topic
+^^^^^
+No quote but normal text::
+
+  \newcommand{\DUtopic}[2][class-arg]{%
+    \ifcsname DUtopic#1\endcsname%
+      \csname DUtopic#1\endcsname{#2}%
+    \else
+      #2
+    \fi
+  }
+
+topic title
+^^^^^^^^^^^
+Title for "topics" (admonitions, sidebar).
+
+Larger font size::
+
+  \providecommand*{\DUtitletopic}[1]{\textbf{\large #1}\smallskip}
+
+transition
+^^^^^^^^^^
+Do not add vertical space after the transition. ::
+
+  \providecommand*{\DUtransition}[1][class-arg]{%
+    \hspace*{\fill}\hrulefill\hspace*{\fill}}

docs/user/emacs.txt

@@ -0,0 +1,960 @@
+.. -*- coding: utf-8 -*-
+
+========================================
+   Emacs Support for reStructuredText
+========================================
+
+:Authors: Stefan Merten <stefan@merten-home.de>, Martin Blais
+          <blais@furius.ca>
+:Version: ``rst.el`` V1.4.1
+:Abstract:
+
+    High-level description of the existing Emacs_ support for editing
+    reStructuredText_ text documents. Suggested setup code and usage
+    instructions are provided.
+
+.. contents::
+
+Introduction
+============
+
+reStructuredText_ is a syntax for simple text files that allows a
+tool set - docutils_ - to extract generic document structure. For
+people who use Emacs_, there is a package that adds a major mode that
+supports editing the syntax of reStructuredText_: ``rst.el``. This
+document describes the features it provides, and how to setup your
+Emacs_ to use them and how to invoke them.
+
+Installation
+============
+
+Emacs_ support for reStructuredText_ is implemented as an Emacs_ major
+mode (``rst-mode``) provided by the ``rst.el`` Emacs_ package.
+
+Emacs_ distributions contain ``rst.el`` since version V23.1. However,
+a significantly updated version of ``rst.el`` is contained in Emacs_
+V24.3. This document describes the version of ``rst.el`` contained in
+Emacs_ V24.3 and later versions. This version of ``rst.el`` has the
+internal version V1.4.1.
+
+If you have Emacs_ V24.3 or later you do not need to install anything
+to get reST support. If you have an Emacs_ between V23.1 and V24.2 you
+may use the version of ``rst.el`` installed with Emacs_ or install a
+more recent one locally_ (recommended). In other cases you need to
+install ``rst.el`` locally_ to get reST support.
+
+Checking situation
+------------------
+
+Here are some steps to check your situation:
+
+#. In Emacs_ switch to an empty buffer and try ::
+
+     M-x rst-mode
+
+   If this works you have ``rst.el`` installed somewhere. You can see
+   that it works if you find a string ``ReST`` in Emacs' modeline of
+   the current buffer. If this doesn't work you need to install
+   ``rst.el`` yourself locally_.
+
+#. In the buffer you just switched to ``rst-mode`` try ::
+
+     C-h v rst-version
+
+   If this fails you have a version of ``rst.el`` older than
+   V1.1.0. Either you have an old ``rst.el`` locally or you are using
+   an Emacs_ between V23.1 and V24.2. In this case it is recommended
+   that you install a more recent version of ``rst.el`` locally_.
+
+   You may also try ::
+
+     C-h v emacs-version
+
+   to find out your Emacs_ version.
+
+#. Check the version of ``rst.el``
+
+   The content of ``rst-version`` gives you the internal version of
+   ``rst.el``. The version contained in Emacs_ V24.3 and described here
+   is V1.4.0. If you have an older version you may or may not install
+   a more recent version of ``rst.el`` locally_.
+
+.. _locally:
+
+Local installation
+------------------
+
+If you decided to install locally please follow these steps.
+
+#. Download ``rst.el``
+
+   Download the most recent published version of ``rst.el`` from
+   http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/tools/editors/emacs/rst.el
+
+#. Put ``rst.el`` to a directory in ``load-path``
+
+   Use ::
+
+     C-h v load-path
+
+   If in the resulting list you find a directory in your home
+   directory put ``rst.el`` in this directory.
+
+   Make sure the directory is one of the first entries in
+   ``load-path``. Otherwise a version of ``rst.el`` which came with
+   Emacs_ may be found before your local version.
+
+   In Emacs_ see the info node ``Init File Examples`` for more
+   information on how to set up your Emacs_ initialization
+   machinery. Try ::
+
+     C-h i
+     mEmacs<Return>
+     sInit File Examples<Return>
+
+#. Enable ``rst-mode``
+
+   Add the following to your Emacs_ initialization setup ::
+
+     (require 'rst)
+
+   After you restarted Emacs_ ``rst.el`` is loaded and ready to be
+   used.
+
+Switching ``rst-mode`` on
+-------------------------
+
+By default ``rst-mode`` is switched on for files ending in ``.rst`` or
+``.rest``. If in a buffer you want to switch ``rst-mode`` on manually
+use ::
+
+  M-x rst-mode
+
+If you want to use ``rst-mode`` in files with other extensions modify
+``auto-mode-alist`` to automatically turn it on whenever you visit
+reStructuredText_ documents::
+
+   (setq auto-mode-alist
+         (append '(("\\.txt\\'" . rst-mode)
+                   ("\\.rst\\'" . rst-mode)
+                   ("\\.rest\\'" . rst-mode)) auto-mode-alist))
+
+Put the extensions you want in the correct place in the example
+above. Add more lines if needed.
+
+If have local variables enabled (try ``C-h v enable-local-variables``
+to find out), you can also add the following at the top of your
+documents to trigger rst-mode::
+
+   .. -*- mode: rst -*-
+
+Or this at the end of your documents::
+
+   ..
+      Local Variables:
+      mode: rst
+      End:
+
+Key bindings
+============
+
+``rst-mode`` automatically binds several keys for invoking special
+functions for editing reStructuredText_. Since ``rst-mode`` contains a
+lot of functionality most key bindings consist of three
+keystrokes.
+
+Following the Emacs_ conventions for major modes the key bindings of
+``rst-mode`` start with ``C-c C-<letter>``. The second key stroke
+selects a group of key bindings:
+
+C-c C-a
+  Commands to adjust the section headers and work with the hierarchy
+  they build.
+
+C-c C-c
+  Commands to compile the current reStructuredText_ document to
+  various output formats.
+
+C-c C-l
+  Commands to work with lists of various kinds.
+
+C-c C-r
+  Commands to manipulate the current region.
+
+C-c C-t
+  Commands to create and manipulate a table of contents.
+
+At any stage of typing you may use ``C-h`` to get help on the
+available key bindings. I.e. ``C-c C-h`` gives you help on all key
+bindings while ``C-c C-r C-h`` gives you help on the commands for
+regions. This is handy if you forgot a certain key binding.
+
+Additional key bindings which have a certain meaning in other Emacs_
+modes are reused in ``rst-mode`` so you don't have to learn a
+different set of key bindings for editing reStructuredText_.
+
+In ``rst-mode`` try ::
+
+  C-h m
+
+to list all mode specific key bindings. Most of the key bindings are
+described in this tutorial.
+
+.. note:: The key bindings have been completely revamped in ``rst.el``
+          V1.0.0. This was necessary to make room for new
+          functionality. Some of the old bindings still work but give
+          a warning to use the new binding. In the output of ``C-h m``
+          these bindings show up as ``rst-deprecated-...``. The old
+          bindings will be removed completely in a later version.
+
+Section Adornments
+==================
+
+``rst-mode`` recognizes the section adornments building the section
+hierarchy of the document. Section adornments are the underlines or
+under- and overlines used to mark a section title. There are a couple
+of commands to work with section adornments. These commands are bound
+to key bindings starting with ``C-c C-a``.
+
+Adjusting a Section Title
+-------------------------
+
+There is a function that helps a great deal to maintain these
+adornments: ``rst-adjust`` (bound to ``C-c C-a C-a``, ``C-c C-=``, and
+``C-=``). This function is a Swiss army knife that can be invoked
+repeatedly and whose behavior depends on context:
+
+#. If there is an incomplete adornment, e.g. ::
+
+      My Section Title
+      ==
+
+   invocation will complete the adornment. It can also be used to
+   adjust the length of the existing adornment when you need to edit
+   the title.
+
+#. If there is no section adornment at all, by default an adornment of
+   the same level as the last encountered section level is added. You
+   can simply enter a few characters of the title and invoke the
+   function to create the section adornment.
+
+   The variable ``rst-new-adornment-down`` can be customized to create
+   one level lower adornments than the previous section title instead
+   of keeping the level.
+
+#. If there is already a section adornment, it is promoted one level
+   up. You can invoke it like this repeatedly to cycle the title
+   through the hierarchy of existing adornments.
+
+Invoking the function with a negative prefix argument, e.g. ``C--
+C-=``, will effectively reverse the direction of adornment cycling.
+To alternate between underline-only and over-and-under styles, you can
+use a regular prefix argument, e.g. ``C-u C-=``. See the
+documentation of ``rst-adjust`` for more description of the prefix
+arguments to alter the behavior of the function.
+
+Promoting and Demoting Many Sections
+------------------------------------
+
+When you are re-organizing the structure of a document, it can be
+useful to change the level of a number of section titles. The same
+key binding can be used to do that: if the region is active when the
+binding is invoked, all the section titles that are within the region
+are promoted accordingly (or demoted, with negative prefix argument).
+
+Redoing All the Adornments to Your Taste
+----------------------------------------
+
+If you open someone else's file and the adornments it contains are
+unfamiliar, you may want to readjust them to fit your own preferred
+hierarchy of adornments. This can be difficult to perform by hand.
+However, you can do this easily by invoking
+``rst-straighten-adornments`` (``C-c C-a C-s``), which operates on the
+entire buffer.
+
+Customizations for Adornments
+-----------------------------
+
+You can customize the variable ``rst-preferred-adornments`` to a list
+of the adornments that you like to use for documents.
+
+If you prefer adornments according to
+http://sphinx-doc.org/rest.html#sections you may customize it to end
+up with a value like this::
+
+  ((35 over-and-under 0) ; ?#
+   (42 over-and-under 0) ; ?*
+   (61 simple 0) ; ?=
+   (45 simple 0) ; ?-
+   (94 simple 0) ; ?^
+   (34 simple 0)) ; ?"
+
+This will become the default in a later version of ``rst.el``.
+
+If you set ``rst-preferred-adornments`` to nil resembling the empty
+list only the section adornment found in the buffer will be used.
+
+Viewing the Hierarchy of Section Adornments
+-------------------------------------------
+
+You can visualize the hierarchy of the section adornments in the
+current buffer by invoking ``rst-display-adornments-hierarchy``, bound
+on ``C-c C-a C-d``. A temporary buffer will appear with fake section
+titles rendered in the style of the current document. This can be
+useful when editing other people's documents to find out which section
+adornments correspond to which levels.
+
+Movement and Selection
+======================
+
+Movement and Selection for Sections
+-----------------------------------
+
+You can move the cursor between the different section titles by using
+the ``rst-backward-section`` (``C-M-a``) and ``rst-forward-section``
+(``C-M-e``). To mark the section that cursor lies in, use
+``rst-mark-section`` (``C-M-h``).
+
+The key bindings are modeled after other modes with similar
+functionality.
+
+Movements and Selection for Text Blocks
+---------------------------------------
+
+The understanding of reStructuredText_ of ``rst-mode`` is used to set
+all the variables influencing Emacs' understanding of paragraphs. Thus
+all operations on paragraphs work as usual. For instance
+``forward-paragraph`` (``M-}``) works as usual.
+
+Indenting and Filling
+=====================
+
+Indentation of text plays a major role in the syntax of
+reStructuredText_. It is tedious to maintain the indentation
+manually. ``rst-mode`` understands most of the structure of
+reStructuredText_ allowing for sophisticated indentation and filling
+support described in this section.
+
+Indenting Text Blocks
+---------------------
+
+``rst-mode`` supports indentation of text blocks by the command
+``rst-shift-region`` (``C-c C-r TAB``). Mark a region and use ``C-c
+C-r TAB`` to indent all blocks one tab to the right. Use ``M-- C-c C-r
+TAB`` to indent the region one tab to the left.
+
+You may use arbitrary prefix arguments such as ``M-2`` or ``M-- 2`` to
+determine the number of tabs you want to indent. A prefix of ``M-0``
+removes all indentation in the active region.
+
+A tab is an indentation making sense for the block at hand in
+reStructuredText_ syntax. In some cases the exact indentation depends
+on personal taste. You may customize a couple of variables ``M-x
+customize-group<RET> rst-indent<RET>`` to match your taste.
+
+Indenting Lines While Typing
+----------------------------
+
+In Emacs_ the ``TAB`` key is often used for indenting the current
+line. ``rst-mode`` implements this for the sophisticated indentation
+rules of reStructuredText_. Pressing ``TAB`` cycles through the
+possible tabs for the current line. In the same manner
+``newline-and-indent`` (``C-j``) indents the new line properly.
+
+This is very handy while writing lists. Consider this
+reStructuredText_ bullet list with the cursor at ``@``::
+
+  * Level 1
+
+    * Level 2@
+
+Type ``C-j`` twice to get this::
+
+  * Level 1
+
+    * Level 2
+
+      @
+
+Now you an enter text at this level, or start a new list item by
+typing another ``*``. Or you may type ``TAB`` to reduce the
+indentation once::
+
+  * Level 1
+
+    * Level 2
+
+    @
+
+Typing another ``TAB`` gets you to the first level::
+
+  * Level 1
+
+    * Level 2
+
+  @
+
+.. note:: Since Emacs_ V24.4 ``electric-indent-mode`` is globally on.
+          This breaks indentation in ``rst-mode`` and renders
+          ``rst-mode`` mostly useless. This is fixed in V1.4.1 of
+          ``rst-mode``.
+
+          A quick fix for older versions of ``rst.el`` is to add the
+          following line at the end of the ``(define-derived-mode
+          rst-mode ...`` block in your copy of ``rst.el``::
+
+            (setq electric-indent-inhibit t)
+
+          You may also install V1.4.1 or newer locally_.
+
+Filling
+-------
+
+``rst-mode`` understanding the indentation rules of reStructuredText_
+also supports filling paragraphs. Just use ``fill-paragraph``
+(``M-q``) as you do in other modes.
+
+Operating on Lists
+==================
+
+Lists are supported in various flavors in reStructuredText_.
+``rst-mode`` understands reStructuredText_ lists and offers some
+support for operating on lists. Key bindings for commands for
+operating on lists start with ``C-c C-l``.
+
+Please note that so far definition lists are not explicitly supported
+by ``rst-mode``.
+
+Bulleted and Enumerated Lists
+-----------------------------
+
+If you have a couple of plain lines you want to turn into an
+enumerated list you can invoke ``rst-enumerate-region`` (``C-c C-l
+C-e``). For example, the following region ::
+
+  Apples
+
+  Oranges
+
+  Bananas
+
+becomes ::
+
+  1. Apples
+
+  2. Oranges
+
+  3. Bananas
+
+``rst-bullet-list-region`` (``C-c C-l C-b``) does the same, but
+results in a bullet list ::
+
+  * Apples
+
+  * Oranges
+
+  * Bananas
+
+By default, each paragraph starting on the leftmost line in the
+highlighted region will be taken to be a single list or enumeration
+item, for example, enumerating the following::
+
+   An apple a day
+   keeps the doctor away.
+
+   But oranges
+   are tastier than apples.
+
+   If you preferred bananas
+   you may be
+   a monkey.
+
+Will result in::
+
+   1. An apple a day
+      keeps the doctor away.
+
+   2. But oranges
+      are tastier than apples.
+
+   3. If you preferred bananas
+      you may be
+      a monkey.
+
+If you would like to enumerate each of the lines, use a prefix
+argument on the preceding commands, e.g.::
+
+  Apples
+  Oranges
+  Bananas
+
+becomes::
+
+  * Apples
+  * Oranges
+  * Bananas
+
+Straightening Existing Bullet List Hierarchies
+----------------------------------------------
+
+If you invoke ``rst-straighten-bullets-region`` (``C-c C-l C-s``), the
+existing bullets in the active region will be replaced to reflect
+their respective level. This does not make a difference in the
+document structure that reStructuredText_ defines, but looks better
+in, for example, if all of the top-level bullet items use the
+character ``-``, and all of the 2nd level items use ``*``, etc.
+
+Inserting a List Item
+---------------------
+
+To start a new list you may invoke ``rst-insert-list`` (``C-c C-l
+C-i``). You may choose from an item style supported by
+reStructuredText_.
+
+You may also invoke ``rst-insert-list`` at the end of a list item. In
+this case it inserts a new line containing the markup for the a list
+item on the same level.
+
+Operating on Other Text Blocks
+==============================
+
+Creating and Removing Line Blocks
+---------------------------------
+
+To create line blocks, first select the region to convert and invoke
+``rst-line-block-region`` ``C-c C-r C-l``. For example, the following
+::
+
+  Apples
+  Oranges
+  Bananas
+
+becomes ::
+
+  | Apples
+  | Oranges
+  | Bananas
+
+This works even if the region is indented. To remove line blocks,
+select a region and invoke with a prefix argument.
+
+Commenting a Region of Text
+---------------------------
+
+``rst-mode`` understands reStructuredText_ comments. Use
+``comment-dwim`` (``M-;``) to work on comments as usual::
+
+  Apples
+  Oranges
+  Bananas
+
+becomes::
+
+  ..
+     Apples
+     Oranges
+     Bananas
+
+To remove a comment you have to tell this to ``comment-dwim``
+explicitly by using a prefix argument (``C-u M-;``).
+
+Please note that only indented comments are supported properly by the
+parts of ``comment-dwim`` working on regions.
+
+.. _Conversion:
+
+Converting Documents from Emacs
+===============================
+
+``rst-mode`` provides a number of functions for running documents
+being edited through the docutils tools. The key bindings for these
+commands start with ``C-c C-c``.
+
+The main generic function is ``rst-compile`` (``C-c C-c C-c``). It
+invokes a compilation command with the correct output name for the
+current buffer and then invokes Emacs' compile function. It also looks
+for the presence of a ``docutils.conf`` configuration file in the
+parent directories and adds it to the command line options. There is also
+``rst-compile-alt-toolset`` (``C-c C-c C-a``) in case you often need
+run your document in a second toolset.
+
+You can customize the commands being used by setting
+``rst-compile-primary-toolset`` and ``rst-compile-secondary-toolset``.
+
+Other commands are available for other formats:
+
+* ``rst-compile-pseudo-region`` (``C-c C-c C-x``)
+
+  When crafting documents, it is often convenient to view which data
+  structures docutils will parse them into. You can use to run the
+  active region through ``rst2pseudoxml.py`` and have the output
+  automatically be displayed in a new buffer.
+  
+* ``rst-compile-pdf-preview`` (``C-c C-c C-p``)
+
+  Convert the current document to PDF and launch a viewer on the
+  results.
+  
+* ``rst-compile-slides-preview`` (``C-c C-c C-s``): Convert the
+  current document to S5 slides and view in a web browser.
+
+Imenu Support
+=============
+
+Using Imenu
+-----------
+
+Emacs_ has a package called ``imenu``. ``rst-mode`` supports Imenu by
+adding a function to convert the structure of a reStructuredText_
+buffer to an Imenu index. Thus you can use invoke ``imenu`` (``M-x
+imenu``) to navigate through the section index or invoke
+``imenu-add-to-menubar`` (``M-x imenu-add-to-menubar``) to add an
+Imenu menu entry to Emacs' menu bar.
+
+Using which function
+--------------------
+
+As a side effect of Imenu support the ``which-func`` package is also
+supported. Invoke ``which-function-mode`` (``M-x
+which-function-mode``) to add the name of the current section to the
+mode line. This is especially useful if you navigate through documents
+with long sections which do not fit on a single screen.
+
+Using the Table of Contents
+===========================
+
+The sections in a reStructuredText_ document can be used to form a
+table of contents. ``rst-mode`` can work with such a table of contents
+in various forms. Key bindings for these commands start with ``C-c
+C-t``.
+
+Navigating Using the Table of Contents
+--------------------------------------
+
+When you are editing long documents, it can be a bit difficult to
+orient yourself in the structure of your text. To that effect, a
+function is provided that presents a hierarchically indented table of
+contents of the document in a temporary buffer, in which you can
+navigate and press ``Return`` to go to a specific section.
+
+Invoke ``rst-toc`` (``C-c C-t C-t``). It presents a temporary buffer
+that looks something like this::
+
+  Table of Contents:
+  Debugging Meta-Techniques
+    Introduction
+    Debugging Solution Patterns
+      Recognize That a Bug Exists
+      Subdivide and Isolate
+      Identify and Verify Assumptions
+      Use a Tool for Introspection
+      Change one thing at a time
+      Learn about the System
+    Understanding a bug
+    The Basic Steps in Debugging
+    Attitude
+      Bad Feelings
+      Good Feelings
+    References
+
+When you move the cursor to a section title and press ``RET`` or ``f``
+or click with ``button1`` on a section title, the temporary buffer
+disappears and you are left with the cursor positioned at the chosen
+section. Clicking with ``button2`` jumps to the respective section but
+keeps the toc buffer. You can use this to look at the various section
+headers quickly. Use ``q`` in this buffer to just quit it without
+moving the cursor in the original document. Use ``z`` to zap the
+buffer altogether.
+
+Inserting a Table of Contents
+-----------------------------
+
+Oftentimes in long text documents that are meant to be read directly,
+a table of contents is inserted at the beginning of the text. In
+reStructuredText_ documents, since the table of contents is
+automatically generated by the parser with the ``.. contents::``
+directive, people generally have not been adding an explicit table of
+contents to their source documents, and partly because it is too much
+trouble to edit and maintain.
+
+The Emacs_ support for reStructuredText_ provides a function to insert
+such a table of contents in your document. Since it is not meant to
+be part of the document text, you should place such a table of
+contents within a comment, so that it is ignored by the parser. This
+is the favored usage::
+
+  .. contents::
+  ..
+      1  Introduction
+      2  Debugging Solution Patterns
+        2.1  Recognize That a Bug Exists
+        2.2  Subdivide and Isolate
+        2.3  Identify and Verify Assumptions
+        2.4  Use a Tool for Introspection
+        2.5  Change one thing at a time
+        2.6  Learn about the System
+      3  Understanding a bug
+      4  The Basic Steps in Debugging
+      5  Attitude
+        5.1  Bad Feelings
+        5.2  Good Feelings
+      6  References
+
+Just place the cursor at the top-left corner where you want to insert
+the TOC and invoke the function ``rst-toc-insert`` with ``C-c C-t
+C-i``. The table of contents will display all the section titles that
+are under the location where the insertion occurs. This way you can
+insert local table of contents by placing them in the appropriate
+location.
+
+You can use a numeric prefix argument to limit the depth of rendering
+of the TOC.
+
+You can customize the look of the TOC by setting the values of the
+following variables: ``rst-toc-indent``, ``rst-toc-insert-style``,
+``rst-toc-insert-max-level``.
+
+Maintaining the Table of Contents Up-to-date
+--------------------------------------------
+
+One issue is that you will probably want to maintain the inserted
+table of contents up-to-date. ``rst-toc-update`` (``C-c C-t C-u``)
+will automatically update an inserted table of contents following a
+``.. contents::`` directive laid out like the example above.
+
+Syntax Highlighting via Font-Lock
+=================================
+
+``rst-mode`` provides syntax highlighting for nearly all to
+reStructuredText_ constructs.
+
+Use ``customize-group rst-faces`` to customize the faces used for
+font-locking.
+
+Customization
+=============
+
+Some aspects of ``rst-mode`` can be configured through the
+customization feature of Emacs_. Try ::
+
+  M-x customize-group<RETURN>rst
+
+for all customizations or use the respective menu entry. Those
+customizations which are useful for many people are described in this
+section.
+
+Customizing Section Title Formatting
+------------------------------------
+
+For a couple of things the reStructuredText_ syntax offers a choice of
+options on how to do things exactly. Some of these choices influence
+the operation of ``rst.el`` and thus can be configured. The
+customizations are contained in the ``rst-adjust`` group.
+
+Among these things is the exact layout of section adornments. In fact
+reStructuredText_ prescribes only the characters and how these
+characters must be used but the exact use of concrete adornments may
+be different in every source file. Using the customization option
+``rst-preferred-adornments`` you can tell ``rst-mode`` on the exact
+sequence of adornments you prefer to markup the different levels of
+sections headers.
+
+Finally the title text of over-and-under adornments may be indented in
+reStructuredText_. ``rst-default-indent`` tells ``rst-mode`` how many
+positions a over-and-under adornment should be indented when toggling
+from simple adornment and in case a consistent indentation throughout
+the whole buffer for such adornment is needed.
+
+Customizing Indentation
+-----------------------
+
+reStructuredText_ uses indentation a lot to signify a certain meaning.
+In some cases the exact amount of indentation is prescribed by the
+syntax while in some cases the exact indentation is not fixed. The
+customization group ``rst-indent`` allows to customize the amount of
+indentation in these cases.
+
+In field lists the content of a field needs to be indented relative to
+the field label. ``rst-indent-field`` tells ``rst-mode`` the amount of
+indentation to use for field content. A value of zero always indents
+according to the content after the field label.
+
+The indentation of literal blocks is controlled by
+``rst-indent-literal-normal`` and ``rst-indent-literal-minimized``.
+The first is used when the leading literal tag (``::``) appears alone
+on a line. The second is used when the minimized style is used where
+the literal tag follows some text.
+
+The indentation of comments is controlled by ``rst-indent-comment``.
+Of course this makes only sense for the indented comments of
+reStructuredText_.
+
+Customization option ``rst-indent-width`` gives the default
+indentation when there are no other hints on what amount of
+indentation to use.
+
+Customizing Faces
+-----------------
+
+The faces used for font-locking can be defined in the ``rst-faces``
+customization group. The customization options ending in ``-face`` are
+only there for backward compatibility so please leave them as they
+are.
+
+reStructuredText_ sets no limit on the nesting of sections. By default
+there are six levels of fontification defined. Section titles deeper
+than six level have no special fontification - only the adornments are
+fontified. The exact mapping from a level to a face is done by by
+``rst-adornment-faces-alist``, however. So if you need fontification
+deeper than six levels you may want to customize this option. You may
+also want to customize it if you like the general idea of section
+title fontification in ``rst-mode`` but for instance prefer a reversed
+order.
+
+Customizing Conversion
+----------------------
+
+Conversion_ can be customized by the customization options in the
+customization group ``rst-compile``.
+
+If some conversion does not work as expected please check
+the variable ``rst-compile-toolsets`` ::
+
+  M-x customize-option<RETURN>rst-compile-toolsets
+
+This variable defines the commands and other details used for
+conversion. In case of problems please check that the commands are
+either available or customize them to what is available in your
+environment.
+
+.. note:: There are some options in V1.4.1 of ``rst.el`` which should
+          be customization options but are not yet. Customization
+          support will be added in a later version.
+
+.. note:: Please note that there is a package ``rst2pdf`` based on the
+          ReportLab library. Please note that the command of this
+          package requires an additional ``-o`` for naming the output
+          file. This breaks the usual conventions employed by Docutils
+          tools. ``rst-mode`` V1.4.1 does not support this directly.
+
+Other Customizations
+--------------------
+
+``rst-preferred-bullets`` can be customized to hold your preferred set
+of bullets to use for bulleted lists.
+
+``rst-mode-hook`` is a normal major mode hook which may be customized.
+It is run if you enter ``rst-mode``.
+
+Related aspects
+===============
+
+This section covers some general aspects using Emacs_ for editing
+reStructuredText_ source. They are not directly related to
+``rst-mode`` but may enhance your experience.
+
+``text-mode`` Settings
+----------------------
+
+Consult the Emacs_ manual for more ``text-mode`` customizations. In
+particular, you may be interested in setting the following variables,
+functions and modes that pertain somewhat to ``text-mode``:
+
+* ``indent-tabs-mode``
+* ``colon-double-space``
+* ``sentence-end-double-space``
+* ``auto-fill-mode``
+* ``auto-mode-alist``
+
+Editing Tables: Emacs table mode
+--------------------------------
+
+You may want to check out `Emacs table mode`_ to create an edit
+tables, it allows creating ASCII tables compatible with
+reStructuredText_.
+
+.. _Emacs table mode: http://table.sourceforge.net/
+
+Character Processing
+--------------------
+
+Since reStructuredText punts on the issue of character processing,
+here are some useful resources for Emacs_ users in the Unicode world:
+
+* `xmlunicode.el and unichars.el from Norman Walsh
+  <http://nwalsh.com/emacs/xmlchars/index.html>`__
+
+* `An essay by Tim Bray, with example code
+  <http://www.tbray.org/ongoing/When/200x/2003/09/27/UniEmacs>`__
+
+* For Emacs_ users on Mac OS X, here are some useful useful additions
+  to your .emacs file.
+
+  - To get direct keyboard input of non-ASCII characters (like
+    "option-e e" resulting in "é" [eacute]), first enable the option
+    key by setting the command key as your meta key::
+
+        (setq mac-command-key-is-meta t) ;; nil for option key
+
+    Next, use one of these lines::
+
+        (set-keyboard-coding-system 'mac-roman)
+        (setq mac-keyboard-text-encoding kTextEncodingISOLatin1)
+
+    I prefer the first line, because it enables non-Latin-1 characters
+    as well (em-dash, curly quotes, etc.).
+
+  - To enable the display of all characters in the Mac-Roman charset,
+    first create a fontset listing the fonts to use for each range of
+    characters using charsets that Emacs_ understands::
+
+      (create-fontset-from-fontset-spec
+       "-apple-monaco-medium-r-normal--10-*-*-*-*-*-fontset-monaco,
+        ascii:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman,
+        latin-iso8859-1:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman,
+        mule-unicode-0100-24ff:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman")
+
+    Latin-1 doesn't cover characters like em-dash and curly quotes, so
+    "mule-unicode-0100-24ff" is needed.
+
+    Next, use that fontset::
+
+        (set-frame-font "fontset-monaco")
+
+  - To enable cooperation between the system clipboard and the Emacs_
+    kill ring, add this line::
+
+        (set-clipboard-coding-system 'mac-roman)
+
+  Other useful resources are in `Andrew Choi's Emacs 21 for Mac OS X
+  FAQ <http://members.shaw.ca/akochoi-emacs/stories/faq.html>`__.
+
+Credits
+=======
+
+Part of the original code of ``rst.el`` has been written by Martin
+Blais and David Goodger and Wei-Wei Guo. The font-locking came from
+Stefan Merten.
+
+Most of the code has been modified, enhanced and extended by Stefan
+Merten who also is the current maintainer of ``rst.el``.
+
+.. _Emacs: http://www.gnu.org/software/emacs/emacs.html
+.. _reStructuredText: http://docutils.sf.net/rst.html
+.. _Docutils: http://docutils.sf.net/
+
+
+
+..  LocalWords:  reST utf Merten Blais rst el docutils modeline emacs
+..  LocalWords:  Init mEmacs sInit alist setq txt overlines RET nd py
+..  LocalWords:  dwim conf toolset pseudoxml pdf Imenu imenu menubar
+..  LocalWords:  func toc xmlunicode unichars eacute charset fontset
+..  LocalWords:  kTextEncodingISOLatin charsets monaco ascii latin
+..  LocalWords:  iso unicode Choi's Goodger Guo
+
+..
+   Local Variables:
+   mode: rst
+   indent-tabs-mode: nil
+   fill-column: 70
+   End:

docs/user/html.txt

@@ -0,0 +1,330 @@
+=====================
+Docutils HTML writers
+=====================
+
+.. contents::
+
+html
+----
+
+`html` is an alias for the default Docutils HTML writer.
+Currently, `html` is mapped to html4css1_.
+
+The target may change with the development of HTML, browsers, Docutils, and
+the web.
+
+* Use ``get_writer_by_name('html')`` or the rst2html.py_ front end, if you
+  want the output to be up-to-date automatically.
+
+* Use a specific writer name or front end, if you depend on stability of the
+  generated HTML code, e.g. because you use a custom style sheet or
+  post-processing that may break otherwise.
+
+
+html4css1
+---------
+
+:aliases:    html4, html_
+:front-ends: rst2html4.py, rst2html.py_
+:config:     `[html4css1 writer]`_
+
+The HTML Writer module, ``docutils/writers/html4css1.py``, was the first
+Docutils writer and up to release 0.13 the only official HTML writer.
+
+The output conforms to the `XHTML 1 Transitional`_ specification. It does
+not validate as `HTML 4.01 Transitional`_ due to the closing of empty tags
+required in XML but not allowed in HTML 4. However, the output follows the
+`HTML Compatibility Guidelines`_ for proper rendering on most HTML user
+agents.
+
+Correct rendering depends on a CSS_ style sheet. A reference style sheet,
+`html4css1.css`_, is provided and used by default.
+
+To support the `Internet Explorer` (with a market share of about 90% around
+2002, the time this writer was written), documents contain some hard-coded
+formatting hints and are tagged as "text/html" (instead of
+"application/xhtml+xml"). [#IE]_
+
+.. [#IE] Conformance to `CSS 2.1`_ has been added in IE 8 (2009), support
+   for XHTML in IE 9 (2011).
+
+.. _rst2html.py: tools.html#rst2html-py
+.. _[html4css1 writer]: config.html#html4css1-writer
+.. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css
+
+pep_html
+~~~~~~~~
+
+:front-end: rstpep2html.py_
+:config:    `[pep_html writer]`_
+
+This is a special writer for the generation of `Python Enhancement
+Proposals`_ (PEPs). It inherits from html4css1_ and adds some `PEP-specific
+options`_, a style sheet and template. The front-end uses also a specialised
+reader.
+
+.. _rstpep2html.py: tools.html#rstpep2html-py
+.. _PEP-specific options:
+.. _[pep_html writer]: config.html#pep-html-writer
+.. _Python Enhancement Proposals: https://www.python.org/dev/peps/
+
+s5_html
+~~~~~~~
+
+:alias:     s5
+:front-end: rst2s5.py_
+:config:    `[s5_html writer]`_
+
+The `s5` writer inherits from html4css1_. It produces XHTML for use with
+S5_, the “Simple Standards-based Slide Show System” by Eric Meyer.  See
+`Easy Slide Shows With reST & S5`_ for details.
+
+.. _rst2s5.py: tools.html#rst2s5-py
+.. _[s5_html writer]: config.html#s5-html-writer
+.. _Easy Slide Shows With reST & S5: slide-shows.html
+.. _S5: http://meyerweb.com/eric/tools/s5/
+.. _theme: tools.html#themes
+
+
+html5_polyglot
+--------------
+
+:aliases: html5
+:front-end: rst2html5.py_
+:config: `[html5 writer]`_
+
+The ``html5_polyglot`` writer generates `polyglot HTML`_ [#]_ output, valid
+XML [#safetext]_ that is compatible with `HTML5`_. New features and elements
+will only be used if they are widely supported to make documents `viewable
+with any browser`_.
+
+There is no hard-coded formatting information in the HTML document. Correct
+rendering of elements not directly supported by HTML depends on a CSS_ style
+sheet. The provided style sheets minimal.css_ and plain.css_ define required
+and optional styling rules respectively. Adaption of the layout is possible
+with `custom style sheets`_. [#safetext]_
+
+New in Docutils 0.13
+
+.. [#] see also `Benefits of polyglot XHTML5`_
+.. [#safetext] The validity of raw HTML and custom stylesheets must be
+   ensured by the author (e.g. using `safe text content`_).
+
+.. _rst2html5.py: tools.html#rst2html5-py
+.. _[html5 writer]: config.html#html5-writer
+.. _minimal.css: ../../docutils/writers/html5_polyglot/minimal.css
+.. _plain.css: ../../docutils/writers/html5_polyglot/plain.css
+.. _custom style sheets: ../howto/html-stylesheets.html
+.. _viewable with any browser: http://www.anybrowser.org/campaign
+.. _Benefits of polyglot XHTML5: http://xmlplease.com/xhtml/xhtml5polyglot/
+.. _safe text content:
+     https://www.w3.org/TR/html-polyglot/#dfn-safe-text-content
+
+
+HTML writers in the sandbox
+---------------------------
+
+There are two more HTML writers in the sandbox_:
+
+.. _sandbox: ../dev/policies.html#the-sandbox
+
+xhtml11
+~~~~~~~
+:aliases:   xhtml, html4strict
+:front-end: rst2xhtml.py
+:config:    `[xhtml11 writer]`
+
+`XHTML 1.1`_ is the latest version of the XML based `extensible
+Hypertext Markup Language` with an official DTD.
+
+The `xhtml11 writer`_ lives in the Docutils sandbox_ since 2008. The output
+conforms to the strict requirements of `XHTML 1.1`_.
+
+.. _xhtml11 writer: ../../../sandbox/html4strict/README.html
+
+
+html4trans
+~~~~~~~~~~
+
+:front-end: rst2html_trans.py_
+
+The `HTML writer for lightweight browsers`_ lives in the Docutils sandbox
+(`sandbox/html4trans`_) since 2008. It removes the dependency on CSS. The
+output conforms to `XHTML 1 Transitional`_ and contains sufficient
+formatting information for rendering without style sheet. (Of course, this
+has some drawbacks_.)
+
+.. _HTML writer for lightweight browsers:
+   ../../../sandbox/html4trans/README.html
+.. _drawbacks: ../../../sandbox/html4trans/README.html#drawbacks
+.. _sandbox/html4trans: ../../../sandbox/html4trans
+.. _rst2html_trans.py: ../../../sandbox/html4trans/tools/rst2html_trans.py
+
+
+Overview
+--------
+
+=============== =========== ============== ================= ===========
+name            alias(es)   `front-end`_   HTML version      CSS version
+=============== =========== ============== ================= ===========
+html4css1_      html4,      rst2html4.py,  `XHTML 1          `CSS 1`_
+                html_       rst2html.py    Transitional`_
+
+pep_html_       ..          rstpep2html.py `XHTML 1          `CSS 1`_
+                                           Transitional`_
+
+s5_html_        s5          rst2s5.py      `XHTML 1          `CSS 1`_
+                                           Transitional`_
+
+html5_polyglot_ html5       rst2html5.py   `HTML5`_          `CSS 3`_
+
+xhtml11_        xhtml,      rst2xhtml.py   `XHTML 1.1`_      `CSS 3`_
+                html4strict
+
+html4trans_ ..              rst2html_trans `XHTML 1          no CSS
+                                           Transitional`_    required
+=============== =========== ============== ================= ===========
+
+
+References
+----------
+
+_`HTML5`
+   `HTML5, A vocabulary and associated APIs for HTML and XHTML`,
+   W3C Recommendation, 28 October 2014.
+   http://www.w3.org/TR/html5/
+
+_`XHTML 1.1`
+   `XHTML™ 1.1 - Module-based XHTML - Second Edition`,
+   W3C Recommendation, 23 November 2010.
+   http://www.w3.org/TR/xhtml11/
+
+_`XHTML 1 Transitional`
+   `Transitional version`_ of:
+   `XHTML™ 1.0 The Extensible HyperText Markup Language (Second
+   Edition)`, `A Reformulation of HTML 4 in XML 1.0`,
+   W3C Recommendation, 26 January 2000, revised 1 August 2002.
+   http://www.w3.org/TR/xhtml1/
+
+_`XHTML Basic`
+   `XHTML™ Basic 1.1 - Second Edition`,
+   W3C Recommendation, 23 November 2010.
+   http://www.w3.org/TR/xhtml-basic/
+
+.. _transitional version:
+   http://www.w3.org/TR/xhtml1/#a_dtd_XHTML-1.0-Transitional
+
+_`HTML 4.01 Transitional`
+  Transitional version of:
+  `HTML 4.01 Specification`, W3C Recommendation 24 December 1999.
+  http://www.w3.org/TR/html4/
+
+.. _`CSS 1`:
+
+_`CSS Level 1`:
+  The features defined in the `CSS1 specification`_, but using the syntax
+  and definitions in the `CSS 2.1`_ specification.
+
+_`CSS 2.1` `Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification`,
+  W3C Recommendation 07 June 2011.
+  http://www.w3.org/TR/CSS21/
+
+_`CSS 3`:
+  CSS Level 3 builds on CSS Level 2 module by module, using the CSS2.1
+  specification as its core.
+
+  Specifications: http://www.w3.org/Style/CSS/specs.en.html
+
+  Validator: http://jigsaw.w3.org/css-validator/
+
+.. other references
+   ----------------
+
+.. _HTML Compatibility Guidelines: http://www.w3.org/TR/xhtml1/#guidelines
+.. _CSS: http://www.w3.org/TR/CSS/
+.. _CSS1 specification: http://www.w3.org/TR/2008/REC-CSS1-20080411/
+.. _polyglot HTML: http://www.w3.org/TR/html-polyglot/
+
+   .. Beware. This specification is no longer in active maintenance and the
+      HTML Working Group does not intend to maintain it further.
+
+.. Appendix
+
+
+      On the question of Polyglot markup, there seems to be little
+      consensus. One line of argument suggests that, to the extent that it
+      is practical to obey the Robustness principle, it makes sense to do
+      so. That is, if you're generating HTML markup for the web, and you can
+      generate Polyglot markup that is also directly consumable as XML, you
+      should do so. Another line of argument suggests that even under the
+      most optimistic of projections, so tiny a fraction of the web will
+      ever be written in Polyglot that there's no practical benefit to
+      pursuing it as a general strategy for consuming documents from the
+      web. If you want to consume HTML content, use an HTML parser that
+      produces an XML-compatible DOM or event stream.
+
+      -- https://www.w3.org/TR/html-xml-tf-report/#conclusions
+
+  Further development
+
+  On 2016-05-25, David Goodger wrote:
+
+  > In addition, I'd actually like to see the HTML writer(s) with
+  > fully-parameterized classes, i.e. removing hard-coded *classes* as well as
+  > formatting. This way, any user who wants to (e.g.) write reST for use with
+  > Bootstrap can easily work around any naming conflicts.
+
+
+
+  Problems with html4css1 writer:
+
+  1. Limiting ourself to CSS Level 1 requires use of hard-coded HTML
+     formatting to get all rST objects mapped to HTML.
+     Hard-coded HTML formatting is considered bad practice.
+
+  2. Maths cannot be included in MathML format without rendering a
+     hmtl4css1-generated document invalid.
+
+     (XHTML 1.1. is the only member of the "HTML4 family" allowing embedding
+     of MathML. However, hard-coded HTML formatting prevents its use.)
+
+
+
+  Comparison of current HTML versions
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  XHTML1.1
+  """"""""
+
+  +2 XML-based with official DTD
+     +1 allows processing with XML-tool-chain
+     +1 allows validating against the DTD
+
+  +1 writer exists (in sandbox) and in active use since 2008
+
+  -1 "old" format
+  -1 requires to work around restrictions lifted in HTML5
+     ("start" argument for enumerated lists, some tags in parsed literal)
+     which makes code and documents more complicated
+
+  HTML5
+  """""
+  +1 more recent
+  +1 simpler to write, less restrictions
+
+  +1 writer exists and in active use since 2015
+
+  +1 new page structure elements such as <main>, <section>, <article>,
+     <header>, <footer>, <aside>, <nav> and <figure>
+     provide better matches for the rst document model.
+
+  -1 new elements not yet supported by many browsers.
+
+  -2 no DTD
+     - no proper validation possible (there is an experimental validator)
+     - no standard interface to post-processing XML-tools
+
+  -1 two concurring definitions:
+     W3C standard and WHATWG "HTML Living Standard".
+
+.. _front-end: tools.html

docs/user/images/s5-files.svg

@@ -0,0 +1,639 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://web.resource.org/cc/"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="595.27559pt"
+   height="841.88976pt"
+   id="svg5904"
+   sodipodi:version="0.32"
+   inkscape:version="0.42"
+   sodipodi:docbase="/Users/david/projects/docutils/s5-branch/docs/user/images"
+   sodipodi:docname="s5-files.svg"
+   inkscape:export-filename="/Users/david/projects/docutils/s5-branch/docs/user/images/s5-files.png"
+   inkscape:export-xdpi="100.00000"
+   inkscape:export-ydpi="100.00000">
+  <defs
+     id="defs5906">
+    <marker
+       inkscape:stockid="Arrow1Mstart"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow1Mstart"
+       style="overflow:visible">
+      <path
+         sodipodi:nodetypes="ccccc"
+         id="path10526"
+         d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none"
+         transform="scale(0.4)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow1Lstart"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow1Lstart"
+       style="overflow:visible">
+      <path
+         sodipodi:nodetypes="ccccc"
+         id="path10529"
+         d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none"
+         transform="scale(0.8)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow2Mend"
+       style="overflow:visible;">
+      <path
+         sodipodi:nodetypes="cccc"
+         id="path10518"
+         style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;"
+         d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+         transform="scale(0.6) rotate(180) translate(-5,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mstart"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow2Mstart"
+       style="overflow:visible">
+      <path
+         sodipodi:nodetypes="cccc"
+         id="path10509"
+         style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round"
+         d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+         transform="scale(0.6) translate(-5,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Lend"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow2Lend"
+       style="overflow:visible;">
+      <path
+         sodipodi:nodetypes="cccc"
+         id="path10521"
+         style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;"
+         d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+         transform="scale(1.1) rotate(180) translate(-5,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Lstart"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow2Lstart"
+       style="overflow:visible">
+      <path
+         sodipodi:nodetypes="cccc"
+         id="path10512"
+         style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round"
+         d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+         transform="scale(1.1) translate(-5,0)" />
+    </marker>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.0050485"
+     inkscape:cx="359.99999"
+     inkscape:cy="345.00000"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     inkscape:window-width="1161"
+     inkscape:window-height="810"
+     inkscape:window-x="51"
+     inkscape:window-y="22"
+     showgrid="true"
+     inkscape:grid-bbox="true"
+     inkscape:grid-points="true"
+     gridspacingx="5.0000000px"
+     gridspacingy="5.0000000px"
+     gridtolerance="2.0000000px" />
+  <metadata
+     id="metadata5909">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     style="display:inline">
+    <g
+       id="g15792">
+      <g
+         transform="translate(-5.000000,-55.00000)"
+         id="g13828"
+         style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round">
+        <g
+           id="g13761"
+           style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round">
+          <path
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000"
+             d="M 451.84175,542.36220 L 490.47866,542.36220"
+             id="path13719" />
+          <path
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000"
+             d="M 515.00000,597.36220 L 491.83836,597.36220"
+             id="path13721" />
+          <path
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000"
+             d="M 515.00000,487.36218 L 491.83836,487.36218"
+             id="path13723" />
+          <path
+             id="path13725"
+             d="M 491.83836,487.36218 L 491.83836,597.36220 L 491.83836,707.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13757"
+             d="M 515.00000,707.36218 L 491.83836,707.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+        </g>
+        <g
+           id="g13695"
+           style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round">
+          <path
+             id="path10755"
+             d="M 451.84175,982.36220 L 490.47866,982.36220"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13691"
+             d="M 515.00000,1037.3622 L 491.83836,1037.3622"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13689"
+             d="M 515.00000,927.36218 L 491.83836,927.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13687"
+             d="M 491.83836,1037.3622 L 491.83836,927.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+        </g>
+        <g
+           id="g13174"
+           style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round">
+          <path
+             id="path9672"
+             d="M 205.00000,762.36217 L 275.47323,762.36217"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13150"
+             d="M 325.12023,762.36218 L 276.91055,762.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13148"
+             d="M 325.12023,872.36218 L 276.91055,872.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13146"
+             d="M 325.12023,982.36218 L 276.91055,982.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13156"
+             d="M 325.12023,542.36218 L 276.91055,542.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13154"
+             d="M 276.91055,982.36218 L 276.91055,542.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:none;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13144"
+             d="M 325.12023,652.36218 L 276.91055,652.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+        </g>
+      </g>
+      <g
+         transform="translate(-5.000000,-55.00000)"
+         id="g13805"
+         style="stroke:#000000;stroke-opacity:1.0000000">
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13533"
+           transform="translate(-160.0000,215.0000)">
+          <g
+             id="g13262"
+             transform="translate(522.7639,-102.4046)"
+             style="stroke:#000000;stroke-opacity:1.0000000">
+            <path
+               sodipodi:nodetypes="ccccccccc"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               id="path13264" />
+            <path
+               sodipodi:nodetypes="ccccccc"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               id="path13266" />
+          </g>
+          <text
+             sodipodi:linespacing="100.00000%"
+             id="text9098"
+             y="266.27817"
+             x="748.73212"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="266.27817"
+               x="748.73212"
+               id="tspan9100"
+               sodipodi:role="line">s5-core</tspan><tspan
+               id="tspan9102"
+               y="290.27818"
+               x="748.73212"
+               sodipodi:role="line">.css</tspan></text>
+        </g>
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13541"
+           transform="translate(-160.0000,215.0000)">
+          <g
+             style="stroke:#000000;stroke-opacity:1.0000000"
+             transform="translate(522.7639,7.595400)"
+             id="g13276">
+            <path
+               id="path13278"
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               sodipodi:nodetypes="ccccccccc" />
+            <path
+               id="path13280"
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               sodipodi:nodetypes="ccccccc" />
+          </g>
+          <text
+             sodipodi:linespacing="100.00000%"
+             id="text9104"
+             y="377.05817"
+             x="749.49524"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="377.05817"
+               x="749.49524"
+               id="tspan9106"
+               sodipodi:role="line">framing</tspan><tspan
+               id="tspan9108"
+               y="401.05818"
+               x="749.49524"
+               sodipodi:role="line">.css</tspan></text>
+        </g>
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13549"
+           transform="translate(-160.0000,215.0000)">
+          <g
+             style="stroke:#000000;stroke-opacity:1.0000000"
+             transform="translate(522.7639,117.5954)"
+             id="g13290">
+            <path
+               id="path13292"
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               sodipodi:nodetypes="ccccccccc" />
+            <path
+               id="path13294"
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               sodipodi:nodetypes="ccccccc" />
+          </g>
+          <text
+             transform="scale(1.075185,0.930073)"
+             sodipodi:linespacing="100.00000%"
+             id="text9110"
+             y="522.89044"
+             x="696.86365"
+             style="font-size:25.804459px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="522.89044"
+               x="696.86365"
+               id="tspan9112"
+               sodipodi:role="line">pretty</tspan><tspan
+               id="tspan9114"
+               y="548.69490"
+               x="696.86365"
+               sodipodi:role="line">.css</tspan></text>
+        </g>
+      </g>
+      <g
+         transform="translate(-5.000000,-55.00000)"
+         id="g13701"
+         style="stroke:#000000;stroke-opacity:1.0000000">
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13617"
+           transform="translate(-150.0000,240.0000)">
+          <g
+             id="g13322"
+             transform="translate(512.7639,312.5954)"
+             style="stroke:#000000;stroke-opacity:1.0000000">
+            <path
+               sodipodi:nodetypes="ccccccccc"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               id="path13324" />
+            <path
+               sodipodi:nodetypes="ccccccc"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               id="path13326" />
+          </g>
+          <text
+             sodipodi:linespacing="100.00000%"
+             id="text9122"
+             y="682.05817"
+             x="740.27032"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="682.05817"
+               x="740.27033"
+               id="tspan9124"
+               sodipodi:role="line">iepngfix</tspan><tspan
+               id="tspan9126"
+               y="706.05818"
+               x="740.27032"
+               sodipodi:role="line">.htc</tspan></text>
+        </g>
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13609"
+           transform="translate(-150.0000,240.0000)">
+          <g
+             style="stroke:#000000;stroke-opacity:1.0000000"
+             transform="translate(512.7639,422.5954)"
+             id="g13336">
+            <path
+               id="path13338"
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               sodipodi:nodetypes="ccccccccc" />
+            <path
+               id="path13340"
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               sodipodi:nodetypes="ccccccc" />
+          </g>
+          <text
+             sodipodi:linespacing="100.00000%"
+             id="text9116"
+             y="790.57019"
+             x="739.14758"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="790.57019"
+               x="739.14758"
+               id="tspan9118"
+               sodipodi:role="line">blank</tspan><tspan
+               id="tspan9120"
+               y="814.57020"
+               x="739.14758"
+               sodipodi:role="line">.gif</tspan></text>
+        </g>
+      </g>
+      <g
+         transform="translate(-5.000000,-55.00000)"
+         id="g13768"
+         style="stroke:#000000;stroke-opacity:1.0000000">
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g12998"
+           transform="translate(140.0000,160.0000)">
+          <g
+             id="g12960"
+             transform="translate(32.76392,117.5954)"
+             style="stroke:#000000;stroke-opacity:1.0000000">
+            <path
+               sodipodi:nodetypes="ccccccccc"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               id="path12962" />
+            <path
+               sodipodi:nodetypes="ccccccc"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               id="path12964" />
+          </g>
+          <text
+             sodipodi:linespacing="100.00000%"
+             id="text9080"
+             y="486.96219"
+             x="259.42813"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="486.96219"
+               x="259.42813"
+               id="tspan9082"
+               sodipodi:role="line">outline</tspan><tspan
+               id="tspan9084"
+               y="510.96220"
+               x="259.42813"
+               sodipodi:role="line">.css</tspan></text>
+        </g>
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13006"
+           transform="translate(140.0000,160.0000)">
+          <g
+             id="g12972"
+             transform="translate(32.76392,227.5954)"
+             style="stroke:#000000;stroke-opacity:1.0000000">
+            <path
+               sodipodi:nodetypes="ccccccccc"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               id="path12974" />
+            <path
+               sodipodi:nodetypes="ccccccc"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               id="path12976" />
+          </g>
+          <text
+             xml:space="preserve"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             x="259.34225"
+             y="596.96216"
+             id="text9284"
+             sodipodi:linespacing="100.00000%"><tspan
+               sodipodi:role="line"
+               id="tspan9290"
+               x="259.34226"
+               y="596.96216">print</tspan><tspan
+               sodipodi:role="line"
+               id="tspan9292"
+               x="259.34225"
+               y="620.96217">.css</tspan></text>
+        </g>
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13014"
+           transform="translate(140.0000,160.0000)">
+          <g
+             style="stroke:#000000;stroke-opacity:1.0000000"
+             transform="translate(32.76392,337.5954)"
+             id="g12978">
+            <path
+               id="path12980"
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               sodipodi:nodetypes="ccccccccc" />
+            <path
+               id="path12982"
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               sodipodi:nodetypes="ccccccc" />
+          </g>
+          <text
+             xml:space="preserve"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             x="259.56012"
+             y="706.32617"
+             id="text12043"
+             sodipodi:linespacing="100.00000%"><tspan
+               sodipodi:role="line"
+               id="tspan12045"
+               x="259.56012"
+               y="706.32617">opera</tspan><tspan
+               sodipodi:role="line"
+               x="259.56012"
+               y="730.32618"
+               id="tspan12047">.css</tspan></text>
+        </g>
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13022"
+           transform="translate(140.0000,160.0000)">
+          <g
+             id="g12984"
+             transform="translate(32.76392,447.5954)"
+             style="stroke:#000000;stroke-opacity:1.0000000">
+            <path
+               sodipodi:nodetypes="ccccccccc"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               id="path12986" />
+            <path
+               sodipodi:nodetypes="ccccccc"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               id="path12988" />
+          </g>
+          <text
+             sodipodi:linespacing="100.00000%"
+             id="text9092"
+             y="816.30219"
+             x="259.32312"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="816.30219"
+               x="259.32312"
+               id="tspan9094"
+               sodipodi:role="line">slides</tspan><tspan
+               id="tspan9096"
+               y="840.30220"
+               x="259.32312"
+               sodipodi:role="line">.js</tspan></text>
+        </g>
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g12990"
+           transform="translate(140.0000,160.0000)">
+          <g
+             style="stroke:#000000;stroke-opacity:1.0000000"
+             transform="translate(32.76392,7.595403)"
+             id="g12886">
+            <path
+               id="path2125"
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               sodipodi:nodetypes="ccccccccc" />
+            <path
+               id="path2168"
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               sodipodi:nodetypes="ccccccc" />
+          </g>
+          <text
+             transform="scale(1.003177,0.996833)"
+             sodipodi:linespacing="100.00000%"
+             id="text9074"
+             y="378.15045"
+             x="258.4964"
+             style="font-size:24.117754px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="378.15045"
+               x="258.49640"
+               id="tspan9076"
+               sodipodi:role="line">slides</tspan><tspan
+               id="tspan9078"
+               y="402.26821"
+               x="258.49640"
+               sodipodi:role="line">.css</tspan></text>
+        </g>
+      </g>
+      <g
+         id="g14176">
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13130"
+           transform="translate(0.000000,-54.99999)">
+          <path
+             sodipodi:nodetypes="ccccccccc"
+             d="M 209.99815,696.86669 L 210.00000,852.36217 L 75.000000,852.36217 L 75.000000,672.36217 L 75.000000,672.36217 L 161.90250,672.36347 C 164.47041,672.36479 166.91132,672.97771 169.09117,674.07931 L 208.96319,694.29521 C 209.63463,694.62733 209.96767,695.52913 209.99815,696.86669 z "
+             style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+             id="path12105" />
+          <path
+             id="path12107"
+             style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+             d="M 208.98791,694.31734 C 208.30060,693.96748 207.39771,694.23853 206.38536,694.97620 L 193.92602,704.33788 L 193.92602,704.33788 L 174.73992,678.74312 C 173.22293,676.78417 171.29202,675.17947 169.09117,674.07931 L 208.98791,694.31734 z "
+             sodipodi:nodetypes="ccccccc" />
+        </g>
+        <text
+           xml:space="preserve"
+           style="font-size:36.814487px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+           x="146.13911"
+           y="695.62231"
+           id="text9058"
+           sodipodi:linespacing="100.00000%"
+           transform="scale(0.997872,1.002133)"><tspan
+             sodipodi:role="line"
+             x="146.13911"
+             y="695.62231"
+             id="tspan9128"><tspan
+   id="tspan14172"
+   style="font-size:36.814487px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:99.999976%;writing-mode:lr-tb;text-anchor:middle;stroke:#000000;stroke-width:0.0000000;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000;font-family:Myriad" />*.html</tspan><tspan
+             sodipodi:role="line"
+             x="146.13912"
+             y="732.43680"
+             id="tspan14174">output</tspan></text>
+      </g>
+    </g>
+  </g>
+  <g
+     inkscape:groupmode="layer"
+     id="layer2"
+     inkscape:label="2"
+     style="display:inline" />
+</svg>

docs/user/links.txt

@@ -0,0 +1,464 @@
+=====================
+ Docutils_ Link List
+=====================
+
+:Author: Lea Wiemann, the Docutils team
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 8025 $
+:Date: $Date: 2017-02-06 15:35:40 +0100 (Mo, 06 Feb 2017) $
+:Copyright: This document has been placed in the public domain.
+
+.. title:: Docutils Links
+
+.. contents::
+
+This document contains links users of Docutils and reStructuredText
+may find useful.  Many of the projects
+listed here are hosted in the `Docutils Sandbox`_.  If you have
+something to publish, you can get write access, too!
+
+The most current version of this link list can always be found at
+http://docutils.sourceforge.net/docs/user/links.html.
+
+.. _Docutils: http://docutils.sourceforge.net/
+.. _Docutils Sandbox: http://docutils.sf.net/sandbox/README.html
+
+
+Editors
+-------
+
+Advanced text editors with reStructuredText support, IDEs, and docutils GUIs:
+
+* Emacs `rst mode <http://docutils.sf.net/tools/editors/emacs>`__.
+
+* `Vim <http://www.vim.org/index.php>`__:
+
+  - `reStructuredText syntax highlighting mode
+    <http://www.vim.org/scripts/script.php?script_id=973>`__,
+
+  - `VST <http://www.vim.org/scripts/script.php?script_id=1334>`__ (Vim
+    reStructuredText) plugin for Vim7 with folding.
+
+  - `VOoM <http://www.vim.org/scripts/script.php?script_id=2657>`__
+    plugin for Vim that emulates two-pane outliner with
+    support for reStructuredText (since version 4.0b2).
+
+  - `Riv: Take notes in rst <https://github.com/Rykka/riv.vim>`__ Vim
+    plugin to take notes in reStructured text.
+
+* `JED <http://www.jedsoft.org/jed/>`__ programmers editor with
+  `rst mode <http://jedmodes.sf.net/mode/rst/>`__
+
+* `reStructuredText editor plug-in for Eclipse`__
+
+  __ http://resteditor.sf.net/
+
+* Gnome's gedit offers syntax highlighting and a reST preview pane.
+
+  Latest version of the plugin is available from `bittner @ github`_
+  (See also: `Gedit third party plugins`__).
+
+  __ https://wiki.gnome.org/Apps/Gedit/ThirdPartyPlugins-v3.8
+
+  .. _bittner @ github:  https://github.com/bittner/gedit-reST-plugin
+
+* A BBEdit_/TextWrangler `language module`__ for editing reST documents.
+
+  .. _BBEdit: https://en.wikipedia.org/wiki/BBEdit
+  __ http://ericfromcanada.bitbucket.org/
+
+* Gunnar Schwant's DocFactory_ is a wxPython GUI application for
+  Docutils.
+
+* ReSTedit_ by Bill Bumgarner is a Docutils GUI for Mac OS X.
+
+* Leo_ is an outliner_, written in Python using PyQt. It can be used as IDE
+  for literal programming, as a filing cabinet holding any kind of data and
+  as `document editor`__ with outlines containing reStructuredText markup.
+
+  .. _outliner: http://en.wikipedia.org/wiki/Outliner
+  __ http://leoeditor.com/tutorial-rst3.html
+
+* `NoTex <https://notex.ch>`_ is a browser-based reStructuredText editor
+  with syntax highlighting and PDF/HTML export functionality using Sphinx.
+
+* `rsted <https://github.com/anru/rsted>`_ is a "simple online editor for
+  reStructuredText on Flask". You can try it on http://rst.ninjs.org/
+
+.. _DocFactory: http://docutils.sf.net/sandbox/gschwant/docfactory/doc/
+.. _ReSTedit: http://www.friday.com/bbum/index.php?s=restedit
+.. _Leo: http://leoeditor.com/
+
+
+Export
+------
+
+Convert reStructuredText to other formats:
+
+PDF
+```
+
+* `rst2pdf (reportlab)
+  <http://rst2pdf.googlecode.com>`_ is a tool to go
+  directly from reStructuredText to PDF, via `reportlab
+  <http://www.reportlab.org/rl_toolkit.html>`_. No LaTeX installation is
+  required.
+
+* `rst2pdf (pdflatex)
+  <http://docutils.sourceforge.net/sandbox/blais/rst2pdf/>`_ by Martin Blais
+  is a minimal front end producing LaTeX, compiling the LaTeX file, getting
+  the produced output to the destination location and finally deleting all
+  the messy temporary files that this process generates.
+
+* `rst2pdf (rubber)
+  <http://docutils.sf.net/sandbox/rst2pdf/README.html>`_ is
+  a front end for the generation of PDF documents from a reStructuredText
+  source via LaTeX in one step cleaning up intermediate files. It uses the
+  `rubber <http://iml.univ-mrs.fr/~beffara/soft/rubber/>`_ Python wrapper
+  for LaTeX and friends.
+
+* ``py.rest`` from the Codespeak `py Lib scripts`_ converts
+  reStructuredText files to HTML and PDF (cleaning up the intermediate
+  latex files).  Similar to ``buildhtml.py``, it looks recursively for
+  .txt files in the given PATHS.
+
+* rlpdf_ is another PDF Writer based on ReportLabs.
+
+* RinohType_ is a pure Python PDF Writer based on a document template and a
+  style sheet (beta).
+
+.. _py Lib scripts: http://codespeak.net/py/dist/bin.html
+.. _rlpdf: http://docutils.sf.net/sandbox/dreamcatcher/rlpdf/
+.. _RinohType: http://pypi.python.org/pypi/RinohType/0.2.1
+
+OpenOffice
+``````````
+
+* Since version 0.5, the odtwriter_ by Dave Kuhlman is part of the Docutils_
+  core.
+
+.. _odtwriter: http://docutils.sf.net/docs/user/odt.html
+
+
+website generators and HTML variants
+````````````````````````````````````
+
+* The Sphinx_ Python Documentation Generator by Georg Brandl was originally
+  created to translate the `Python documentation`_, and is now `used by
+  <http://sphinx.pocoo.org/examples.html>`__ a wide choice of projects.
+
+  It can generate complete web sites (interlinked and indexed HTML pages),
+  ePub, PDF, and others [#]_ from a set of rst source files.
+
+  .. [#] see http://sphinx-doc.org/config.html#options-for-epub-output
+  .. _Sphinx: http://sphinx.pocoo.org/
+
+* The Nikola_ static site generator, uses reStructuredText by
+  default.
+
+  .. _nikola:  http://getnikola.com/
+
+* Pelican_ is a static site generator (mainly for blogs). Articles/pages can
+  be written in reStructuredText or Markdown\ [#markdown]_ format.
+
+  .. _pelican: http://docs.getpelican.com
+
+* tinkerer_ is a static bloggin framework based on Sphinx_.
+
+  .. _tinkerer: http://tinkerer.me
+
+* rst2ht_ by Oliver Rutherfurd, converts reStructuredText to an .ht
+  template, for use with ht2html_.
+
+  .. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html
+  .. _ht2html: http://ht2html.sourceforge.net/
+
+* htmlnav_ by Gunnar Schwant, is an HTML writer which supports navigation
+  bars.
+
+  .. _htmlnav: http://docutils.sf.net/sandbox/gschwant/htmlnav/
+
+* rest2web_, by Michael Foord, is a tool for creating web sites with
+  reStructuredText.
+
+  .. _rest2web: http://www.voidspace.org.uk/python/rest2web/
+
+* rst2chm_ by Oliver Rutherfurd, generates Microsoft HTML Help files from
+  reStructuredText files.
+
+  .. _rst2chm: http://www.rutherfurd.net/software/rst2chm/
+
+* `html4strict <http://docutils.sf.net/sandbox/html4strict/>`__
+  produces XHTML that strictly conforms to the XHTML 1.0 specification.
+
+* `html4trans <http://docutils.sf.net/sandbox/html4trans/>`__
+  produces XHTML conforming to the version 1.0 Transitional DTD that
+  contains enough formatting information to be viewed by a lightweight HTML
+  browser without CSS support.
+
+* A `simple HTML writer`_ by Bill Bumgarner that doesn't rely on CSS
+  (stylesheets).
+
+  .. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/
+
+ePub
+````
+
+* The `rst2epub`_ project by Robert Wierschke converts simple
+  reStructuredText doucments into valid epub files.
+
+  .. simple but well structured with classes/modules for epub components,
+     and a standard ``setup.py`` installation file.
+
+* rst2epub2_ by Matt Harrison includes the epublib (originally by Tim
+  Tambin) and a rst2epub.py executable for the conversion.
+
+* Sphinx_ provides ePub as output option, too.
+
+.. _rst2epub: https://bitbucket.org/wierob/rst2epub
+.. _rst2epub2: https://github.com/mattharrison/rst2epub2
+
+
+Others
+``````
+
+* Pandoc_ is a document converter that can write Markdown\ [#markdown]_,
+  reStructuredText, HTML, LaTeX, RTF, DocBook XML, and S5.
+
+* restxsl_ by Michael Alyn Miller, lets you transform reStructuredText
+  documents into XML/XHTML files using XSLT stylesheets.
+
+* An `XSLT script`__ by Ladislav Lhotka enables reStructuredText annotations
+  to be included in RELAG NG XML schemas.
+
+  __ http://www.cesnet.cz/doc/techzpravy/2006/rngrest/
+
+* `DocBook Writer`_ by Oliver Rutherfurd.
+
+* Nabu_, written by Martin Blais, is a publishing system which
+  extracts information from reStructuredText documents and stores it
+  in a database.  Python knowledge is required to write extractor
+  functions (see `Writing an Extractor`_) and to retrieve the data
+  from the database again.
+
+* The `pickle writer`_ by Martin Blais pickles the document tree to a binary
+  string. Later unpickling will allow you to publish with other Writers.
+
+* The `Texinfo Writer`_, by Jon Waltman converts reStructuredText to
+  Texinfo, the documentation format used by the GNU project and the
+  Emacs text editor.  Texinfo can be used to produce multiple output
+  formats, including HTML, PDF, and Info.
+
+* For `confluence CMS`_ see https://github.com/netresearch/rst2confluence.
+
+* Deploying into wikis might be aided by deploy-rst_.
+
+.. _Pandoc: http://sophos.berkeley.edu/macfarlane/pandoc/
+.. _restxsl: http://www.strangeGizmo.com/products/restxsl/
+.. _DocBook Writer: http://docutils.sf.net/sandbox/oliverr/docbook/
+.. _Nabu: http://furius.ca/nabu/
+.. _Writing an Extractor: http://furius.ca/nabu/doc/nabu-extractor.html
+.. _pickle writer: http://docutils.sf.net/sandbox/blais/pickle_writer/
+.. _Texinfo Writer: http://docutils.sf.net/sandbox/texinfo-writer/README.html
+.. _confluence CMS: http://www.atlassian.com/software/confluence
+.. _deploy-rst: https://github.com/netresearch/deploy-rst
+
+
+Import
+------
+
+Convert other formats to reStructuredText:
+
+* recommonmark_ is a Markdown\ [#markdown]_ (CommonMark_) parser for docutils.
+
+* sxw2rest_, by Trent W. Buck, converts StarOffice XML Writer (SXW)
+  files to reStructuredText.
+
+* xml2rst_, an XSLT stylesheet written by Stefan Merten, converts XML
+  dumps of the document tree (e.g. created with rst2xml.py) back to
+  reStructuredText.
+
+* xhtml2rest_, written by Antonios Christofides, is a simple utility
+  to convert XHTML to reStructuredText.
+
+* DashTable_ by Gustav Klopp converts HTML tables into reStructuredText.
+  Colspan and Rowspan supported!
+
+  .. _DashTable: https://github.com/gustavklopp/DashTable
+
+* Sphinx_ includes a `LaTeX to Rst converter
+  <http://svn.python.org/projects/doctools/converter/>`__ in its source code
+  (trimmed to importing the old Python docs).
+
+* Pandoc_ can read Markdown\ [#markdown]_ and (subsets of) HTML, and LaTeX and export to
+  (amongst others) reStructuredText.
+
+* PySource_, by Tony Ibbs, is an experimental Python source Reader.
+  There is some related code in David Goodger's sandbox
+  (pysource_reader_) and a `Python Source Reader`_ document.
+
+.. [#markdown]
+   `Markdown <http://daringfireball.net/projects/markdown/syntax>`__ is
+   another lightwight markup language.  See also documentation on `Common
+   markup for Markdown and reStructuredText`_.
+
+.. _recommonmark: https://github.com/rtfd/recommonmark
+.. _CommonMark: http://commonmark.org/
+.. _sxw2rest: http://twb.ath.cx/~twb/darcs/sxw2rest/
+.. _xml2rst: http://www.merten-home.de/FreeSoftware/xml2rst/index.html
+.. _xhtml2rest: http://docutils.sf.net/sandbox/wiemann/xhtml2rest/
+.. _PySource: http://docutils.sf.net/sandbox/tibs/pysource/
+.. _pysource_reader: http://docutils.sf.net/sandbox/davidg/pysource_reader/
+.. _Python Source Reader: http://docutils.sf.net/docs/dev/pysource.html
+.. _Common markup for Markdown and reStructuredText:
+   https://gist.github.com/dupuy/1855764
+
+
+Extensions
+----------
+
+Extend the reStructuredText syntax or the features of Docutils.
+More extensions are in the `Docutils Sandbox`_.
+
+* Beni Cherniavsky has written a generic `preprocessing module`_ for
+  roles and/or directives and built preprocessors for TeX math for
+  both LaTeX and HTML output on top of it.
+
+* Beni Cherniavsky maintains a Makefile_ for driving Docutils, hoping
+  to handle everything one might do with Docutils.
+
+* The `ASCII art to SVG converter`_ (aafigure) developed by
+  Chris Liechti can parse ASCII art images, embedded in reST documents and
+  output an image. This would mean that simple illustrations could be
+  embedded as ASCII art in the reST source and still look nice when
+  converted to e.g. HTML
+
+* zot4rst_ by Erik Hetzner is an extension that allows users to write reST
+  documents using citations from a Zotero_ library.
+
+* Quick and easy publishing reStructuredText source files as blog posts
+  on blogger.com is possible with `rst2blogger`_ .
+
+.. _preprocessing module: http://docutils.sf.net/sandbox/cben/rolehack/
+.. _Makefile: http://docutils.sf.net/sandbox/cben/make/
+.. _ASCII art to SVG converter:
+   http://docutils.sf.net/sandbox/cliechti/aafigure/
+.. _zot4rst: http://e6h.org/~egh/hg/zotero-plain
+.. _Zotero: http://www.zotero.org/
+.. _rst2blogger: https://github.com/dhellmann/rst2blogger#readme
+
+
+Related Applications
+--------------------
+
+Applications using docutils/reStructuredText and helper applications.
+
+* For Wikis, please see the `FAQ entry about Wikis`_.
+
+* For Blogs (Weblogs), please see the `FAQ entry about Blogs`_.
+
+* `Project Gutenberg`_ uses a customized version of Docutils with it's own
+  xetex- and nroff-writer and epub generator.
+
+.. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html
+    #are-there-any-wikis-that-use-restructuredtext-syntax
+.. _FAQ entry about Blogs: http://docutils.sf.net/FAQ.html
+    #are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
+.. _Project Gutenberg: http://www.gutenberg.org
+
+
+Tools
+`````
+
+* rstcheck_ Checks syntax of reStructuredText and code blocks nested within
+  it. (Using the Sphinx syntax "code-block" for the "code" directive.)
+
+  .. _rstcheck: https://pypi.python.org/pypi/rstcheck
+
+* restview_ is a viewer for ReStructuredText documents.
+
+  Pass the name of a ReStructuredText document to restview, and it will
+  launch a web server on localhost:random-port and open a web browser. It
+  will also watch for changes in that file and automatically reload and
+  rerender it. This is very convenient for previewing a document while
+  you're editing it.
+
+  .. _restview: http://mg.pov.lt/restview/
+
+
+Development
+```````````
+
+* Sphinx_ extends the ReStructuredText syntax to better support the
+  documentation of Software (and other) *projects* (but other documents
+  can be written with it too).
+
+  Since version 2.6, the `Python documentation`_ is based on
+  reStructuredText and Sphinx.
+
+* Trac_, a project management and bug/issue tracking system, supports
+  `using reStructuredText
+  <http://trac.edgewall.org/wiki/WikiRestructuredText>`__ as an
+  alternative to wiki markup.
+
+* PyLit_ provides a bidirectional text <--> code converter for *literate
+  programming with reStructuredText*.
+
+* If you are developing a Qt app, rst2qhc_ lets you generate the whole help
+  automatically from reStructuredText. That includes keywords, TOC,
+  multiple manuals per project, filters, project file, collection project
+  file, and more.
+
+.. _Python documentation: http://docs.python.org/
+.. _Trac: http://trac.edgewall.org/
+.. _PyLit: http://repo.or.cz/pylit.git
+.. _rst2qhc: http://rst2qhc.googlecode.com
+
+
+CMS Systems
+```````````
+
+* Plone_ and Zope_ both support reStructuredText markup.
+* ZReST_, by Richard Jones, is a "ReStructuredText Document for Zope_"
+  application that is complete and ready to install.
+
+.. _Plone: http://plone.org/
+.. _Zope: http://www.zope.org/
+.. _ZReST: http://docutils.sf.net/sandbox/richard/ZReST/
+
+
+Presentations
+`````````````
+
+* rst2html5_ transform restructuredtext documents to html5 + twitter's
+  bootstrap css, deck.js or reveal.js
+
+* landslide_ generates HTML5 slideshows from markdown, ReST, or textile.
+
+* `native support for S5 <slide-shows.s5.html>`_.
+
+* The `PythonPoint interface`_ by Richard Jones produces PDF
+  presentations using ReportLabs' PythonPoint_.
+
+* rst2beamer_ generates a LaTeX source that uses the `Beamer` document class.
+  Can be converted to PDF slides with pdfLaTeX/XeLaTeX/LuaLaTeX.
+
+* InkSlide_ quick and easy presentations using Inkscape_. InkSlide uses
+  reStructuredText for markup, although it renders only a subset of rst.
+
+* rst2outline_ translates a reStructuredText document to a plain text
+  outline. This can then be transformed to PowerPoint.
+
+* Pandoc_ can also be used to produce slides, as shown in this
+  `Pandoc Slides Demo`_
+
+.. _PythonPoint: http://www.reportlab.org/python_point.html
+.. _PythonPoint interface: http://docutils.sf.net/sandbox/richard/pythonpoint/
+.. _rst2beamer: http://docutils.sf.net/sandbox/rst2beamer/
+.. _Inkscape: http://inkscape.org/
+.. _InkSlide: http://wiki.inkscape.org/wiki/index.php/InkSlide
+.. _rst2html5: https://github.com/marianoguerra/rst2html5
+.. _landslide: https://github.com/adamzap/landslide
+.. _rst2outline: http://docutils.sf.net/sandbox/rst2outline/
+.. _Pandoc Slides Demo:
+   http://johnmacfarlane.net/pandoc/demo/example9/producing-slide-shows-with-pandoc

docs/user/mailing-lists.txt

@@ -0,0 +1,157 @@
+=========================
+ Docutils_ Mailing Lists
+=========================
+
+:Author: Lea Wiemann
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 8111 $
+:Date: $Date: 2017-06-10 22:35:01 +0200 (Sa, 10 Jun 2017) $
+:Copyright: This document has been placed in the public domain.
+
+
+.. Gmane went down 2016 and is only partially restored.
+   http://home.gmane.org/2016/08/29/next-steps-gmane/
+
+.. raw:: html
+
+   <div class="sidebar">
+   <p class="first sidebar-title">Search the list archives</p>
+   <form method="get" action="https://sourceforge.net/p/docutils/mailman/search/">
+   <p style="margin-bottom: 3px;"><input type="text" name="q" style="width: 100%;" /></p>
+   <p>Search in <select name="mail_list">
+       <option value="all">all mailing lists</option>
+       <option value="docutils-users">Docutils-users</option>
+       <option value="docutils-develop">Docutils-develop</option>
+       <option value="docutils-checkins">Docutils-checkins</option>
+       </select></p>
+   <p class="last"><input type="submit" value="Search" /></p>
+   </form>
+   </div>
+
+All discussion about Docutils takes place on mailing lists.
+
+There are four different lists with traffic related to Docutils.
+For an oversight, see https://sourceforge.net/p/docutils/mailman/.
+If unsure, use the **Docutils-users** mailing list:
+
+
+Docutils-users
+--------------
+
+The `Docutils-users mailing list`_ is a place to discuss any issues
+related to the usage of Docutils and reStructuredText.  (Please be
+sure to check the FAQ_ first.)
+
+There are several possibilities to **read and post** messages on the
+mailing lists; use the one you feel most comfortable with.
+
+* Using an `email subscription`__.  This is the traditional way; you
+  will receive all messages sent to the mailing list via email.
+
+  __ `docutils-users mailing list`_
+
+.. * Using Gmane's `web interface`__.  To post a message, click "post" or
+  "followup" in the drop-down menu on the right.  (Gmane also has a
+  complete **archive** of the mailing list; use the search form at the
+  top of this page to search it.)
+
+  __ http://news.gmane.org/gmane.text.docutils.user
+
+* Use a newsreader with Gmane's `NNTP interface`__
+  (gmane.text.docutils.user on news.gmane.org).
+
+  __ nntp://news.gmane.org/gmane.text.docutils.user
+
+* **If you do not wish to subscribe,** you can also just send an email
+  message with your question or comment to
+  Docutils-users@lists.sourceforge.net.
+
+  Note in your message that you are not subscribed (to make sure that you
+  receive copies [CCs] of any replies) or check for answers in the
+  `Docutils-users Archives`_.
+
+The first time you post a message without being subscribed (also when
+posting via Gmane), you will receive an automatic response with the subject
+"Your message to Docutils-users awaits moderator approval"; this is done to
+prevent spam to the mailing lists.  Your message will usually be approved
+within a few hours.  To avoid duplicates, please do not resend your message
+using a different email address.  After your first message has been
+approved, your email address will be added to the whitelist and future
+messages will be posted to the mailing list without moderation.
+
+To see the collection of prior postings to the list, visit the
+`Docutils-users Archives`_.
+
+
+Docutils-develop
+----------------
+
+Discussions about developing and extending Docutils take place on the
+`Docutils-develop mailing list`_.
+
+You can access this list via `email subscription`__ or news__
+(gmane.text.docutils.devel); the posting address is
+Docutils-develop@lists.sourceforge.net.
+
+To see the collection of prior postings to the list, visit the
+`Docutils-develop Archives`__.
+
+__ `Docutils-develop mailing list`_
+__ nntp://news.gmane.org/gmane.text.docutils.devel
+__ http://sourceforge.net/mailarchive/forum.php?forum_name=docutils-develop
+
+Docutils-checkins
+-----------------
+
+All check-ins to the `Subversion repository`_ cause a "check-in email"
+to the `Docutils-checkins list`_.  In order to stay informed about
+current development, developers are advised to monitor this mailing
+list.
+
+This mailing list is for reading only; please direct any discussion
+about the check-ins to Docutils-develop.  (For your convenience, the
+Reply-To header of all check-in emails points to Docutils-develop.)
+
+This mailing list is accessible via `email subscription`__ or
+news__ (gmane.text.docutils.cvs) as well.
+
+If you are using an email subscription and you would prefer to only
+receive check-in messages for changes that affect the main Docutils
+distribution (i.e. ``trunk/docutils/*``), go to the `list options`_
+page and select the "Docutils core" topic.
+
+__ `Docutils-checkins list`_
+__ nntp://news.gmane.org/gmane.text.docutils.cvs
+.. _list options: http://lists.sf.net/lists/options/docutils-checkins
+
+Doc-SIG
+-------
+
+The "Python Documentation Special Interest Group" (`Doc-SIG`_) mailing list
+is occasionally used to discuss the usage of Docutils for Python
+documentation.
+
+This mailing list can be accessed via `email subscription`__ or
+news__ (gmane.comp.python.documentation) as well.  You must be
+subscribed in order to post messages to this mailing list.
+
+__ `Doc-SIG`_
+__ nntp://news.gmane.org/gmane.comp.python.documentation
+
+
+.. _Docutils-users mailing list:
+   http://lists.sourceforge.net/lists/listinfo/docutils-users
+.. _Docutils-users Archives:
+   http://sourceforge.net/mailarchive/forum.php?forum_name=docutils-users
+.. _Docutils-develop mailing list:
+   http://lists.sourceforge.net/lists/listinfo/docutils-develop
+.. _Docutils-develop Archives:
+   http://sourceforge.net/mailarchive/forum.php?forum_name=docutils-develop
+.. _Docutils-checkins list:
+   http://lists.sourceforge.net/lists/listinfo/docutils-checkins
+.. _Doc-SIG:
+   http://mail.python.org/mailman/listinfo/doc-sig
+
+.. _Subversion repository: ../dev/repository.html
+.. _Docutils: http://docutils.sourceforge.net/
+.. _FAQ: ../../FAQ.html

docs/user/manpage.txt

@@ -0,0 +1,163 @@
+==============================
+ manpage writer for Docutils_ 
+==============================
+
+:Author: Engelbert Gruber
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 7302 $
+:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:Copyright: This document has been placed in the public domain.
+
+This tries to explore the posibilities to generate man-pages from
+reStructuredText. Man pages are the way for Unix systems to provide
+help to the user. GNU does this with (TeX)info-pages.
+
+Module information
+''''''''''''''''''
+
+Unix man page belong into a numbered section, 1 is user commands, 8 contains
+administrator commands, the headlines of all manpages are collected into a
+database, queryable with the programm ``apropos``, therefore the headline
+should contain a short text describing into which group this command belongs.
+
+These informations are collected from title, subtitle and the docinfo.
+
+Also man pages have a defined set of sections, that are more or less
+mandatory, see References_.
+
+man pages look like::
+       
+   man(1)     Man Pager Utils     man(1)
+       
+   NAME
+       man - an interface to the on-line reference manuals
+       
+   SYNOPSIS
+       man [-c|-w|-tZT device] [-adhu7V] [-m system[,...]] [-L locale]
+     
+in roff formatting::
+     
+     .TH man 1 "14 May 2001" "2.3.19" "Manual pager utils"
+     .SH NAME
+     man \- an interface to the on-line reference manuals
+     .SH SYNOPSIS
+     .\" The general command line
+     .B man
+     .RB [\| \-c \||\| \-w \||\| \-tZT
+     .IR device \|]
+
+This means we have 
+
+* a title "man" 
+* a subtitle "an interface to the on-line reference manuals"
+* a manual section "1"
+* a manual group "Manual pager utils"
+* a date "14 May 2001"
+* a version "2.3.19"
+
+References
+''''''''''
+
+man pages from section 7, ``man`` and ``man-pages``.
+
+.. [LMHT] Linux Man Page Howto.
+
+Conventions
+'''''''''''
+
+* man pages have a special structure and organization. From the manpage 
+  to *man*::
+
+    The table below shows the section numbers of the manual followed  by  the
+    types of pages they contain.
+
+    1   Executable programs or shell commands
+    2   System calls (functions provided by the kernel)
+    3   Library calls (functions within program libraries)
+    4   Special files (usually found in /dev)
+    5   File formats and conventions eg /etc/passwd
+    6   Games
+    7   Miscellaneous  (including  macro  packages and conven-
+        tions), e.g. man(7), groff(7)
+    8   System administration commands (usually only for root)
+    9   Kernel routines [Non standard]
+
+    A manual page consists of several parts.
+
+    They  may  be  labelled  NAME,  SYNOPSIS,  DESCRIPTION,  OPTIONS,  FILES,
+    SEE ALSO, BUGS, and AUTHOR.
+
+    The  following  conventions apply to the SYNOPSIS section and can be used
+    as a guide in other sections.
+
+    bold text          type exactly as shown.
+    italic text        replace with appropriate argument.
+    [-abc]             any or all arguments within [ ] are optional.
+    -a|-b              options delimited by | cannot be used together.
+    argument ...       argument is repeatable.
+    [expression] ...   entire expression within [ ] is repeatable.
+
+    The command or function illustration is a pattern that should  match  all
+    possible  invocations.   In some cases it is advisable to illustrate sev-
+    eral exclusive invocations as is shown in the SYNOPSIS  section  of  this
+    manual page.
+
+* new lines in general.
+
+  Consecutive blank lines are merged by the viewer but not on printouts.
+  So one has to be cautious. This is most disturbing when printing 
+  postscript.
+
+  .. NOTE::
+
+    1. Roff requests only work when at line start.
+    2. But consecutive blank lines are merged by the viewer but not on 
+       printouts.
+
+    So try the rule start new lines in ``visit_``-functions, but only if 
+    necessary. E.g. ``field-names`` are already on a new line because of 
+    docutils structure.
+
+* Indentation, left margin:
+
+  - The writer includes two macros ``.INDENT`` and ``.UNINDENT`` that
+    keep track of the indentation in roff-code, for line-blocks python
+    keeps track of it. WHAT should be the preferred way ?
+
+    But standard macros like ``.PP`` might reset it.
+
+  - Why do ``.RE`` and ``.RS`` not work?
+
+  .. Note::
+     Current indent is in register ``.i``.
+
+* [LMHT]_ Filenames are always in italics, except in the SYNOPSIS section,
+  use::
+
+    .I /usr/include/stdio.h
+
+  and::
+
+    .B #include <stdio.h>
+
+* Tables are possible, via the external processor tbl, although one should
+  avoid them.
+
+Open issues
+'''''''''''
+
+* How to typeset command/manpage names in text.
+* How to write long syntax lines.
+* Line ends around email or web addresses in texts.
+  How to distinguish something is inline or not ?
+  
+* Images and equations are discouraged.
+* Lists in admonitions are not intended.
+* Encoding declaration ``'\" t -*- coding: ISO-8859-1 -*-``
+  in first line.
+
+  BUT if UTF-8 is declared tables are no longer processed.
+
+* Input and output encoding are problematic at least.
+ 
+.. _Docutils: http://docutils.sourceforge.net/

docs/user/rst/cheatsheet.txt

@@ -0,0 +1,132 @@
+=====================================================
+ The reStructuredText_ Cheat Sheet: Syntax Reminders
+=====================================================
+:Info: See <http://docutils.sf.net/rst.html> for introductory docs.
+:Author: David Goodger <goodger@python.org>
+:Date: $Date: 2013-02-20 02:10:53 +0100 (Mi, 20 Feb 2013) $
+:Revision: $Revision: 7612 $
+:Description: This is a "docinfo block", or bibliographic field list
+
+.. NOTE:: If you are reading this as HTML, please read
+   `<cheatsheet.txt>`_ instead to see the input syntax examples!
+
+Section Structure
+=================
+Section titles are underlined or overlined & underlined.
+
+Body Elements
+=============
+Grid table:
+
++--------------------------------+-----------------------------------+
+| Paragraphs are flush-left,     | Literal block, preceded by "::":: |
+| separated by blank lines.      |                                   |
+|                                |     Indented                      |
+|     Block quotes are indented. |                                   |
++--------------------------------+ or::                              |
+| >>> print 'Doctest block'      |                                   |
+| Doctest block                  | > Quoted                          |
++--------------------------------+-----------------------------------+
+| | Line blocks preserve line breaks & indents. [new in 0.3.6]       |
+| |     Useful for addresses, verse, and adornment-free lists; long  |
+|       lines can be wrapped with continuation lines.                |
++--------------------------------------------------------------------+
+
+Simple tables:
+
+================  ============================================================
+List Type         Examples (syntax in the `text source <cheatsheet.txt>`_)
+================  ============================================================
+Bullet list       * items begin with "-", "+", or "*"
+Enumerated list   1. items use any variation of "1.", "A)", and "(i)"
+                  #. also auto-enumerated
+Definition list   Term is flush-left : optional classifier
+                      Definition is indented, no blank line between
+Field list        :field name: field body
+Option list       -o  at least 2 spaces between option & description
+================  ============================================================
+
+================  ============================================================
+Explicit Markup   Examples (visible in the `text source`_)
+================  ============================================================
+Footnote          .. [1] Manually numbered or [#] auto-numbered
+                     (even [#labelled]) or [*] auto-symbol
+Citation          .. [CIT2002] A citation.
+Hyperlink Target  .. _reStructuredText: http://docutils.sf.net/rst.html
+                  .. _indirect target: reStructuredText_
+                  .. _internal target:
+Anonymous Target  __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html
+Directive ("::")  .. image:: images/biohazard.png
+Substitution Def  .. |substitution| replace:: like an inline directive
+Comment           .. is anything else
+Empty Comment     (".." on a line by itself, with blank lines before & after,
+                  used to separate indentation contexts)
+================  ============================================================
+
+Inline Markup
+=============
+*emphasis*; **strong emphasis**; `interpreted text`; `interpreted text
+with role`:emphasis:; ``inline literal text``; standalone hyperlink,
+http://docutils.sourceforge.net; named reference, reStructuredText_;
+`anonymous reference`__; footnote reference, [1]_; citation reference,
+[CIT2002]_; |substitution|; _`inline internal target`.
+
+Directive Quick Reference
+=========================
+See <http://docutils.sf.net/docs/ref/rst/directives.html> for full info.
+
+================  ============================================================
+Directive Name    Description (Docutils version added to, in [brackets])
+================  ============================================================
+attention         Specific admonition; also "caution", "danger",
+                  "error", "hint", "important", "note", "tip", "warning"
+admonition        Generic titled admonition: ``.. admonition:: By The Way``
+image             ``.. image:: picture.png``; many options possible
+figure            Like "image", but with optional caption and legend
+topic             ``.. topic:: Title``; like a mini section
+sidebar           ``.. sidebar:: Title``; like a mini parallel document
+parsed-literal    A literal block with parsed inline markup
+rubric            ``.. rubric:: Informal Heading``
+epigraph          Block quote with class="epigraph"
+highlights        Block quote with class="highlights"
+pull-quote        Block quote with class="pull-quote"
+compound          Compound paragraphs [0.3.6]
+container         Generic block-level container element [0.3.10]
+table             Create a titled table [0.3.1]
+list-table        Create a table from a uniform two-level bullet list [0.3.8]
+csv-table         Create a table from CSV data [0.3.4]
+contents          Generate a table of contents
+sectnum           Automatically number sections, subsections, etc.
+header, footer    Create document decorations [0.3.8]
+target-notes      Create an explicit footnote for each external target
+math              Mathematical notation (input in LaTeX format)
+meta              HTML-specific metadata
+include           Read an external reST file as if it were inline
+raw               Non-reST data passed untouched to the Writer
+replace           Replacement text for substitution definitions
+unicode           Unicode character code conversion for substitution defs
+date              Generates today's date; for substitution defs
+class             Set a "class" attribute on the next element
+role              Create a custom interpreted text role [0.3.2]
+default-role      Set the default interpreted text role [0.3.10]
+title             Set the metadata document title [0.3.10]
+================  ============================================================
+
+Interpreted Text Role Quick Reference
+=====================================
+See <http://docutils.sf.net/docs/ref/rst/roles.html> for full info.
+
+================  ============================================================
+Role Name         Description
+================  ============================================================
+emphasis          Equivalent to *emphasis*
+literal           Equivalent to ``literal`` but processes backslash escapes
+math              Mathematical notation (input in LaTeX format)
+PEP               Reference to a numbered Python Enhancement Proposal
+RFC               Reference to a numbered Internet Request For Comments
+raw               For non-reST data; cannot be used directly (see docs) [0.3.6]
+strong            Equivalent to **strong**
+sub               Subscript
+sup               Superscript
+title             Title reference (book, etc.); standard default role
+================  ============================================================

docs/user/rst/demo.txt

@@ -0,0 +1,552 @@
+.. This is a comment. Note how any initial comments are moved by
+   transforms to after the document title, subtitle, and docinfo.
+
+================================
+ reStructuredText Demonstration
+================================
+
+.. Above is the document title, and below is the subtitle.
+   They are transformed from section titles after parsing.
+
+--------------------------------
+ Examples of Syntax Constructs
+--------------------------------
+
+.. bibliographic fields (which also require a transform):
+
+:Author: David Goodger
+:Address: 123 Example Street
+          Example, EX  Canada
+          A1B 2C3
+:Contact: docutils-develop@lists.sourceforge.net
+:Authors: Me; Myself; I
+:organization: humankind
+:date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $
+:status: This is a "work in progress"
+:revision: $Revision: 7302 $
+:version: 1
+:copyright: This document has been placed in the public domain. You
+            may do with it as you wish. You may copy, modify,
+            redistribute, reattribute, sell, buy, rent, lease,
+            destroy, or improve it, quote it at length, excerpt,
+            incorporate, collate, fold, staple, or mutilate it, or do
+            anything else to it that your or anyone else's heart
+            desires.
+:field name: This is a generic bibliographic field.
+:field name 2:
+    Generic bibliographic fields may contain multiple body elements.
+
+    Like this.
+
+:Dedication:
+
+    For Docutils users & co-developers.
+
+:abstract:
+
+    This document is a demonstration of the reStructuredText markup
+    language, containing examples of all basic reStructuredText
+    constructs and many advanced constructs.
+
+.. meta::
+   :keywords: reStructuredText, demonstration, demo, parser
+   :description lang=en: A demonstration of the reStructuredText
+       markup language, containing examples of all basic
+       constructs and many advanced constructs.
+
+.. contents:: Table of Contents
+.. section-numbering::
+
+
+Structural Elements
+===================
+
+Section Title
+-------------
+
+That's it, the text just above this line.
+
+Transitions
+-----------
+
+Here's a transition:
+
+---------
+
+It divides the section.
+
+Body Elements
+=============
+
+Paragraphs
+----------
+
+A paragraph.
+
+Inline Markup
+`````````````
+
+Paragraphs contain text and may contain inline markup: *emphasis*,
+**strong emphasis**, ``inline literals``, standalone hyperlinks
+(http://www.python.org), external hyperlinks (Python_), internal
+cross-references (example_), external hyperlinks with embedded URIs
+(`Python web site <http://www.python.org>`__), footnote references
+(manually numbered [1]_, anonymous auto-numbered [#]_, labeled
+auto-numbered [#label]_, or symbolic [*]_), citation references
+([CIT2002]_), substitution references (|example|), and _`inline
+hyperlink targets` (see Targets_ below for a reference back to here).
+Character-level inline markup is also possible (although exceedingly
+ugly!) in *re*\ ``Structured``\ *Text*.  Problems are indicated by
+|problematic| text (generated by processing errors; this one is
+intentional).
+
+The default role for interpreted text is `Title Reference`.  Here are
+some explicit interpreted text roles: a PEP reference (:PEP:`287`); an
+RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`;
+and explicit roles for :emphasis:`standard` :strong:`inline`
+:literal:`markup`.
+
+.. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
+
+Let's test wrapping and whitespace significance in inline literals:
+``This is an example of --inline-literal --text, --including some--
+strangely--hyphenated-words.  Adjust-the-width-of-your-browser-window
+to see how the text is wrapped.  -- ---- --------  Now note    the
+spacing    between the    words of    this sentence    (words
+should    be grouped    in pairs).``
+
+If the ``--pep-references`` option was supplied, there should be a
+live link to PEP 258 here.
+
+Bullet Lists
+------------
+
+- A bullet list
+
+  + Nested bullet list.
+  + Nested item 2.
+
+- Item 2.
+
+  Paragraph 2 of item 2.
+
+  * Nested bullet list.
+  * Nested item 2.
+
+    - Third level.
+    - Item 2.
+
+  * Nested item 3.
+
+Enumerated Lists
+----------------
+
+1. Arabic numerals.
+
+   a) lower alpha)
+
+      (i) (lower roman)
+
+          A. upper alpha.
+
+             I) upper roman)
+
+2. Lists that don't start at 1:
+
+   3. Three
+
+   4. Four
+
+   C. C
+
+   D. D
+
+   iii. iii
+
+   iv. iv
+
+#. List items may also be auto-enumerated.
+
+Definition Lists
+----------------
+
+Term
+    Definition
+Term : classifier
+    Definition paragraph 1.
+
+    Definition paragraph 2.
+Term
+    Definition
+
+Field Lists
+-----------
+
+:what: Field lists map field names to field bodies, like database
+       records.  They are often part of an extension syntax.  They are
+       an unambiguous variant of RFC 2822 fields.
+
+:how arg1 arg2:
+
+    The field marker is a colon, the field name, and a colon.
+
+    The field body may contain one or more body elements, indented
+    relative to the field marker.
+
+Option Lists
+------------
+
+For listing command-line options:
+
+-a            command-line option "a"
+-b file       options can have arguments
+              and long descriptions
+--long        options can be long also
+--input=file  long options can also have
+              arguments
+
+--very-long-option
+              The description can also start on the next line.
+
+              The description may contain multiple body elements,
+              regardless of where it starts.
+
+-x, -y, -z    Multiple options are an "option group".
+-v, --verbose  Commonly-seen: short & long options.
+-1 file, --one=file, --two file
+              Multiple options with arguments.
+/V            DOS/VMS-style options too
+
+There must be at least two spaces between the option and the
+description.
+
+Literal Blocks
+--------------
+
+Literal blocks are indicated with a double-colon ("::") at the end of
+the preceding paragraph (over there ``-->``).  They can be indented::
+
+    if literal_block:
+        text = 'is left as-is'
+        spaces_and_linebreaks = 'are preserved'
+        markup_processing = None
+
+Or they can be quoted without indentation::
+
+>> Great idea!
+>
+> Why didn't I think of that?
+
+Line Blocks
+-----------
+
+| This is a line block.  It ends with a blank line.
+|     Each new line begins with a vertical bar ("|").
+|     Line breaks and initial indents are preserved.
+| Continuation lines are wrapped portions of long lines;
+  they begin with a space in place of the vertical bar.
+|     The left edge of a continuation line need not be aligned with
+  the left edge of the text above it.
+
+| This is a second line block.
+|
+| Blank lines are permitted internally, but they must begin with a "|".
+
+Take it away, Eric the Orchestra Leader!
+
+    | A one, two, a one two three four
+    |
+    | Half a bee, philosophically,
+    |     must, *ipso facto*, half not be.
+    | But half the bee has got to be,
+    |     *vis a vis* its entity.  D'you see?
+    |
+    | But can a bee be said to be
+    |     or not to be an entire bee,
+    |         when half the bee is not a bee,
+    |             due to some ancient injury?
+    |
+    | Singing...
+
+Block Quotes
+------------
+
+Block quotes consist of indented body elements:
+
+    My theory by A. Elk.  Brackets Miss, brackets.  This theory goes
+    as follows and begins now.  All brontosauruses are thin at one
+    end, much much thicker in the middle and then thin again at the
+    far end.  That is my theory, it is mine, and belongs to me and I
+    own it, and what it is too.
+
+    -- Anne Elk (Miss)
+
+Doctest Blocks
+--------------
+
+>>> print 'Python-specific usage examples; begun with ">>>"'
+Python-specific usage examples; begun with ">>>"
+>>> print '(cut and pasted from interactive Python sessions)'
+(cut and pasted from interactive Python sessions)
+
+Tables
+------
+
+Here's a grid table followed by a simple table:
+
++------------------------+------------+----------+----------+
+| Header row, column 1   | Header 2   | Header 3 | Header 4 |
+| (header rows optional) |            |          |          |
++========================+============+==========+==========+
+| body row 1, column 1   | column 2   | column 3 | column 4 |
++------------------------+------------+----------+----------+
+| body row 2             | Cells may span columns.          |
++------------------------+------------+---------------------+
+| body row 3             | Cells may  | - Table cells       |
++------------------------+ span rows. | - contain           |
+| body row 4             |            | - body elements.    |
++------------------------+------------+----------+----------+
+| body row 5             | Cells may also be     |          |
+|                        | empty: ``-->``        |          |
++------------------------+-----------------------+----------+
+
+=====  =====  ======
+   Inputs     Output
+------------  ------
+  A      B    A or B
+=====  =====  ======
+False  False  False
+True   False  True
+False  True   True
+True   True   True
+=====  =====  ======
+
+Footnotes
+---------
+
+.. [1] A footnote contains body elements, consistently indented by at
+   least 3 spaces.
+
+   This is the footnote's second paragraph.
+
+.. [#label] Footnotes may be numbered, either manually (as in [1]_) or
+   automatically using a "#"-prefixed label.  This footnote has a
+   label so it can be referred to from multiple places, both as a
+   footnote reference ([#label]_) and as a hyperlink reference
+   (label_).
+
+.. [#] This footnote is numbered automatically and anonymously using a
+   label of "#" only.
+
+.. [*] Footnotes may also use symbols, specified with a "*" label.
+   Here's a reference to the next footnote: [*]_.
+
+.. [*] This footnote shows the next symbol in the sequence.
+
+.. [4] Here's an unreferenced footnote, with a reference to a
+   nonexistent footnote: [5]_.
+
+Citations
+---------
+
+.. [CIT2002] Citations are text-labeled footnotes. They may be
+   rendered separately and differently from footnotes.
+
+Here's a reference to the above, [CIT2002]_, and a [nonexistent]_
+citation.
+
+Targets
+-------
+
+.. _example:
+
+This paragraph is pointed to by the explicit "example" target. A
+reference can be found under `Inline Markup`_, above. `Inline
+hyperlink targets`_ are also possible.
+
+Section headers are implicit targets, referred to by name. See
+Targets_, which is a subsection of `Body Elements`_.
+
+Explicit external targets are interpolated into references such as
+"Python_".
+
+.. _Python: http://www.python.org/
+
+Targets may be indirect and anonymous.  Thus `this phrase`__ may also
+refer to the Targets_ section.
+
+__ Targets_
+
+Here's a `hyperlink reference without a target`_, which generates an
+error.
+
+Duplicate Target Names
+``````````````````````
+
+Duplicate names in section headers or other implicit targets will
+generate "info" (level-1) system messages.  Duplicate names in
+explicit targets will generate "warning" (level-2) system messages.
+
+Duplicate Target Names
+``````````````````````
+
+Since there are two "Duplicate Target Names" section headers, we
+cannot uniquely refer to either of them by name.  If we try to (like
+this: `Duplicate Target Names`_), an error is generated.
+
+Directives
+----------
+
+.. contents:: :local:
+
+These are just a sample of the many reStructuredText Directives.  For
+others, please see
+http://docutils.sourceforge.net/docs/ref/rst/directives.html.
+
+Document Parts
+``````````````
+
+An example of the "contents" directive can be seen above this section
+(a local, untitled table of contents_) and at the beginning of the
+document (a document-wide `table of contents`_).
+
+Images
+``````
+
+An image directive (also clickable -- a hyperlink reference):
+
+.. image:: images/title.png
+   :target: directives_
+
+A figure directive:
+
+.. figure:: images/title.png
+   :alt: reStructuredText, the markup syntax
+
+   A figure is an image with a caption and/or a legend:
+
+   +------------+-----------------------------------------------+
+   | re         | Revised, revisited, based on 're' module.     |
+   +------------+-----------------------------------------------+
+   | Structured | Structure-enhanced text, structuredtext.      |
+   +------------+-----------------------------------------------+
+   | Text       | Well it is, isn't it?                         |
+   +------------+-----------------------------------------------+
+
+   This paragraph is also part of the legend.
+
+Admonitions
+```````````
+
+.. Attention:: Directives at large.
+
+.. Caution::
+
+   Don't take any wooden nickels.
+
+.. DANGER:: Mad scientist at work!
+
+.. Error:: Does not compute.
+
+.. Hint:: It's bigger than a bread box.
+
+.. Important::
+   - Wash behind your ears.
+   - Clean up your room.
+   - Call your mother.
+   - Back up your data.
+
+.. Note:: This is a note.
+
+.. Tip:: 15% if the service is good.
+
+.. WARNING:: Strong prose may provoke extreme mental exertion.
+   Reader discretion is strongly advised.
+
+.. admonition:: And, by the way...
+
+   You can make up your own admonition too.
+
+Topics, Sidebars, and Rubrics
+`````````````````````````````
+
+.. sidebar:: Sidebar Title
+   :subtitle: Optional Subtitle
+
+   This is a sidebar.  It is for text outside the flow of the main
+   text.  
+
+   .. rubric:: This is a rubric inside a sidebar
+
+   Sidebars often appears beside the main text with a border and
+   background color.
+
+.. topic:: Topic Title
+
+   This is a topic.
+
+.. rubric:: This is a rubric
+
+Target Footnotes
+````````````````
+
+.. target-notes::
+
+Replacement Text
+````````````````
+
+I recommend you try |Python|_.
+
+.. |Python| replace:: Python, *the* best language around
+
+Compound Paragraph
+``````````````````
+
+.. compound::
+
+   This paragraph contains a literal block::
+
+       Connecting... OK
+       Transmitting data... OK
+       Disconnecting... OK
+      
+   and thus consists of a simple paragraph, a literal block, and
+   another simple paragraph.  Nonetheless it is semantically *one*
+   paragraph.
+
+This construct is called a *compound paragraph* and can be produced
+with the "compound" directive.
+
+Substitution Definitions
+------------------------
+
+An inline image (|example|) example:
+
+.. |EXAMPLE| image:: images/biohazard.png
+
+(Substitution definitions are not visible in the HTML source.)
+
+Comments
+--------
+
+Here's one:
+
+.. Comments begin with two dots and a space. Anything may
+   follow, except for the syntax of footnotes, hyperlink
+   targets, directives, or substitution definitions.
+
+   Double-dashes -- "--" -- must be escaped somehow in HTML output.
+
+(View the HTML source to see the comment.)
+
+Error Handling
+==============
+
+Any errors caught during processing will generate system messages.
+
+|*** Expect 6 errors (including this one). ***|
+
+There should be six messages in the following, auto-generated
+section, "Docutils System Messages":
+
+.. section should be added by Docutils automatically

docs/user/rst/images/biohazard-bitmap-scaling.svg

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   version="1.1"
+   viewBox="0 0 16 16" 
+   width="100%" 
+   height="100%"
+   id="svg2">
+  <metadata
+     id="metadata8">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs6" />
+  <image
+     xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABHNCSVQICAgIfAhkiAAAAIRJREFU
+OI2lUkEOwCAIa83+/+XusGCQIWOxF1GhUICSEEFSkvj1BgCjEwwAkkjylW0hyByyBP5+dR2zqrYE
+ux5kvq8e/AVtCh39HlbhqIIlcafdx+jxFezs2BY3fDkxO0lVezElnGA2MWrzmxftkiASxZIjjiWk
+BNlYd6NeJCyzLVbZ/92om331AFqcoAAAAABJRU5ErkJggg==
+"
+     x="4.9541664"
+     y="-5.2426963"
+     width="11.322034"
+     height="9.3559322"
+     transform="matrix(0.77695327,0.62955828,-0.62955828,0.77695327,0,0)"
+     id="image10" />
+  <text
+     x="0.40677962"
+     y="15.186441"
+     id="text2987"
+     xml:space="preserve"
+     style="font-size:4px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans;-inkscape-font-specification:DejaVu Sans"><tspan
+       x="0.40677962"
+       y="15.186441"
+       id="tspan2989">turned</tspan></text>
+</svg>

docs/user/rst/images/biohazard-bitmap.svg

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   version="1.1"
+   width="16"
+   height="16"
+   id="svg2">
+  <metadata
+     id="metadata8">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs6" />
+  <image
+     xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABHNCSVQICAgIfAhkiAAAAIRJREFU
+OI2lUkEOwCAIa83+/+XusGCQIWOxF1GhUICSEEFSkvj1BgCjEwwAkkjylW0hyByyBP5+dR2zqrYE
+ux5kvq8e/AVtCh39HlbhqIIlcafdx+jxFezs2BY3fDkxO0lVezElnGA2MWrzmxftkiASxZIjjiWk
+BNlYd6NeJCyzLVbZ/92om331AFqcoAAAAABJRU5ErkJggg==
+"
+     x="4.9541664"
+     y="-5.2426963"
+     width="11.322034"
+     height="9.3559322"
+     transform="matrix(0.77695327,0.62955828,-0.62955828,0.77695327,0,0)"
+     id="image10" />
+  <text
+     x="0.40677962"
+     y="15.186441"
+     id="text2987"
+     xml:space="preserve"
+     style="font-size:4px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:DejaVu Sans;-inkscape-font-specification:DejaVu Sans"><tspan
+       x="0.40677962"
+       y="15.186441"
+       id="tspan2989">turned</tspan></text>
+</svg>

docs/user/rst/images/title-scaling.svg

@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   version="1.1"
+   viewBox="0 0 280.82999 27.34" 
+   width="100%" 
+   height="100%"
+   id="svg2"
+   inkscape:version="0.48.5 r10040"
+   sodipodi:docname="title.svg">
+  <sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="1000"
+     inkscape:window-height="680"
+     id="namedview10"
+     showgrid="false"
+     inkscape:zoom="1.573906"
+     inkscape:cx="58.770981"
+     inkscape:cy="13.67"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="0"
+     inkscape:current-layer="svg2" />
+  <metadata
+     id="metadata8">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs6" />
+  <text
+     x="1.1959002"
+     y="24.185671"
+     transform="scale(0.95603363,1.0459883)"
+     id="text2818"
+     xml:space="preserve"
+     style="font-size:34.41720963px;font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:TeXGyrePagella;-inkscape-font-specification:TeXGyrePagella Italic"
+     sodipodi:linespacing="100%"><tspan
+       x="1.1959002"
+       y="24.185671"
+       id="tspan2820"><tspan
+         id="tspan2985"
+         style="font-family:Times New Roman;-inkscape-font-specification:Times New Roman">re</tspan><tspan
+         id="tspan2822"
+         style="font-size:34.41720963px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;font-family:Courier New;-inkscape-font-specification:Courier New">Structured</tspan><tspan
+         id="tspan2989"
+         style="font-family:Times New Roman;-inkscape-font-specification:Times New Roman">Text</tspan></tspan></text>
+</svg>

docs/user/rst/images/title.svg

@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   version="1.1"
+   width="280.82999"
+   height="27.34"
+   id="svg2"
+   inkscape:version="0.48.5 r10040"
+   sodipodi:docname="title.svg">
+  <sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="1000"
+     inkscape:window-height="680"
+     id="namedview10"
+     showgrid="false"
+     inkscape:zoom="1.573906"
+     inkscape:cx="58.770981"
+     inkscape:cy="13.67"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="0"
+     inkscape:current-layer="svg2" />
+  <metadata
+     id="metadata8">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs6" />
+  <text
+     x="1.1959002"
+     y="24.185671"
+     transform="scale(0.95603363,1.0459883)"
+     id="text2818"
+     xml:space="preserve"
+     style="font-size:34.41720963px;font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:TeXGyrePagella;-inkscape-font-specification:TeXGyrePagella Italic"
+     sodipodi:linespacing="100%"><tspan
+       x="1.1959002"
+       y="24.185671"
+       id="tspan2820"><tspan
+         id="tspan2985"
+         style="font-family:Times New Roman;-inkscape-font-specification:Times New Roman">re</tspan><tspan
+         id="tspan2822"
+         style="font-size:34.41720963px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;font-family:Courier New;-inkscape-font-specification:Courier New">Structured</tspan><tspan
+         id="tspan2989"
+         style="font-family:Times New Roman;-inkscape-font-specification:Times New Roman">Text</tspan></tspan></text>
+</svg>

docs/user/rst/quickstart.txt

@@ -0,0 +1,404 @@
+A ReStructuredText Primer
+=========================
+
+:Author: Richard Jones
+:Version: $Revision: 5801 $
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+
+The text below contains links that look like "(quickref__)".  These
+are relative links that point to the `Quick reStructuredText`_ user
+reference.  If these links don't work, please refer to the `master
+quick reference`_ document.
+
+__
+.. _Quick reStructuredText: quickref.html
+.. _master quick reference:
+   http://docutils.sourceforge.net/docs/user/rst/quickref.html
+
+.. Note:: This document is an informal introduction to
+   reStructuredText.  The `What Next?`_ section below has links to
+   further resources, including a formal reference.
+
+
+Structure
+---------
+
+From the outset, let me say that "Structured Text" is probably a bit
+of a misnomer.  It's more like "Relaxed Text" that uses certain
+consistent patterns.  These patterns are interpreted by a HTML
+converter to produce "Very Structured Text" that can be used by a web
+browser.
+
+The most basic pattern recognised is a **paragraph** (quickref__).
+That's a chunk of text that is separated by blank lines (one is
+enough).  Paragraphs must have the same indentation -- that is, line
+up at their left edge.  Paragraphs that start indented will result in
+indented quote paragraphs. For example::
+
+  This is a paragraph.  It's quite
+  short.
+
+     This paragraph will result in an indented block of
+     text, typically used for quoting other text.
+
+  This is another one.
+
+Results in:
+
+  This is a paragraph.  It's quite
+  short.
+
+     This paragraph will result in an indented block of
+     text, typically used for quoting other text.
+
+  This is another one.
+
+__ quickref.html#paragraphs
+
+
+Text styles
+-----------
+
+(quickref__)
+
+__ quickref.html#inline-markup
+
+Inside paragraphs and other bodies of text, you may additionally mark
+text for *italics* with "``*italics*``" or **bold** with
+"``**bold**``".  This is called "inline markup".
+
+If you want something to appear as a fixed-space literal, use
+"````double back-quotes````".  Note that no further fiddling is done
+inside the double back-quotes -- so asterisks "``*``" etc. are left
+alone.
+
+If you find that you want to use one of the "special" characters in
+text, it will generally be OK -- reStructuredText is pretty smart.
+For example, this lone asterisk * is handled just fine, as is the
+asterisk in this equation: 5*6=30.  If you actually
+want text \*surrounded by asterisks* to **not** be italicised, then
+you need to indicate that the asterisk is not special.  You do this by
+placing a backslash just before it, like so "``\*``" (quickref__), or
+by enclosing it in double back-quotes (inline literals), like this::
+
+    ``*``
+
+__ quickref.html#escaping
+
+.. Tip:: Think of inline markup as a form of (parentheses) and use it
+   the same way: immediately before and after the text being marked
+   up.  Inline markup by itself (surrounded by whitespace) or in the
+   middle of a word won't be recognized.  See the `markup spec`__ for
+   full details.
+
+__ ../../ref/rst/restructuredtext.html#inline-markup
+
+
+Lists
+-----
+
+Lists of items come in three main flavours: **enumerated**,
+**bulleted** and **definitions**.  In all list cases, you may have as
+many paragraphs, sublists, etc. as you want, as long as the left-hand
+side of the paragraph or whatever aligns with the first line of text
+in the list item.
+
+Lists must always start a new paragraph -- that is, they must appear
+after a blank line.
+
+**enumerated** lists (numbers, letters or roman numerals; quickref__)
+  __ quickref.html#enumerated-lists
+
+  Start a line off with a number or letter followed by a period ".",
+  right bracket ")" or surrounded by brackets "( )" -- whatever you're
+  comfortable with.  All of the following forms are recognised::
+
+    1. numbers
+
+    A. upper-case letters
+       and it goes over many lines
+
+       with two paragraphs and all!
+
+    a. lower-case letters
+
+       3. with a sub-list starting at a different number
+       4. make sure the numbers are in the correct sequence though!
+
+    I. upper-case roman numerals
+
+    i. lower-case roman numerals
+
+    (1) numbers again
+
+    1) and again
+
+  Results in (note: the different enumerated list styles are not
+  always supported by every web browser, so you may not get the full
+  effect here):
+
+  1. numbers
+
+  A. upper-case letters
+     and it goes over many lines
+
+     with two paragraphs and all!
+
+  a. lower-case letters
+
+     3. with a sub-list starting at a different number
+     4. make sure the numbers are in the correct sequence though!
+
+  I. upper-case roman numerals
+
+  i. lower-case roman numerals
+
+  (1) numbers again
+
+  1) and again
+
+**bulleted** lists (quickref__)
+  __ quickref.html#bullet-lists
+
+  Just like enumerated lists, start the line off with a bullet point
+  character - either "-", "+" or "*"::
+
+    * a bullet point using "*"
+
+      - a sub-list using "-"
+
+        + yet another sub-list
+
+      - another item
+
+  Results in:
+
+  * a bullet point using "*"
+
+    - a sub-list using "-"
+
+      + yet another sub-list
+
+    - another item
+
+**definition** lists (quickref__)
+  __ quickref.html#definition-lists
+
+  Unlike the other two, the definition lists consist of a term, and
+  the definition of that term.  The format of a definition list is::
+
+    what
+      Definition lists associate a term with a definition.
+
+    *how*
+      The term is a one-line phrase, and the definition is one or more
+      paragraphs or body elements, indented relative to the term.
+      Blank lines are not allowed between term and definition.
+
+  Results in:
+
+  what
+    Definition lists associate a term with a definition.
+
+  *how*
+    The term is a one-line phrase, and the definition is one or more
+    paragraphs or body elements, indented relative to the term.
+    Blank lines are not allowed between term and definition.
+
+
+Preformatting (code samples)
+----------------------------
+(quickref__)
+
+__ quickref.html#literal-blocks
+
+To just include a chunk of preformatted, never-to-be-fiddled-with
+text, finish the prior paragraph with "``::``".  The preformatted
+block is finished when the text falls back to the same indentation
+level as a paragraph prior to the preformatted block.  For example::
+
+  An example::
+
+      Whitespace, newlines, blank lines, and all kinds of markup
+        (like *this* or \this) is preserved by literal blocks.
+    Lookie here, I've dropped an indentation level
+    (but not far enough)
+
+  no more example
+
+Results in:
+
+  An example::
+
+      Whitespace, newlines, blank lines, and all kinds of markup
+        (like *this* or \this) is preserved by literal blocks.
+    Lookie here, I've dropped an indentation level
+    (but not far enough)
+
+  no more example
+
+Note that if a paragraph consists only of "``::``", then it's removed
+from the output::
+
+  ::
+
+      This is preformatted text, and the
+      last "::" paragraph is removed
+
+Results in:
+
+::
+
+    This is preformatted text, and the
+    last "::" paragraph is removed
+
+
+Sections
+--------
+
+(quickref__)
+
+__ quickref.html#section-structure
+
+To break longer text up into sections, you use **section headers**.
+These are a single line of text (one or more words) with adornment: an
+underline alone, or an underline and an overline together, in dashes
+"``-----``", equals "``======``", tildes "``~~~~~~``" or any of the
+non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you
+feel comfortable with.  An underline-only adornment is distinct from
+an overline-and-underline adornment using the same character.  The
+underline/overline must be at least as long as the title text.  Be
+consistent, since all sections marked with the same adornment style
+are deemed to be at the same level::
+
+  Chapter 1 Title
+  ===============
+
+  Section 1.1 Title
+  -----------------
+
+  Subsection 1.1.1 Title
+  ~~~~~~~~~~~~~~~~~~~~~~
+
+  Section 1.2 Title
+  -----------------
+
+  Chapter 2 Title
+  ===============
+
+This results in the following structure, illustrated by simplified
+pseudo-XML::
+
+    <section>
+        <title>
+            Chapter 1 Title
+        <section>
+            <title>
+                Section 1.1 Title
+            <section>
+                <title>
+                    Subsection 1.1.1 Title
+        <section>
+            <title>
+                Section 1.2 Title
+    <section>
+        <title>
+            Chapter 2 Title
+
+(Pseudo-XML uses indentation for nesting and has no end-tags.  It's
+not possible to show actual processed output, as in the other
+examples, because sections cannot exist inside block quotes.  For a
+concrete example, compare the section structure of this document's
+source text and processed output.)
+
+Note that section headers are available as link targets, just using
+their name.  To link to the Lists_ heading, I write "``Lists_``".  If
+the heading has a space in it like `text styles`_, we need to quote
+the heading "```text styles`_``".
+
+
+Document Title / Subtitle
+`````````````````````````
+
+The title of the whole document is distinct from section titles and
+may be formatted somewhat differently (e.g. the HTML writer by default
+shows it as a centered heading).
+
+To indicate the document title in reStructuredText, use a unique adornment
+style at the beginning of the document.  To indicate the document subtitle,
+use another unique adornment style immediately after the document title.  For
+example::
+
+    ================
+     Document Title
+    ================
+    ----------
+     Subtitle
+    ----------
+
+    Section Title
+    =============
+
+    ...
+
+Note that "Document Title" and "Section Title" above both use equals
+signs, but are distict and unrelated styles.  The text of
+overline-and-underlined titles (but not underlined-only) may be inset
+for aesthetics.
+
+
+Images
+------
+
+(quickref__)
+
+__ quickref.html#directives
+
+To include an image in your document, you use the the ``image`` directive__.
+For example::
+
+  .. image:: images/biohazard.png
+
+results in:
+
+.. image:: images/biohazard.png
+
+The ``images/biohazard.png`` part indicates the filename of the image
+you wish to appear in the document. There's no restriction placed on
+the image (format, size etc).  If the image is to appear in HTML and
+you wish to supply additional information, you may::
+
+  .. image:: images/biohazard.png
+     :height: 100
+     :width: 200
+     :scale: 50
+     :alt: alternate text
+
+See the full `image directive documentation`__ for more info.
+
+__ ../../ref/rst/directives.html
+__ ../../ref/rst/directives.html#images
+
+
+What Next?
+----------
+
+This primer introduces the most common features of reStructuredText,
+but there are a lot more to explore.  The `Quick reStructuredText`_
+user reference is a good place to go next.  For complete details, the
+`reStructuredText Markup Specification`_ is the place to go [#]_.
+
+Users who have questions or need assistance with Docutils or
+reStructuredText should post a message to the Docutils-users_ mailing
+list.
+
+.. [#] If that relative link doesn't work, try the master document:
+   http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.
+
+.. _reStructuredText Markup Specification:
+   ../../ref/rst/restructuredtext.html
+.. _Docutils-users: ../mailing-lists.html#docutils-users
+.. _Docutils project web site: http://docutils.sourceforge.net/

docs/user/smartquotes.txt

@@ -0,0 +1,481 @@
+=========================
+Smart Quotes for Docutils
+=========================
+
+:Author: Günter Milde,
+         based on SmartyPants by John Gruber, Brad Choate, and Chad Miller
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 8112 $
+:Date: $Date: 2017-06-14 16:20:20 +0200 (Mi, 14 Jun 2017) $
+:License: Released under the terms of the `2-Clause BSD license`_
+:Abstract: This document describes the Docutils `smartquotes` module.
+
+.. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause
+
+.. contents::
+
+Description
+===========
+
+The `"smart_quotes" configuration setting`_ triggers the SmartQuotes
+transformation on Text nodes that includes the following steps:
+
+- Straight quotes (``"`` and ``'``) into "curly" quote characters
+- dashes (``--`` and ``---``) into en- and em-dash entities
+- three consecutive dots (``...`` or ``. . .``) into an ellipsis entity.
+
+This means you can write, edit, and save your documents using plain old
+ASCII---straight quotes, plain dashes, and plain dots---while Docutils
+generates documents with typographical quotes, dashes, and ellipses.
+
+Advantages:
+
+* typing speed (especially when blind-typing),
+* the possibility to change the quoting style of the
+  complete document with just one configuration option, and
+* restriction to 7-bit characters in the source.
+
+However, there are `algorithmic shortcomings`_ for 2 reasons:
+
+* Dual use of the "ASCII-apostrophe" (') as single quote and apostrophe,
+* languages that do not use whitespace around words.
+
+So, please consider also
+`Why You Might Not Want to Use "Smart" Quotes in Your Documents`_.
+
+.. _"smart_quotes" configuration setting:
+.. _"smart_quotes" setting: config.html#smart-quotes
+
+
+Escaping
+========
+
+The `SmartQuotes` transform does not modify characters in literal text
+such as source code, maths, or literal blocks.
+
+If you need literal straight quotes (or plain hyphens and periods) in normal
+text, you can backslash escape the characters to preserve
+ASCII-punctuation. You need two backslashes as one backslash is removed by
+the reStructuredText `escaping mechanism`_.
+
+========  =========  ========  =========
+Escape    Character  Escape    Character
+========  =========  ========  =========
+``\\``    \\         ``\\.``   \\.
+``\\"``   \\"        ``\\-``   \\-
+``\\'``   \\'        ``\\```   \\`
+========  =========  ========  =========
+
+This is useful, for example, when you want to use straight quotes as
+foot and inch marks: 6\\'2\\" tall; a 17\\" iMac.
+
+.. _escaping mechanism: ../ref/rst/restructuredtext.html#escaping-mechanism
+
+
+Localisation
+============
+
+Quotation marks have a `variety of forms`__ in different languages and
+media.
+
+__ https://en.wikipedia.org/wiki/Quotation_mark#Summary_table
+
+`SmartQuotes` inserts quotation marks depending on the language of the
+current block element and the value of the `"smart_quotes" setting`_.\
+[#x-altquot]_ 
+There is built-in support for the following languages:\ [#smartquotes-locales]_
+
+:af: .. class:: language-af
+
+    "'Afrikaans' quotes"
+
+:af-x-altquot: .. class:: language-af-x-altquot
+
+    "'Afrikaans' alternative quotes"
+
+:ca: .. class:: language-ca
+
+    "'Catalan' quotes"
+
+:ca-x-altquot: .. class:: language-ca-x-altquot
+
+    "'Catalan' alternative quotes"
+
+:cs: .. class:: language-cs
+
+    "'Czech' quotes"
+
+:cs-x-altquot: .. class:: language-cs-x-altquot
+
+    "'Czech' alternative quotes"
+
+:da: .. class:: language-da
+
+    "'Danish' quotes"
+
+:da-x-altquot: .. class:: language-da-x-altquot
+
+    "'Danish' alternative quotes"
+
+:de: .. class:: language-de
+
+    "'German' quotes"
+
+:de-x-altquot: .. class:: language-de-x-altquot
+
+    "'German' alternative quotes"
+
+:de-ch: .. class:: language-de-ch
+
+    "'Swiss-German' quotes"
+
+:el: .. class:: language-el
+
+    "'Greek' quotes"
+
+:en: .. class:: language-en
+
+    "'English' quotes"
+
+:en-uk-x-altquot: .. class:: language-en-uk-x-altquot
+
+    "'British' alternative quotes"
+    (swaps single and double quotes: ``"`` → ‘ and ``'`` → “)
+
+:eo: .. class:: language-eo
+
+    "'Esperanto' quotes"
+
+:es: .. class:: language-es
+
+    "'Spanish' quotes"
+
+:es-x-altquot: .. class:: language-es-x-altquot
+
+    "'Spanish' alternative quotes"
+
+:et: .. class:: language-et
+
+    "'Estonian' quotes" (no secondary quote listed in Wikipedia)
+
+:et-x-altquot: .. class:: language-et-x-altquot
+
+    "'Estonian' alternative quotes"
+
+:eu: .. class:: language-eu
+
+    "'Basque' quotes"
+
+:fi: .. class:: language-fi
+
+    "'Finnish' quotes"
+
+:fi-x-altquot: .. class:: language-fi-x-altquot
+
+    "'Finnish' alternative quotes"
+
+:fr: .. class:: language-fr
+
+    "'French' quotes"
+
+:fr-x-altquot: .. class:: language-fr-x-altquot
+
+    "'French' alternative quotes"
+
+:fr-ch: .. class:: language-fr-ch
+
+    "'Swiss-French' quotes"
+
+:fr-ch-x-altquot: .. class:: language-fr-ch-x-altquot
+
+    "'Swiss-French' alternative quotes" (narrow no-break space, see
+    http://typoguide.ch/)
+
+:gl: .. class:: language-gl
+
+    "'Galician' quotes"
+
+:he: .. class:: language-he
+
+    "'Hebrew' quotes"
+
+:he-x-altquot: .. class:: language-he-x-altquot
+
+    "'Hebrew' alternative quotes"
+
+:hr: .. class:: language-hr
+
+    "'Croatian' quotes"
+
+:hr-x-altquot: .. class:: language-hr-x-altquot
+
+    "'Croatian' alternative quotes"
+
+:hsb: .. class:: language-hsb
+
+    "'Upper Sorbian' quotes"
+
+:hsb-x-altquot: .. class:: language-hsb-x-altquot
+
+    "'Upper Sorbian' alternative quotes"
+
+:hu: .. class:: language-hu
+
+    "'Hungarian' quotes"
+
+:is: .. class:: language-is
+
+    "'Icelandic' quotes"
+
+:it: .. class:: language-it
+
+    "'Italian' quotes"
+
+:it-ch: .. class:: language-it-ch
+
+    "'Swiss-Italian' quotes"
+
+:it-x-altquot: .. class:: language-it-x-altquot
+
+    "'Italian' alternative quotes"
+
+:ja: .. class:: language-ja
+
+    "'Japanese' quotes"
+
+:lt: .. class:: language-lt
+
+    "'Lithuanian' quotes"
+
+:lv: .. class:: language-lv
+
+    "'Latvian' quotes"
+
+:nl: .. class:: language-nl
+
+    "'Dutch' quotes"
+
+:nl-x-altquot: .. class:: language-nl-x-altquot
+
+    "'Dutch' alternative quotes"
+
+.. # 'nl-x-altquot2': u'””’’',
+
+:pl: .. class:: language-pl
+
+    "'Polish' quotes"
+
+:pl-x-altquot: .. class:: language-pl-x-altquot
+
+    "'Polish' alternative quotes"
+
+:pt: .. class:: language-pt
+
+    "'Portuguese' quotes"
+
+:pt-br: .. class:: language-pt-br
+
+    "'Portuguese (Brazil)' quotes"
+
+:ro: .. class:: language-ro
+
+    "'Romanian' quotes"
+
+:ru: .. class:: language-ru
+
+    "'Russian' quotes"
+
+:sh: .. class:: language-sh
+
+    "'Serbo-Croatian' quotes"
+
+:sh-x-altquot: .. class:: language-sh-x-altquot
+
+    "'Serbo-Croatian' alternative quotes"
+
+:sk: .. class:: language-sk
+
+    "'Slovak' quotes"
+
+:sk-x-altquot: .. class:: language-sk-x-altquot
+
+    "'Slovak' alternative quotes"
+
+:sl: .. class:: language-sl
+
+    "'Slovenian' quotes"
+
+:sl-x-altquot: .. class:: language-sl-x-altquot
+
+    "'Slovenian' alternative quotes"
+
+:sr: .. class:: language-sr
+
+    "'Serbian' quotes"
+
+:sr-x-altquot: .. class:: language-sr-x-altquot
+
+    "'Serbian' alternative quotes"
+
+:sv: .. class:: language-sv
+
+    "'Swedish' quotes"
+
+:sv-x-altquot: .. class:: language-sv-x-altquot
+
+    "'Swedish' alternative quotes"
+
+:tr: .. class:: language-tr
+
+    "'Turkish' quotes"
+
+:tr-x-altquot: .. class:: language-tr-x-altquot
+
+    "'Turkish' alternative quotes"
+
+.. 'tr-x-altquot2': u'“„‘‚', # antiquated?
+
+:uk: .. class:: language-uk
+
+    "'Ukrainian' quotes"
+
+:uk-x-altquot: .. class:: language-uk-x-altquot
+
+    "'Ukrainian' alternative quotes"
+
+:zh-cn: .. class:: language-zh-cn
+
+    "'Chinese (China)' quotes"
+
+:zh-tw: .. class:: language-zh-tw
+
+    "'Chinese (Taiwan)' quotes"
+
+Quotes in text blocks in a non-configured language are kept as plain quotes:
+
+:undefined: .. class:: language-undefined-example
+
+    "'Undefined' quotes"
+
+.. [#x-altquot] Tags with the non-standard extension ``-x-altquot`` define
+   the quote set used with the `"smart_quotes" setting`_ value ``"alt"``.
+
+.. [#smartquotes-locales] The definitions for language-dependend
+   typographical quotes can be extended or overwritten using the
+   `"smartquotes_locales" setting`_.
+
+   The following example ensures a correct leading apostrophe in ``'s
+   Gravenhage`` (at the cost of incorrect leading single quotes) in Dutch
+   and sets French quotes to double and single guillemets with inner
+   spacing::
+
+     smartquote-locales: nl: „”’’
+                         fr: « : »:‹ : ›
+
+.. _"smartquotes_locales" setting: config.html#smartquotes-locales
+
+
+Caveats
+=======
+
+Why You Might Not Want to Use "Smart" Quotes in Your Documents
+--------------------------------------------------------------
+
+For one thing, you might not care.
+
+Most normal, mentally stable individuals do not take notice of proper
+typographic punctuation. Many design and typography nerds, however, break
+out in a nasty rash when they encounter, say, a restaurant sign that uses
+a straight apostrophe to spell "Joe's".
+
+If you're the sort of person who just doesn't care, you might well want to
+continue not caring. Using straight quotes -- and sticking to the 7-bit
+ASCII character set in general -- is certainly a simpler way to live.
+
+Even if you *do* care about accurate typography, you still might want to
+think twice before "auto-educating" the quote characters in your documents.
+As there is always a chance that the algorithm gets it wrong, you may
+instead prefer to use the compose key or some other means to insert the
+correct Unicode characters into the source.
+
+
+Algorithmic Shortcomings
+------------------------
+
+The ASCII character (u0027 APOSTROPHE) is used for apostrophe and single
+quotes. If used inside a word, it is converted into an apostrophe:
+
+   .. class:: language-fr
+
+   Il dit : "C'est 'super' !"
+
+At the beginning or end of a word, it cannot be distinguished from a single
+quote by the algorithm.
+
+The `right single quotation mark`_ character -- used to close a secondary
+(inner) quote in English -- is also "the preferred character to use for
+apostrophe" (Unicode_). Therefore, "educating" works as expected for
+apostrophes at the end of a word, e.g.,
+
+  Mr. Hastings' pen; three days' leave; my two cents' worth.
+
+However, when apostrophes are used at the start of leading contractions,
+"educating" will turn the apostrophe into an *opening* secondary quote. In
+English, this is *not* the apostrophe character, e.g., ``'Twas brillig``
+is "miseducated" to
+
+  'Twas brillig.
+
+In other locales (French, Italian, German, ...), secondary closing quotes
+differ from the apostrophe. A text like::
+
+   .. class:: language-de-CH
+
+   "Er sagt: 'Ich fass' es nicht.'"
+
+becomes
+
+   .. class:: language-de-CH
+
+   "Er sagt: 'Ich fass' es nicht.'"
+
+with a single closing guillemet in place of the apostrophe.
+
+In such cases, it's best to use the recommended apostrophe character (’) in
+the source:
+
+   | ’Twas brillig, and the slithy toves
+   | Did gyre and gimble in the wabe;
+   | All mimsy were the borogoves,
+   | And the mome raths outgrabe.
+
+.. _right single quotation mark:
+    http://www.fileformat.info/info/unicode/char/2019/index.htm
+.. _Unicode: http://www.unicode.org/charts/PDF/U2000.pdf
+
+History
+=======
+
+The smartquotes module is an adaption of "SmartyPants_" to Docutils.
+
+`John Gruber`_ did all of the hard work of writing this software in Perl for
+`Movable Type`_ and almost all of this useful documentation.  `Chad Miller`_
+ported it to Python to use with Pyblosxom_.
+
+Portions of the SmartyPants original work are based on Brad Choate's nifty
+MTRegex plug-in.  `Brad Choate`_ also contributed a few bits of source code to
+this plug-in.  Brad Choate is a fine hacker indeed.
+`Jeremy Hedley`_ and `Charles Wiltgen`_ deserve mention for exemplary beta
+testing of the original SmartyPants.
+
+Internationalisation and adaption to Docutils by Günter Milde.
+
+.. _SmartyPants: http://daringfireball.net/projects/smartypants/
+.. _Pyblosxom: http://pyblosxom.bluesock.org/
+.. _Movable Type: http://www.movabletype.org/
+.. _John Gruber: http://daringfireball.net/
+.. _Chad Miller: http://web.chad.org/
+.. _Brad Choate: http://bradchoate.com/
+.. _Jeremy Hedley: http://antipixel.com/
+.. _Charles Wiltgen: http://playbacktime.com/
+.. _Rael Dornfest: http://raelity.org/

docs/user/tools.txt

@@ -0,0 +1,481 @@
+==========================
+ Docutils Front-End Tools
+==========================
+
+:Author: David Goodger
+:Contact: docutils-develop@lists.sourceforge.net
+:Revision: $Revision: 8012 $
+:Date: $Date: 2017-01-04 00:08:19 +0100 (Mi, 04 Jan 2017) $
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+
+--------------
+ Introduction
+--------------
+
+Once the Docutils package is unpacked, you will discover a "``tools``"
+directory containing several front ends for common Docutils
+processing.  Rather than a single all-purpose program, Docutils has
+many small front ends, each specialized for a specific "Reader" (which
+knows how to interpret a file in context), a "Parser" (which
+understands the syntax of the text), and a "Writer" (which knows how
+to generate a specific data format).
+
+Most front ends have common options and the same command-line usage
+pattern::
+
+    toolname [options] [<source> [<destination]]
+
+(The exceptions are buildhtml.py_ and rstpep2html.py_.)  See
+rst2html.py_ for concrete examples.  Each tool has a "``--help``"
+option which lists the `command-line options`_ and arguments it
+supports.  Processing can also be customized with `configuration
+files`_.
+
+The two arguments, "source" and "destination", are optional.  If only
+one argument (source) is specified, the standard output (stdout) is
+used for the destination.  If no arguments are specified, the standard
+input (stdin) is used for the source.
+
+
+Getting Help
+============
+
+First, try the "``--help``" option each front-end tool has.
+
+Users who have questions or need assistance with Docutils or
+reStructuredText should post a message to the Docutils-users_ mailing
+list.
+
+.. _Docutils-users: mailing-lists.html#docutils-users
+
+
+-----------
+ The Tools
+-----------
+
+HTML-Generating Tools
+=====================
+
+buildhtml.py
+------------
+
+:Readers: Standalone, PEP
+:Parser: reStructuredText
+:Writers: html_, pep_html_
+
+Use ``buildhtml.py`` to generate ``*.html`` from all the ``*.txt`` files
+(including PEPs) in each <directory> given, and their subdirectories
+too.  (Use the ``--local`` option to skip subdirectories.)
+
+Usage::
+
+    buildhtml.py [options] [<directory> ...]
+
+After unpacking the Docutils package, the following shell commands
+will generate HTML for all included documentation::
+
+    cd docutils/tools
+    buildhtml.py ..
+
+For official releases, the directory may be called "docutils-X.Y",
+where "X.Y" is the release version.  Alternatively::
+
+    cd docutils
+    tools/buildhtml.py --config=tools/docutils.conf
+
+The current directory (and all subdirectories) is chosen by default if
+no directory is named.  Some files may generate system messages
+(docs/user/rst/demo.txt contains intentional errors); use the
+``--quiet`` option to suppress all warnings.  The ``--config`` option
+ensures that the correct settings are in place (a ``docutils.conf``
+`configuration file`_ in the current directory is picked up
+automatically).  Command-line options may be used to override config
+file settings or replace them altogether.
+
+
+rst2html.py
+-----------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: html_
+
+`rst2html.py` is the front-end for the default Docutils HTML writer.
+The default writer may change with the development of HTML, browsers,
+Docutils, and the web. Currently, it is html4css1_.
+
+* Use `rst2html.py`, if you want the output to be up-to-date automatically.
+
+* Use a specific front end, if you depend on stability of the
+  generated HTML code, e.g. because you use a custom style sheet or
+  post-processing that may break otherwise.
+
+
+rst2html4.py
+------------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: html4css1_
+
+The ``rst2html4.py`` front end reads standalone reStructuredText source
+files and produces `XHTML 1.0 Transitional`_ output.
+A CSS stylesheet is required for proper rendering; a simple but
+complete stylesheet is installed and used by default (see Stylesheets_
+below).
+
+For example, to process a reStructuredText file "``test.txt``" into
+HTML::
+
+    rst2html.py test.txt test.html
+
+Now open the "``test.html``" file in your favorite browser to see the
+results.  To get a footer with a link to the source file, date & time
+of processing, and links to the Docutils project, add some options::
+
+    rst2html.py -stg test.txt test.html
+
+
+Stylesheets
+```````````
+
+``rst2html.py`` inserts into the generated HTML a cascading stylesheet
+(or a link to a stylesheet, when passing the "``--link-stylesheet``"
+option).  A stylesheet is required for proper rendering.  The default
+stylesheet (``docutils/writers/html4css1/html4css1.css``, located in
+the installation directory) is provided for basic use.  To use
+different stylesheet(s), specify the stylesheets' location(s)
+as comma-separated list with the "``--stylesheet``" (for a URL)
+or "``--stylesheet-path``" (for a local file) command-line option,
+or with `configuration file`_ settings (e.g. ``./docutils.conf``
+or ``~/.docutils``).  To experiment with styles, please see the
+`guide to writing HTML (CSS) stylesheets for Docutils`__.
+
+__ ../howto/html-stylesheets.html
+.. _html4css1: html.html#html4css1
+.. _html: html.html#html
+
+
+rst2html5.py
+------------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: html5 (html5_polyglot_)
+
+The ``rst2html5.py`` front end reads standalone reStructuredText source
+files and produces `HTML 5`_ output.
+Correct rendering of elements not directly supported by HTML depends on a
+CSS style sheet. The provided style sheets ``minimal.css`` and ``plain.css``
+define required and optional styling rules respectively.
+
+.. _html5_polyglot: html.html#html5-polyglot
+
+rstpep2html.py
+--------------
+
+:Reader: PEP
+:Parser: reStructuredText
+:Writer: pep_html_
+
+``rstpep2html.py`` reads a new-style PEP (marked up with reStructuredText)
+and produces `XHTML 1.0 Transitional`_.  It requires a template file and a
+stylesheet.  By default, it makes use of a "``pep-html-template``" file and
+the "``pep.css``" stylesheet (both in the ``docutils/writers/pep_html/``
+directory), but these can be overridden by command-line options or
+configuration files.
+
+For example, to process a PEP into HTML::
+
+    cd <path-to-docutils>/docs/peps
+    rstpep2html.py pep-0287.txt pep-0287.html
+
+.. _pep_html: html.html#pep-html
+
+rst2s5.py
+---------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: s5_html_
+
+The ``rst2s5.py`` front end reads standalone reStructuredText source
+files and produces (X)HTML output compatible with S5_, the "Simple
+Standards-based Slide Show System" by Eric Meyer.  A theme is required
+for proper rendering; several are distributed with Docutils and others
+are available; see Themes_ below.
+
+For example, to process a reStructuredText file "``slides.txt``" into
+S5/HTML::
+
+    rst2s5.py slides.txt slides.html
+
+Now open the "``slides.html``" file in your favorite browser, switch
+to full-screen mode, and enjoy the results.
+
+.. _S5: http://meyerweb.com/eric/tools/s5/
+.. _s5_html: html.html#s5-html
+
+Themes
+``````
+
+Each S5 theme consists of a directory containing several files:
+stylesheets, JavaScript, and graphics.  These are copied into a
+``ui/<theme>`` directory beside the generated HTML.  A theme is chosen
+using the "``--theme``" option (for themes that come with Docutils) or
+the "``--theme-url``" option (for themes anywhere).  For example, the
+"medium-black" theme can be specified as follows::
+
+    rst2s5.py --theme medium-black slides.txt slides.html
+
+The theme will be copied to the ``ui/medium-black`` directory.
+
+Several themes are included with Docutils:
+
+``default``
+    This is a simplified version of S5's default theme.
+
+    :Main content: black serif text on a white background
+    :Text capacity: about 13 lines
+    :Headers: light blue, bold sans-serif text on a dark blue
+              background; titles are limited to one line
+    :Footers: small, gray, bold sans-serif text on a dark blue
+              background
+
+``small-white``
+    (Small text on a white background.)
+
+    :Main content: black serif text on a white background
+    :Text capacity: about 15 lines
+    :Headers: black, bold sans-serif text on a white background;
+              titles wrap
+    :Footers: small, dark gray, bold sans-serif text on a white
+              background
+
+``small-black``
+    :Main content: white serif text on a black background
+    :Text capacity: about 15 lines
+    :Headers: white, bold sans-serif text on a black background;
+              titles wrap
+    :Footers: small, light gray, bold sans-serif text on a black
+              background
+
+``medium-white``
+    :Main content: black serif text on a white background
+    :Text capacity: about 9 lines
+    :Headers: black, bold sans-serif text on a white background;
+              titles wrap
+    :Footers: small, dark gray, bold sans-serif text on a white
+              background
+
+``medium-black``
+    :Main content: white serif text on a black background
+    :Text capacity: about 9 lines
+    :Headers: white, bold sans-serif text on a black background;
+              titles wrap
+    :Footers: small, light gray, bold sans-serif text on a black
+              background
+
+``big-white``
+    :Main content: black, bold sans-serif text on a white background
+    :Text capacity: about 5 lines
+    :Headers: black, bold sans-serif text on a white background;
+              titles wrap
+    :Footers: not displayed
+
+``big-black``
+    :Main content: white, bold sans-serif text on a black background
+    :Text capacity: about 5 lines
+    :Headers: white, bold sans-serif text on a black background;
+              titles wrap
+    :Footers: not displayed
+
+If a theme directory contains a file named ``__base__``, the name of
+the theme's base theme will be read from it.  Files are accumulated
+from the named theme, any base themes, and the "default" theme (which
+is the implicit base of all themes).
+
+For details, please see `Easy Slide Shows With reStructuredText &
+S5 <slide-shows.html>`_.
+
+
+.. _HTML 5: http://www.w3.org/TR/html5/
+.. _HTML 4.1: http://www.w3.org/TR/html401/
+.. _XHTML 1.0 Transitional: http://www.w3.org/TR/xhtml1/
+.. _XHTML 1.1: http://www.w3.org/TR/xhtml1/
+
+
+LaTeX-Generating Tools
+======================
+
+rst2latex.py
+------------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: latex2e
+
+The ``rst2latex.py`` front end reads standalone reStructuredText
+source files and produces LaTeX_ output. For example, to process a
+reStructuredText file "``test.txt``" into LaTeX::
+
+    rst2latex.py test.txt test.tex
+
+The output file "``test.tex``" should then be processed with ``latex``
+or ``pdflatex`` to get a document in DVI, PostScript or PDF format for
+printing or on-screen viewing.
+
+For details see `Generating LaTeX with Docutils`_.
+
+rst2xetex.py
+------------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: xetex
+
+The ``rst2xetex.py`` front end reads standalone reStructuredText source
+files and produces `LaTeX` output for processing with unicode-aware
+TeX engines (`LuaTeX`_ or `XeTeX`_). For example, to process a
+reStructuredText file "``test.txt``" into LaTeX::
+
+    rst2xetex.py test.txt test.tex
+
+The output file "``test.tex``" should then be processed with ``xelatex`` or
+``lualatex`` to get a document in PDF format for printing or on-screen
+viewing.
+
+For details see `Generating LaTeX with Docutils`_.
+
+.. _LaTeX: https://en.wikipedia.org/wiki/LaTeX
+.. _XeTeX: https://en.wikipedia.org/wiki/XeTeX
+.. _LuaTeX: https://en.wikipedia.org/wiki/LuaTeX
+
+
+XML-Generating Tools
+====================
+
+rst2xml.py
+----------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: XML (Docutils native)
+
+The ``rst2xml.py`` front end produces Docutils-native XML output.
+This can be transformed with standard XML tools such as XSLT
+processors into arbitrary final forms. An example is the xml2rst_ processor
+in the Docutils sandbox.
+
+.. _xml2rst: ../../../sandbox/xml2rst
+
+
+ODF/OpenOffice-Generating Tools
+===============================
+
+rst2odt.py
+----------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: ODF/.odt
+
+The ``rst2odt.py`` front end reads standalone reStructuredText
+source files and produces ODF/.odt files that can be read, edited,
+printed, etc with OpenOffice ``oowriter``
+(http://www.openoffice.org/).  A stylesheet file is required.  A
+stylesheet file is an OpenOffice .odt file containing definitions
+of the styles required for ``rst2odt.py``.  You can learn more
+about how to use ``rst2odt.py``, the styles used ``rst2odt.py``,
+etc from `Odt Writer for Docutils <odt.html>`_.
+
+
+reStructuredText-Generating Tools
+=================================
+
+Currently, there is no reStructuredText writer in Docutils and therefore
+an ``rst2rst.py`` tool is still missing.
+
+To generate reStructuredText documents with Docutils, you can use
+the XML (Docutils native) writer and the xml2rst_ processor.
+
+
+Testing/Debugging Tools
+=======================
+
+rst2pseudoxml.py
+----------------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: Pseudo-XML
+
+``rst2pseudoxml.py`` is used for debugging the Docutils "Reader to
+Transform to Writer" pipeline.  It produces a compact pretty-printed
+"pseudo-XML", where nesting is indicated by indentation (no end-tags).
+External attributes for all elements are output, and internal
+attributes for any leftover "pending" elements are also given.
+
+
+quicktest.py
+------------
+
+:Reader: N/A
+:Parser: reStructuredText
+:Writer: N/A
+
+The ``quicktest.py`` tool is used for testing the reStructuredText
+parser.  It does not use a Docutils Reader or Writer or the standard
+Docutils command-line options.  Rather, it does its own I/O and calls
+the parser directly.  No transforms are applied to the parsed
+document.  Various forms output are possible:
+
+- Pretty-printed pseudo-XML (default)
+- Test data (Python list of input and pseudo-XML output strings;
+  useful for creating new test cases)
+- Pretty-printed native XML
+- Raw native XML (with or without a stylesheet reference)
+
+
+
+---------------
+ Customization
+---------------
+
+Command-Line Options
+====================
+
+Each front-end tool supports command-line options for one-off
+customization.  For persistent customization, use `configuration
+files`_.  Command-line options take priority over configuration file
+settings.
+
+Use the "--help" option on each of the front ends to list the
+command-line options it supports.  Command-line options and their
+corresponding configuration file entry names are listed in the
+`Docutils Configuration Files`_ document.
+
+
+.. _configuration file:
+
+Configuration Files
+===================
+
+Configuration files are used for persistent customization; they can be
+set once and take effect every time you use a front-end tool.
+
+For details, see `Docutils Configuration Files`_.
+
+.. _Docutils Configuration Files: config.html
+.. _Generating LaTeX with Docutils: latex.html
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

docutils.conf

@@ -0,0 +1,16 @@
+# These entries affect all processing:
+[general]
+source-link: yes
+datestamp: %Y-%m-%d %H:%M UTC
+generator: on
+
+# These entries affect HTML output:
+[html4css1 writer]
+stylesheet-path: docutils/writers/html4css1/html4css1.css
+embed-stylesheet: no
+field-name-limit: 20
+
+# Prevent tools/buildhtml.py from processing certain text files.
+[buildhtml application]
+ignore: GPL2.txt
+prune: .svn:.hg:docs/.svn:docutils:test:tools:licenses:build:dist

docutils/_compat.py

@@ -0,0 +1,48 @@
+# $Id: _compat.py 7486 2012-07-11 12:25:14Z milde $
+# Author: Georg Brandl <georg@python.org>
+# Copyright: This module has been placed in the public domain.
+
+"""
+Python 2/3 compatibility definitions.
+
+This module currently provides the following helper symbols:
+
+* bytes (name of byte string type; str in 2.x, bytes in 3.x)
+* b (function converting a string literal to an ASCII byte string;
+  can be also used to convert a Unicode string into a byte string)
+* u_prefix (unicode repr prefix: 'u' in 2.x, '' in 3.x)
+  (Required in docutils/test/test_publisher.py)
+* BytesIO (a StringIO class that works with bytestrings)
+"""
+
+import sys
+
+if sys.version_info < (3,0):
+    b = bytes = str
+    u_prefix = 'u'
+    from StringIO import StringIO as BytesIO
+else:
+    import builtins
+    bytes = builtins.bytes
+    u_prefix = ''
+    def b(s):
+        if isinstance(s, str):
+            return s.encode('latin1')
+        elif isinstance(s, bytes):
+            return s
+        else:
+            raise TypeError("Invalid argument %r for b()" % (s,))
+    # using this hack since 2to3 "fixes" the relative import
+    # when using ``from io import BytesIO``
+    BytesIO = __import__('io').BytesIO
+
+if sys.version_info < (2,5):
+    import __builtin__
+
+    def __import__(name, globals={}, locals={}, fromlist=[], level=-1):
+        """Compatibility definition for Python 2.4.
+
+        Silently ignore the `level` argument missing in Python < 2.5.
+        """
+        # we need the level arg because the default changed in Python 3.3
+        return __builtin__.__import__(name, globals, locals, fromlist)

docutils/core.py

@@ -0,0 +1,665 @@
+# $Id: core.py 8126 2017-06-23 09:34:28Z milde $
+# Author: David Goodger <goodger@python.org>
+# Copyright: This module has been placed in the public domain.
+
+"""
+Calling the ``publish_*`` convenience functions (or instantiating a
+`Publisher` object) with component names will result in default
+behavior.  For custom behavior (setting component options), create
+custom component objects first, and pass *them* to
+``publish_*``/`Publisher`.  See `The Docutils Publisher`_.
+
+.. _The Docutils Publisher: http://docutils.sf.net/docs/api/publisher.html
+"""
+
+__docformat__ = 'reStructuredText'
+
+import sys
+import pprint
+from docutils import __version__, __version_details__, SettingsSpec
+from docutils import frontend, io, utils, readers, writers
+from docutils.frontend import OptionParser
+from docutils.transforms import Transformer
+from docutils.utils.error_reporting import ErrorOutput, ErrorString
+import docutils.readers.doctree
+
+class Publisher:
+
+    """
+    A facade encapsulating the high-level logic of a Docutils system.
+    """
+
+    def __init__(self, reader=None, parser=None, writer=None,
+                 source=None, source_class=io.FileInput,
+                 destination=None, destination_class=io.FileOutput,
+                 settings=None):
+        """
+        Initial setup.  If any of `reader`, `parser`, or `writer` are not
+        specified, the corresponding ``set_...`` method should be called with
+        a component name (`set_reader` sets the parser as well).
+        """
+
+        self.document = None
+        """The document tree (`docutils.nodes` objects)."""
+
+        self.reader = reader
+        """A `docutils.readers.Reader` instance."""
+
+        self.parser = parser
+        """A `docutils.parsers.Parser` instance."""
+
+        self.writer = writer
+        """A `docutils.writers.Writer` instance."""
+
+        for component in 'reader', 'parser', 'writer':
+            assert not isinstance(getattr(self, component), str), (
+                'passed string "%s" as "%s" parameter; pass an instance, '
+                'or use the "%s_name" parameter instead (in '
+                'docutils.core.publish_* convenience functions).'
+                % (getattr(self, component), component, component))
+
+        self.source = source
+        """The source of input data, a `docutils.io.Input` instance."""
+
+        self.source_class = source_class
+        """The class for dynamically created source objects."""
+
+        self.destination = destination
+        """The destination for docutils output, a `docutils.io.Output`
+        instance."""
+
+        self.destination_class = destination_class
+        """The class for dynamically created destination objects."""
+
+        self.settings = settings
+        """An object containing Docutils settings as instance attributes.
+        Set by `self.process_command_line()` or `self.get_settings()`."""
+
+        self._stderr = ErrorOutput()
+
+    def set_reader(self, reader_name, parser, parser_name):
+        """Set `self.reader` by name."""
+        reader_class = readers.get_reader_class(reader_name)
+        self.reader = reader_class(parser, parser_name)
+        self.parser = self.reader.parser
+
+    def set_writer(self, writer_name):
+        """Set `self.writer` by name."""
+        writer_class = writers.get_writer_class(writer_name)
+        self.writer = writer_class()
+
+    def set_components(self, reader_name, parser_name, writer_name):
+        if self.reader is None:
+            self.set_reader(reader_name, self.parser, parser_name)
+        if self.parser is None:
+            if self.reader.parser is None:
+                self.reader.set_parser(parser_name)
+            self.parser = self.reader.parser
+        if self.writer is None:
+            self.set_writer(writer_name)
+
+    def setup_option_parser(self, usage=None, description=None,
+                            settings_spec=None, config_section=None,
+                            **defaults):
+        if config_section:
+            if not settings_spec:
+                settings_spec = SettingsSpec()
+            settings_spec.config_section = config_section
+            parts = config_section.split()
+            if len(parts) > 1 and parts[-1] == 'application':
+                settings_spec.config_section_dependencies = ['applications']
+        #@@@ Add self.source & self.destination to components in future?
+        option_parser = OptionParser(
+            components=(self.parser, self.reader, self.writer, settings_spec),
+            defaults=defaults, read_config_files=True,
+            usage=usage, description=description)
+        return option_parser
+
+    def get_settings(self, usage=None, description=None,
+                     settings_spec=None, config_section=None, **defaults):
+        """
+        Set and return default settings (overrides in `defaults` dict).
+
+        Set components first (`self.set_reader` & `self.set_writer`).
+        Explicitly setting `self.settings` disables command line option
+        processing from `self.publish()`.
+        """
+        option_parser = self.setup_option_parser(
+            usage, description, settings_spec, config_section, **defaults)
+        self.settings = option_parser.get_default_values()
+        return self.settings
+
+    def process_programmatic_settings(self, settings_spec,
+                                      settings_overrides,
+                                      config_section):
+        if self.settings is None:
+            defaults = (settings_overrides or {}).copy()
+            # Propagate exceptions by default when used programmatically:
+            defaults.setdefault('traceback', True)
+            self.get_settings(settings_spec=settings_spec,
+                              config_section=config_section,
+                              **defaults)
+
+    def process_command_line(self, argv=None, usage=None, description=None,
+                             settings_spec=None, config_section=None,
+                             **defaults):
+        """
+        Pass an empty list to `argv` to avoid reading `sys.argv` (the
+        default).
+
+        Set components first (`self.set_reader` & `self.set_writer`).
+        """
+        option_parser = self.setup_option_parser(
+            usage, description, settings_spec, config_section, **defaults)
+        if argv is None:
+            argv = sys.argv[1:]
+            # converting to Unicode (Python 3 does this automatically):
+            if sys.version_info < (3,0):
+                # TODO: make this failsafe and reversible?
+                argv_encoding = (frontend.locale_encoding or 'ascii')
+                argv = [a.decode(argv_encoding) for a in argv]
+        self.settings = option_parser.parse_args(argv)
+
+    def set_io(self, source_path=None, destination_path=None):
+        if self.source is None:
+            self.set_source(source_path=source_path)
+        if self.destination is None:
+            self.set_destination(destination_path=destination_path)
+
+    def set_source(self, source=None, source_path=None):
+        if source_path is None:
+            source_path = self.settings._source
+        else:
+            self.settings._source = source_path
+        # Raise IOError instead of system exit with `tracback == True`
+        # TODO: change io.FileInput's default behaviour and remove this hack
+        try:
+            self.source = self.source_class(
+                source=source, source_path=source_path,
+                encoding=self.settings.input_encoding)
+        except TypeError:
+            self.source = self.source_class(
+                source=source, source_path=source_path,
+                encoding=self.settings.input_encoding)
+
+    def set_destination(self, destination=None, destination_path=None):
+        if destination_path is None:
+            destination_path = self.settings._destination
+        else:
+            self.settings._destination = destination_path
+        self.destination = self.destination_class(
+            destination=destination, destination_path=destination_path,
+            encoding=self.settings.output_encoding,
+            error_handler=self.settings.output_encoding_error_handler)
+
+    def apply_transforms(self):
+        self.document.transformer.populate_from_components(
+            (self.source, self.reader, self.reader.parser, self.writer,
+             self.destination))
+        self.document.transformer.apply_transforms()
+
+    def publish(self, argv=None, usage=None, description=None,
+                settings_spec=None, settings_overrides=None,
+                config_section=None, enable_exit_status=False):
+        """
+        Process command line options and arguments (if `self.settings` not
+        already set), run `self.reader` and then `self.writer`.  Return
+        `self.writer`'s output.
+        """
+        exit = None
+        try:
+            if self.settings is None:
+                self.process_command_line(
+                    argv, usage, description, settings_spec, config_section,
+                    **(settings_overrides or {}))
+            self.set_io()
+            self.document = self.reader.read(self.source, self.parser,
+                                             self.settings)
+            self.apply_transforms()
+            output = self.writer.write(self.document, self.destination)
+            self.writer.assemble_parts()
+        except SystemExit, error:
+            exit = 1
+            exit_status = error.code
+        except Exception, error:
+            if not self.settings:       # exception too early to report nicely
+                raise
+            if self.settings.traceback: # Propagate exceptions?
+                self.debugging_dumps()
+                raise
+            self.report_Exception(error)
+            exit = True
+            exit_status = 1
+        self.debugging_dumps()
+        if (enable_exit_status and self.document
+            and (self.document.reporter.max_level
+                 >= self.settings.exit_status_level)):
+            sys.exit(self.document.reporter.max_level + 10)
+        elif exit:
+            sys.exit(exit_status)
+        return output
+
+    def debugging_dumps(self):
+        if not self.document:
+            return
+        if self.settings.dump_settings:
+            print >>self._stderr, '\n::: Runtime settings:'
+            print >>self._stderr, pprint.pformat(self.settings.__dict__)
+        if self.settings.dump_internals:
+            print >>self._stderr, '\n::: Document internals:'
+            print >>self._stderr, pprint.pformat(self.document.__dict__)
+        if self.settings.dump_transforms:
+            print >>self._stderr, '\n::: Transforms applied:'
+            print >>self._stderr, (' (priority, transform class, '
+                                 'pending node details, keyword args)')
+            print >>self._stderr, pprint.pformat(
+                [(priority, '%s.%s' % (xclass.__module__, xclass.__name__),
+                  pending and pending.details, kwargs)
+                 for priority, xclass, pending, kwargs
+                 in self.document.transformer.applied])
+        if self.settings.dump_pseudo_xml:
+            print >>self._stderr, '\n::: Pseudo-XML:'
+            print >>self._stderr, self.document.pformat().encode(
+                'raw_unicode_escape')
+
+    def report_Exception(self, error):
+        if isinstance(error, utils.SystemMessage):
+            self.report_SystemMessage(error)
+        elif isinstance(error, UnicodeEncodeError):
+            self.report_UnicodeError(error)
+        elif isinstance(error, io.InputError):
+            self._stderr.write(u'Unable to open source file for reading:\n'
+                               u'  %s\n' % ErrorString(error))
+        elif isinstance(error, io.OutputError):
+            self._stderr.write(
+                u'Unable to open destination file for writing:\n'
+                u'  %s\n' % ErrorString(error))
+        else:
+            print >>self._stderr, u'%s' % ErrorString(error)
+            print >>self._stderr, ("""\
+Exiting due to error.  Use "--traceback" to diagnose.
+Please report errors to <docutils-users@lists.sf.net>.
+Include "--traceback" output, Docutils version (%s%s),
+Python version (%s), your OS type & version, and the
+command line used.""" % (__version__,
+                         docutils.__version_details__ and
+                         ' [%s]'%docutils.__version_details__ or '',
+                         sys.version.split()[0]))
+
+    def report_SystemMessage(self, error):
+        print >>self._stderr, ('Exiting due to level-%s (%s) system message.'
+                             % (error.level,
+                                utils.Reporter.levels[error.level]))
+
+    def report_UnicodeError(self, error):
+        data = error.object[error.start:error.end]
+        self._stderr.write(
+            '%s\n'
+            '\n'
+            'The specified output encoding (%s) cannot\n'
+            'handle all of the output.\n'
+            'Try setting "--output-encoding-error-handler" to\n'
+            '\n'
+            '* "xmlcharrefreplace" (for HTML & XML output);\n'
+            '  the output will contain "%s" and should be usable.\n'
+            '* "backslashreplace" (for other output formats);\n'
+            '  look for "%s" in the output.\n'
+            '* "replace"; look for "?" in the output.\n'
+            '\n'
+            '"--output-encoding-error-handler" is currently set to "%s".\n'
+            '\n'
+            'Exiting due to error.  Use "--traceback" to diagnose.\n'
+            'If the advice above doesn\'t eliminate the error,\n'
+            'please report it to <docutils-users@lists.sf.net>.\n'
+            'Include "--traceback" output, Docutils version (%s),\n'
+            'Python version (%s), your OS type & version, and the\n'
+            'command line used.\n'
+            % (ErrorString(error),
+               self.settings.output_encoding,
+               data.encode('ascii', 'xmlcharrefreplace'),
+               data.encode('ascii', 'backslashreplace'),
+               self.settings.output_encoding_error_handler,
+               __version__, sys.version.split()[0]))
+
+default_usage = '%prog [options] [<source> [<destination>]]'
+default_description = ('Reads from <source> (default is stdin) and writes to '
+                       '<destination> (default is stdout).  See '
+                       '<http://docutils.sf.net/docs/user/config.html> for '
+                       'the full reference.')
+
+def publish_cmdline(reader=None, reader_name='standalone',
+                    parser=None, parser_name='restructuredtext',
+                    writer=None, writer_name='pseudoxml',
+                    settings=None, settings_spec=None,
+                    settings_overrides=None, config_section=None,
+                    enable_exit_status=True, argv=None,
+                    usage=default_usage, description=default_description):
+    """
+    Set up & run a `Publisher` for command-line-based file I/O (input and
+    output file paths taken automatically from the command line).  Return the
+    encoded string output also.
+
+    Parameters: see `publish_programmatically` for the remainder.
+
+    - `argv`: Command-line argument list to use instead of ``sys.argv[1:]``.
+    - `usage`: Usage string, output if there's a problem parsing the command
+      line.
+    - `description`: Program description, output for the "--help" option
+      (along with command-line option descriptions).
+    """
+    pub = Publisher(reader, parser, writer, settings=settings)
+    pub.set_components(reader_name, parser_name, writer_name)
+    output = pub.publish(
+        argv, usage, description, settings_spec, settings_overrides,
+        config_section=config_section, enable_exit_status=enable_exit_status)
+    return output
+
+def publish_file(source=None, source_path=None,
+                 destination=None, destination_path=None,
+                 reader=None, reader_name='standalone',
+                 parser=None, parser_name='restructuredtext',
+                 writer=None, writer_name='pseudoxml',
+                 settings=None, settings_spec=None, settings_overrides=None,
+                 config_section=None, enable_exit_status=False):
+    """
+    Set up & run a `Publisher` for programmatic use with file-like I/O.
+    Return the encoded string output also.
+
+    Parameters: see `publish_programmatically`.
+    """
+    output, pub = publish_programmatically(
+        source_class=io.FileInput, source=source, source_path=source_path,
+        destination_class=io.FileOutput,
+        destination=destination, destination_path=destination_path,
+        reader=reader, reader_name=reader_name,
+        parser=parser, parser_name=parser_name,
+        writer=writer, writer_name=writer_name,
+        settings=settings, settings_spec=settings_spec,
+        settings_overrides=settings_overrides,
+        config_section=config_section,
+        enable_exit_status=enable_exit_status)
+    return output
+
+def publish_string(source, source_path=None, destination_path=None,
+                   reader=None, reader_name='standalone',
+                   parser=None, parser_name='restructuredtext',
+                   writer=None, writer_name='pseudoxml',
+                   settings=None, settings_spec=None,
+                   settings_overrides=None, config_section=None,
+                   enable_exit_status=False):
+    """
+    Set up & run a `Publisher` for programmatic use with string I/O.  Return
+    the encoded string or Unicode string output.
+
+    For encoded string output, be sure to set the 'output_encoding' setting to
+    the desired encoding.  Set it to 'unicode' for unencoded Unicode string
+    output.  Here's one way::
+
+        publish_string(..., settings_overrides={'output_encoding': 'unicode'})
+
+    Similarly for Unicode string input (`source`)::
+
+        publish_string(..., settings_overrides={'input_encoding': 'unicode'})
+
+    Parameters: see `publish_programmatically`.
+    """
+    output, pub = publish_programmatically(
+        source_class=io.StringInput, source=source, source_path=source_path,
+        destination_class=io.StringOutput,
+        destination=None, destination_path=destination_path,
+        reader=reader, reader_name=reader_name,
+        parser=parser, parser_name=parser_name,
+        writer=writer, writer_name=writer_name,
+        settings=settings, settings_spec=settings_spec,
+        settings_overrides=settings_overrides,
+        config_section=config_section,
+        enable_exit_status=enable_exit_status)
+    return output
+
+def publish_parts(source, source_path=None, source_class=io.StringInput,
+                  destination_path=None,
+                  reader=None, reader_name='standalone',
+                  parser=None, parser_name='restructuredtext',
+                  writer=None, writer_name='pseudoxml',
+                  settings=None, settings_spec=None,
+                  settings_overrides=None, config_section=None,
+                  enable_exit_status=False):
+    """
+    Set up & run a `Publisher`, and return a dictionary of document parts.
+    Dictionary keys are the names of parts, and values are Unicode strings;
+    encoding is up to the client.  For programmatic use with string I/O.
+
+    For encoded string input, be sure to set the 'input_encoding' setting to
+    the desired encoding.  Set it to 'unicode' for unencoded Unicode string
+    input.  Here's how::
+
+        publish_parts(..., settings_overrides={'input_encoding': 'unicode'})
+
+    Parameters: see `publish_programmatically`.
+    """
+    output, pub = publish_programmatically(
+        source=source, source_path=source_path, source_class=source_class,
+        destination_class=io.StringOutput,
+        destination=None, destination_path=destination_path,
+        reader=reader, reader_name=reader_name,
+        parser=parser, parser_name=parser_name,
+        writer=writer, writer_name=writer_name,
+        settings=settings, settings_spec=settings_spec,
+        settings_overrides=settings_overrides,
+        config_section=config_section,
+        enable_exit_status=enable_exit_status)
+    return pub.writer.parts
+
+def publish_doctree(source, source_path=None,
+                    source_class=io.StringInput,
+                    reader=None, reader_name='standalone',
+                    parser=None, parser_name='restructuredtext',
+                    settings=None, settings_spec=None,
+                    settings_overrides=None, config_section=None,
+                    enable_exit_status=False):
+    """
+    Set up & run a `Publisher` for programmatic use with string I/O.
+    Return the document tree.
+
+    For encoded string input, be sure to set the 'input_encoding' setting to
+    the desired encoding.  Set it to 'unicode' for unencoded Unicode string
+    input.  Here's one way::
+
+        publish_doctree(..., settings_overrides={'input_encoding': 'unicode'})
+
+    Parameters: see `publish_programmatically`.
+    """
+    pub = Publisher(reader=reader, parser=parser, writer=None,
+                    settings=settings,
+                    source_class=source_class,
+                    destination_class=io.NullOutput)
+    pub.set_components(reader_name, parser_name, 'null')
+    pub.process_programmatic_settings(
+        settings_spec, settings_overrides, config_section)
+    pub.set_source(source, source_path)
+    pub.set_destination(None, None)
+    output = pub.publish(enable_exit_status=enable_exit_status)
+    return pub.document
+
+def publish_from_doctree(document, destination_path=None,
+                         writer=None, writer_name='pseudoxml',
+                         settings=None, settings_spec=None,
+                         settings_overrides=None, config_section=None,
+                         enable_exit_status=False):
+    """
+    Set up & run a `Publisher` to render from an existing document
+    tree data structure, for programmatic use with string I/O.  Return
+    the encoded string output.
+
+    Note that document.settings is overridden; if you want to use the settings
+    of the original `document`, pass settings=document.settings.
+
+    Also, new document.transformer and document.reporter objects are
+    generated.
+
+    For encoded string output, be sure to set the 'output_encoding' setting to
+    the desired encoding.  Set it to 'unicode' for unencoded Unicode string
+    output.  Here's one way::
+
+        publish_from_doctree(
+            ..., settings_overrides={'output_encoding': 'unicode'})
+
+    Parameters: `document` is a `docutils.nodes.document` object, an existing
+    document tree.
+
+    Other parameters: see `publish_programmatically`.
+    """
+    reader = docutils.readers.doctree.Reader(parser_name='null')
+    pub = Publisher(reader, None, writer,
+                    source=io.DocTreeInput(document),
+                    destination_class=io.StringOutput, settings=settings)
+    if not writer and writer_name:
+        pub.set_writer(writer_name)
+    pub.process_programmatic_settings(
+        settings_spec, settings_overrides, config_section)
+    pub.set_destination(None, destination_path)
+    return pub.publish(enable_exit_status=enable_exit_status)
+
+def publish_cmdline_to_binary(reader=None, reader_name='standalone',
+                    parser=None, parser_name='restructuredtext',
+                    writer=None, writer_name='pseudoxml',
+                    settings=None, settings_spec=None,
+                    settings_overrides=None, config_section=None,
+                    enable_exit_status=True, argv=None,
+                    usage=default_usage, description=default_description,
+                    destination=None, destination_class=io.BinaryFileOutput
+                    ):
+    """
+    Set up & run a `Publisher` for command-line-based file I/O (input and
+    output file paths taken automatically from the command line).  Return the
+    encoded string output also.
+
+    This is just like publish_cmdline, except that it uses
+    io.BinaryFileOutput instead of io.FileOutput.
+
+    Parameters: see `publish_programmatically` for the remainder.
+
+    - `argv`: Command-line argument list to use instead of ``sys.argv[1:]``.
+    - `usage`: Usage string, output if there's a problem parsing the command
+      line.
+    - `description`: Program description, output for the "--help" option
+      (along with command-line option descriptions).
+    """
+    pub = Publisher(reader, parser, writer, settings=settings,
+        destination_class=destination_class)
+    pub.set_components(reader_name, parser_name, writer_name)
+    output = pub.publish(
+        argv, usage, description, settings_spec, settings_overrides,
+        config_section=config_section, enable_exit_status=enable_exit_status)
+    return output
+
+def publish_programmatically(source_class, source, source_path,
+                             destination_class, destination, destination_path,
+                             reader, reader_name,
+                             parser, parser_name,
+                             writer, writer_name,
+                             settings, settings_spec,
+                             settings_overrides, config_section,
+                             enable_exit_status):
+    """
+    Set up & run a `Publisher` for custom programmatic use.  Return the
+    encoded string output and the Publisher object.
+
+    Applications should not need to call this function directly.  If it does
+    seem to be necessary to call this function directly, please write to the
+    Docutils-develop mailing list
+    <http://docutils.sf.net/docs/user/mailing-lists.html#docutils-develop>.
+
+    Parameters:
+
+    * `source_class` **required**: The class for dynamically created source
+      objects.  Typically `io.FileInput` or `io.StringInput`.
+
+    * `source`: Type depends on `source_class`:
+
+      - If `source_class` is `io.FileInput`: Either a file-like object
+        (must have 'read' and 'close' methods), or ``None``
+        (`source_path` is opened).  If neither `source` nor
+        `source_path` are supplied, `sys.stdin` is used.
+
+      - If `source_class` is `io.StringInput` **required**: The input
+        string, either an encoded 8-bit string (set the
+        'input_encoding' setting to the correct encoding) or a Unicode
+        string (set the 'input_encoding' setting to 'unicode').
+
+    * `source_path`: Type depends on `source_class`:
+
+      - `io.FileInput`: Path to the input file, opened if no `source`
+        supplied.
+
+      - `io.StringInput`: Optional.  Path to the file or object that produced
+        `source`.  Only used for diagnostic output.
+
+    * `destination_class` **required**: The class for dynamically created
+      destination objects.  Typically `io.FileOutput` or `io.StringOutput`.
+
+    * `destination`: Type depends on `destination_class`:
+
+      - `io.FileOutput`: Either a file-like object (must have 'write' and
+        'close' methods), or ``None`` (`destination_path` is opened).  If
+        neither `destination` nor `destination_path` are supplied,
+        `sys.stdout` is used.
+
+      - `io.StringOutput`: Not used; pass ``None``.
+
+    * `destination_path`: Type depends on `destination_class`:
+
+      - `io.FileOutput`: Path to the output file.  Opened if no `destination`
+        supplied.
+
+      - `io.StringOutput`: Path to the file or object which will receive the
+        output; optional.  Used for determining relative paths (stylesheets,
+        source links, etc.).
+
+    * `reader`: A `docutils.readers.Reader` object.
+
+    * `reader_name`: Name or alias of the Reader class to be instantiated if
+      no `reader` supplied.
+
+    * `parser`: A `docutils.parsers.Parser` object.
+
+    * `parser_name`: Name or alias of the Parser class to be instantiated if
+      no `parser` supplied.
+
+    * `writer`: A `docutils.writers.Writer` object.
+
+    * `writer_name`: Name or alias of the Writer class to be instantiated if
+      no `writer` supplied.
+
+    * `settings`: A runtime settings (`docutils.frontend.Values`) object, for
+      dotted-attribute access to runtime settings.  It's the end result of the
+      `SettingsSpec`, config file, and option processing.  If `settings` is
+      passed, it's assumed to be complete and no further setting/config/option
+      processing is done.
+
+    * `settings_spec`: A `docutils.SettingsSpec` subclass or object.  Provides
+      extra application-specific settings definitions independently of
+      components.  In other words, the application becomes a component, and
+      its settings data is processed along with that of the other components.
+      Used only if no `settings` specified.
+
+    * `settings_overrides`: A dictionary containing application-specific
+      settings defaults that override the defaults of other components.
+      Used only if no `settings` specified.
+
+    * `config_section`: A string, the name of the configuration file section
+      for this application.  Overrides the ``config_section`` attribute
+      defined by `settings_spec`.  Used only if no `settings` specified.
+
+    * `enable_exit_status`: Boolean; enable exit status at end of processing?
+    """
+    pub = Publisher(reader, parser, writer, settings=settings,
+                    source_class=source_class,
+                    destination_class=destination_class)
+    pub.set_components(reader_name, parser_name, writer_name)
+    pub.process_programmatic_settings(
+        settings_spec, settings_overrides, config_section)
+    pub.set_source(source, source_path)
+    pub.set_destination(destination, destination_path)
+    output = pub.publish(enable_exit_status=enable_exit_status)
+    return output, pub

docutils/docutils.conf

@@ -0,0 +1,5 @@
+# This configuration file is to prevent tools/buildhtml.py from
+# processing text files in and below this directory.
+
+[buildhtml application]
+prune: .

docutils/examples.py

@@ -0,0 +1,97 @@
+# $Id: examples.py 7320 2012-01-19 22:33:02Z milde $
+# Author: David Goodger <goodger@python.org>
+# Copyright: This module has been placed in the public domain.
+
+"""
+This module contains practical examples of Docutils client code.
+
+Importing this module from client code is not recommended; its contents are
+subject to change in future Docutils releases.  Instead, it is recommended
+that you copy and paste the parts you need into your own code, modifying as
+necessary.
+"""
+
+from docutils import core, io
+
+
+def html_parts(input_string, source_path=None, destination_path=None,
+               input_encoding='unicode', doctitle=True,
+               initial_header_level=1):
+    """
+    Given an input string, returns a dictionary of HTML document parts.
+
+    Dictionary keys are the names of parts, and values are Unicode strings;
+    encoding is up to the client.
+
+    Parameters:
+
+    - `input_string`: A multi-line text string; required.
+    - `source_path`: Path to the source file or object.  Optional, but useful
+      for diagnostic output (system messages).
+    - `destination_path`: Path to the file or object which will receive the
+      output; optional.  Used for determining relative paths (stylesheets,
+      source links, etc.).
+    - `input_encoding`: The encoding of `input_string`.  If it is an encoded
+      8-bit string, provide the correct encoding.  If it is a Unicode string,
+      use "unicode", the default.
+    - `doctitle`: Disable the promotion of a lone top-level section title to
+      document title (and subsequent section title to document subtitle
+      promotion); enabled by default.
+    - `initial_header_level`: The initial level for header elements (e.g. 1
+      for "<h1>").
+    """
+    overrides = {'input_encoding': input_encoding,
+                 'doctitle_xform': doctitle,
+                 'initial_header_level': initial_header_level}
+    parts = core.publish_parts(
+        source=input_string, source_path=source_path,
+        destination_path=destination_path,
+        writer_name='html', settings_overrides=overrides)
+    return parts
+
+def html_body(input_string, source_path=None, destination_path=None,
+              input_encoding='unicode', output_encoding='unicode',
+              doctitle=True, initial_header_level=1):
+    """
+    Given an input string, returns an HTML fragment as a string.
+
+    The return value is the contents of the <body> element.
+
+    Parameters (see `html_parts()` for the remainder):
+
+    - `output_encoding`: The desired encoding of the output.  If a Unicode
+      string is desired, use the default value of "unicode" .
+    """
+    parts = html_parts(
+        input_string=input_string, source_path=source_path,
+        destination_path=destination_path,
+        input_encoding=input_encoding, doctitle=doctitle,
+        initial_header_level=initial_header_level)
+    fragment = parts['html_body']
+    if output_encoding != 'unicode':
+        fragment = fragment.encode(output_encoding)
+    return fragment
+
+def internals(input_string, source_path=None, destination_path=None,
+              input_encoding='unicode', settings_overrides=None):
+    """
+    Return the document tree and publisher, for exploring Docutils internals.
+
+    Parameters: see `html_parts()`.
+    """
+    if settings_overrides:
+        overrides = settings_overrides.copy()
+    else:
+        overrides = {}
+    overrides['input_encoding'] = input_encoding
+    output, pub = core.publish_programmatically(
+        source_class=io.StringInput, source=input_string,
+        source_path=source_path,
+        destination_class=io.NullOutput, destination=None,
+        destination_path=destination_path,
+        reader=None, reader_name='standalone',
+        parser=None, parser_name='restructuredtext',
+        writer=None, writer_name='null',
+        settings=None, settings_spec=None, settings_overrides=overrides,
+        config_section=None, enable_exit_status=None)
+    return pub.writer.document, pub

docutils/frontend.py

@@ -0,0 +1,859 @@
+# $Id: frontend.py 8126 2017-06-23 09:34:28Z milde $
+# Author: David Goodger <goodger@python.org>
+# Copyright: This module has been placed in the public domain.
+
+"""
+Command-line and common processing for Docutils front-end tools.
+
+Exports the following classes:
+
+* `OptionParser`: Standard Docutils command-line processing.
+* `Option`: Customized version of `optparse.Option`; validation support.
+* `Values`: Runtime settings; objects are simple structs
+  (``object.attribute``).  Supports cumulative list settings (attributes).
+* `ConfigParser`: Standard Docutils config file processing.
+
+Also exports the following functions:
+
+* Option callbacks: `store_multiple`, `read_config_file`.
+* Setting validators: `validate_encoding`,
+  `validate_encoding_error_handler`,
+  `validate_encoding_and_error_handler`,
+  `validate_boolean`, `validate_ternary`, `validate_threshold`,
+  `validate_colon_separated_string_list`,
+  `validate_comma_separated_string_list`,
+  `validate_dependency_file`.
+* `make_paths_absolute`.
+* SettingSpec manipulation: `filter_settings_spec`.
+"""
+
+__docformat__ = 'reStructuredText'
+
+import os
+import os.path
+import sys
+import warnings
+import ConfigParser as CP
+import codecs
+import optparse
+from optparse import SUPPRESS_HELP
+import docutils
+import docutils.utils
+import docutils.nodes
+from docutils.utils.error_reporting import (locale_encoding, SafeString,
+                                            ErrorOutput, ErrorString)
+
+
+def store_multiple(option, opt, value, parser, *args, **kwargs):
+    """
+    Store multiple values in `parser.values`.  (Option callback.)
+
+    Store `None` for each attribute named in `args`, and store the value for
+    each key (attribute name) in `kwargs`.
+    """
+    for attribute in args:
+        setattr(parser.values, attribute, None)
+    for key, value in kwargs.items():
+        setattr(parser.values, key, value)
+
+def read_config_file(option, opt, value, parser):
+    """
+    Read a configuration file during option processing.  (Option callback.)
+    """
+    try:
+        new_settings = parser.get_config_file_settings(value)
+    except ValueError, error:
+        parser.error(error)
+    parser.values.update(new_settings, parser)
+
+def validate_encoding(setting, value, option_parser,
+                      config_parser=None, config_section=None):
+    try:
+        codecs.lookup(value)
+    except LookupError:
+        raise (LookupError('setting "%s": unknown encoding: "%s"'
+                           % (setting, value)),
+               None, sys.exc_info()[2])
+    return value
+
+def validate_encoding_error_handler(setting, value, option_parser,
+                                    config_parser=None, config_section=None):
+    try:
+        codecs.lookup_error(value)
+    except LookupError:
+        raise (LookupError(
+            'unknown encoding error handler: "%s" (choices: '
+            '"strict", "ignore", "replace", "backslashreplace", '
+            '"xmlcharrefreplace", and possibly others; see documentation for '
+            'the Python ``codecs`` module)' % value),
+               None, sys.exc_info()[2])
+    return value
+
+def validate_encoding_and_error_handler(
+    setting, value, option_parser, config_parser=None, config_section=None):
+    """
+    Side-effect: if an error handler is included in the value, it is inserted
+    into the appropriate place as if it was a separate setting/option.
+    """
+    if ':' in value:
+        encoding, handler = value.split(':')
+        validate_encoding_error_handler(
+            setting + '_error_handler', handler, option_parser,
+            config_parser, config_section)
+        if config_parser:
+            config_parser.set(config_section, setting + '_error_handler',
+                              handler)
+        else:
+            setattr(option_parser.values, setting + '_error_handler', handler)
+    else:
+        encoding = value
+    validate_encoding(setting, encoding, option_parser,
+                      config_parser, config_section)
+    return encoding
+
+def validate_boolean(setting, value, option_parser,
+                     config_parser=None, config_section=None):
+    """Check/normalize boolean settings:
+         True:  '1', 'on', 'yes', 'true'
+         False: '0', 'off', 'no','false', ''
+    """
+    if isinstance(value, bool):
+        return value
+    try:
+        return option_parser.booleans[value.strip().lower()]
+    except KeyError:
+        raise (LookupError('unknown boolean value: "%s"' % value),
+               None, sys.exc_info()[2])
+
+def validate_ternary(setting, value, option_parser,
+                     config_parser=None, config_section=None):
+    """Check/normalize three-value settings:
+         True:  '1', 'on', 'yes', 'true'
+         False: '0', 'off', 'no','false', ''
+         any other value: returned as-is.
+    """
+    if isinstance(value, bool) or value is None:
+        return value
+    try:
+        return option_parser.booleans[value.strip().lower()]
+    except KeyError:
+        return value
+
+def validate_nonnegative_int(setting, value, option_parser,
+                             config_parser=None, config_section=None):
+    value = int(value)
+    if value < 0:
+        raise ValueError('negative value; must be positive or zero')
+    return value
+
+def validate_threshold(setting, value, option_parser,
+                       config_parser=None, config_section=None):
+    try:
+        return int(value)
+    except ValueError:
+        try:
+            return option_parser.thresholds[value.lower()]
+        except (KeyError, AttributeError):
+            raise (LookupError('unknown threshold: %r.' % value),
+                   None, sys.exc_info[2])
+
+def validate_colon_separated_string_list(
+    setting, value, option_parser, config_parser=None, config_section=None):
+    if not isinstance(value, list):
+        value = value.split(':')
+    else:
+        last = value.pop()
+        value.extend(last.split(':'))
+    return value
+
+def validate_comma_separated_list(setting, value, option_parser,
+                                    config_parser=None, config_section=None):
+    """Check/normalize list arguments (split at "," and strip whitespace).
+    """
+    # `value` is already a ``list`` when  given as command line option
+    # and "action" is "append" and ``unicode`` or ``str`` else.
+    if not isinstance(value, list):
+        value = [value]
+    # this function is called for every option added to `value`
+    # -> split the last item and append the result:
+    last = value.pop()
+    items = [i.strip(u' \t\n') for i in last.split(u',') if i.strip(u' \t\n')]
+    value.extend(items)
+    return value
+
+def validate_url_trailing_slash(
+    setting, value, option_parser, config_parser=None, config_section=None):
+    if not value:
+        return './'
+    elif value.endswith('/'):
+        return value
+    else:
+        return value + '/'
+
+def validate_dependency_file(setting, value, option_parser,
+                             config_parser=None, config_section=None):
+    try:
+        return docutils.utils.DependencyList(value)
+    except IOError:
+        return docutils.utils.DependencyList(None)
+
+def validate_strip_class(setting, value, option_parser,
+                         config_parser=None, config_section=None):
+    # value is a comma separated string list:
+    value = validate_comma_separated_list(setting, value, option_parser,
+                                          config_parser, config_section)
+    # validate list elements:
+    for cls in value:
+        normalized = docutils.nodes.make_id(cls)
+        if cls != normalized:
+            raise ValueError('Invalid class value %r (perhaps %r?)'
+                             % (cls, normalized))
+    return value
+
+def validate_smartquotes_locales(setting, value, option_parser,
+                         config_parser=None, config_section=None):
+    """Check/normalize a comma separated list of smart quote definitions.
+
+    Return a list of (language-tag, quotes) string tuples."""
+
+    # value is a comma separated string list:
+    value = validate_comma_separated_list(setting, value, option_parser,
+                                          config_parser, config_section)
+    # validate list elements
+    lc_quotes = []
+    for item in value:
+        try:
+            lang, quotes = item.split(':', 1)
+        except AttributeError:
+            # this function is called for every option added to `value`
+            # -> ignore if already a tuple:
+            lc_quotes.append(item)
+            continue
+        except ValueError:
+            raise ValueError(u'Invalid value "%s".'
+                             ' Format is "<language>:<quotes>".'
+                             % item.encode('ascii', 'backslashreplace'))
+        # parse colon separated string list:
+        quotes = quotes.strip()
+        multichar_quotes = quotes.split(':')
+        if len(multichar_quotes) == 4:
+            quotes = multichar_quotes
+        elif len(quotes) != 4:
+            raise ValueError('Invalid value "%s". Please specify 4 quotes\n'
+                '    (primary open/close; secondary open/close).'
+                             % item.encode('ascii', 'backslashreplace'))
+        lc_quotes.append((lang,quotes))
+    return lc_quotes
+
+def make_paths_absolute(pathdict, keys, base_path=None):
+    """
+    Interpret filesystem path settings relative to the `base_path` given.
+
+    Paths are values in `pathdict` whose keys are in `keys`.  Get `keys` from
+    `OptionParser.relative_path_settings`.
+    """
+    if base_path is None:
+        base_path = os.getcwdu() # type(base_path) == unicode
+        # to allow combining non-ASCII cwd with unicode values in `pathdict`
+    for key in keys:
+        if key in pathdict:
+            value = pathdict[key]
+            if isinstance(value, list):
+                value = [make_one_path_absolute(base_path, path)
+                         for path in value]
+            elif value:
+                value = make_one_path_absolute(base_path, value)
+            pathdict[key] = value
+
+def make_one_path_absolute(base_path, path):
+    return os.path.abspath(os.path.join(base_path, path))
+
+def filter_settings_spec(settings_spec, *exclude, **replace):
+    """Return a copy of `settings_spec` excluding/replacing some settings.
+
+    `settings_spec` is a tuple of configuration settings with a structure
+    described for docutils.SettingsSpec.settings_spec.
+
+    Optional positional arguments are names of to-be-excluded settings.
+    Keyword arguments are option specification replacements.
+    (See the html4strict writer for an example.)
+    """
+    settings = list(settings_spec)
+    # every third item is a sequence of option tuples
+    for i in range(2, len(settings), 3):
+        newopts = []
+        for opt_spec in settings[i]:
+            # opt_spec is ("<help>", [<option strings>], {<keyword args>})
+            opt_name = [opt_string[2:].replace('-', '_')
+                        for opt_string in opt_spec[1]
+                            if opt_string.startswith('--')
+                       ][0]
+            if opt_name in exclude:
+                continue
+            if opt_name in replace.keys():
+                newopts.append(replace[opt_name])
+            else:
+                newopts.append(opt_spec)
+        settings[i] = tuple(newopts)
+    return tuple(settings)
+
+
+class Values(optparse.Values):
+
+    """
+    Updates list attributes by extension rather than by replacement.
+    Works in conjunction with the `OptionParser.lists` instance attribute.
+    """
+
+    def __init__(self, *args, **kwargs):
+        optparse.Values.__init__(self, *args, **kwargs)
+        if (not hasattr(self, 'record_dependencies')
+            or self.record_dependencies is None):
+            # Set up dependency list, in case it is needed.
+            self.record_dependencies = docutils.utils.DependencyList()
+
+    def update(self, other_dict, option_parser):
+        if isinstance(other_dict, Values):
+            other_dict = other_dict.__dict__
+        other_dict = other_dict.copy()
+        for setting in option_parser.lists.keys():
+            if (hasattr(self, setting) and setting in other_dict):
+                value = getattr(self, setting)
+                if value:
+                    value += other_dict[setting]
+                    del other_dict[setting]
+        self._update_loose(other_dict)
+
+    def copy(self):
+        """Return a shallow copy of `self`."""
+        return self.__class__(defaults=self.__dict__)
+
+
+class Option(optparse.Option):
+
+    ATTRS = optparse.Option.ATTRS + ['validator', 'overrides']
+
+    def process(self, opt, value, values, parser):
+        """
+        Call the validator function on applicable settings and
+        evaluate the 'overrides' option.
+        Extends `optparse.Option.process`.
+        """
+        result = optparse.Option.process(self, opt, value, values, parser)
+        setting = self.dest
+        if setting:
+            if self.validator:
+                value = getattr(values, setting)
+                try:
+                    new_value = self.validator(setting, value, parser)
+                except Exception, error:
+                    raise (optparse.OptionValueError(
+                        'Error in option "%s":\n    %s'
+                        % (opt, ErrorString(error))),
+                           None, sys.exc_info()[2])
+                setattr(values, setting, new_value)
+            if self.overrides:
+                setattr(values, self.overrides, None)
+        return result
+
+
+class OptionParser(optparse.OptionParser, docutils.SettingsSpec):
+
+    """
+    Parser for command-line and library use.  The `settings_spec`
+    specification here and in other Docutils components are merged to build
+    the set of command-line options and runtime settings for this process.
+
+    Common settings (defined below) and component-specific settings must not
+    conflict.  Short options are reserved for common settings, and components
+    are restrict to using long options.
+    """
+
+    standard_config_files = [
+        '/etc/docutils.conf',           # system-wide
+        './docutils.conf',              # project-specific
+        '~/.docutils']                  # user-specific
+    """Docutils configuration files, using ConfigParser syntax.  Filenames
+    will be tilde-expanded later.  Later files override earlier ones."""
+
+    threshold_choices = 'info 1 warning 2 error 3 severe 4 none 5'.split()
+    """Possible inputs for for --report and --halt threshold values."""
+
+    thresholds = {'info': 1, 'warning': 2, 'error': 3, 'severe': 4, 'none': 5}
+    """Lookup table for --report and --halt threshold values."""
+
+    booleans={'1': True, 'on': True, 'yes': True, 'true': True,
+              '0': False, 'off': False, 'no': False, 'false': False, '': False}
+    """Lookup table for boolean configuration file settings."""
+
+    default_error_encoding = getattr(sys.stderr, 'encoding',
+                                     None) or locale_encoding or 'ascii'
+
+    default_error_encoding_error_handler = 'backslashreplace'
+
+    settings_spec = (
+        'General Docutils Options',
+        None,
+        (('Specify the document title as metadata.',
+          ['--title'], {}),
+         ('Include a "Generated by Docutils" credit and link.',
+          ['--generator', '-g'], {'action': 'store_true',
+                                  'validator': validate_boolean}),
+         ('Do not include a generator credit.',
+          ['--no-generator'], {'action': 'store_false', 'dest': 'generator'}),
+         ('Include the date at the end of the document (UTC).',
+          ['--date', '-d'], {'action': 'store_const', 'const': '%Y-%m-%d',
+                             'dest': 'datestamp'}),
+         ('Include the time & date (UTC).',
+          ['--time', '-t'], {'action': 'store_const',
+                             'const': '%Y-%m-%d %H:%M UTC',
+                             'dest': 'datestamp'}),
+         ('Do not include a datestamp of any kind.',
+          ['--no-datestamp'], {'action': 'store_const', 'const': None,
+                               'dest': 'datestamp'}),
+         ('Include a "View document source" link.',
+          ['--source-link', '-s'], {'action': 'store_true',
+                                    'validator': validate_boolean}),
+         ('Use <URL> for a source link; implies --source-link.',
+          ['--source-url'], {'metavar': '<URL>'}),
+         ('Do not include a "View document source" link.',
+          ['--no-source-link'],
+          {'action': 'callback', 'callback': store_multiple,
+           'callback_args': ('source_link', 'source_url')}),
+         ('Link from section headers to TOC entries.  (default)',
+          ['--toc-entry-backlinks'],
+          {'dest': 'toc_backlinks', 'action': 'store_const', 'const': 'entry',
+           'default': 'entry'}),
+         ('Link from section headers to the top of the TOC.',
+          ['--toc-top-backlinks'],
+          {'dest': 'toc_backlinks', 'action': 'store_const', 'const': 'top'}),
+         ('Disable backlinks to the table of contents.',
+          ['--no-toc-backlinks'],
+          {'dest': 'toc_backlinks', 'action': 'store_false'}),
+         ('Link from footnotes/citations to references. (default)',
+          ['--footnote-backlinks'],
+          {'action': 'store_true', 'default': 1,
+           'validator': validate_boolean}),
+         ('Disable backlinks from footnotes and citations.',
+          ['--no-footnote-backlinks'],
+          {'dest': 'footnote_backlinks', 'action': 'store_false'}),
+         ('Enable section numbering by Docutils.  (default)',
+          ['--section-numbering'],
+          {'action': 'store_true', 'dest': 'sectnum_xform',
+           'default': 1, 'validator': validate_boolean}),
+         ('Disable section numbering by Docutils.',
+          ['--no-section-numbering'],
+          {'action': 'store_false', 'dest': 'sectnum_xform'}),
+         ('Remove comment elements from the document tree.',
+          ['--strip-comments'],
+          {'action': 'store_true', 'validator': validate_boolean}),
+         ('Leave comment elements in the document tree. (default)',
+          ['--leave-comments'],
+          {'action': 'store_false', 'dest': 'strip_comments'}),
+         ('Remove all elements with classes="<class>" from the document tree. '
+          'Warning: potentially dangerous; use with caution. '
+          '(Multiple-use option.)',
+          ['--strip-elements-with-class'],
+          {'action': 'append', 'dest': 'strip_elements_with_classes',
+           'metavar': '<class>', 'validator': validate_strip_class}),
+         ('Remove all classes="<class>" attributes from elements in the '
+          'document tree. Warning: potentially dangerous; use with caution. '
+          '(Multiple-use option.)',
+          ['--strip-class'],
+          {'action': 'append', 'dest': 'strip_classes',
+           'metavar': '<class>', 'validator': validate_strip_class}),
+         ('Report system messages at or higher than <level>: "info" or "1", '
+          '"warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5"',
+          ['--report', '-r'], {'choices': threshold_choices, 'default': 2,
+                               'dest': 'report_level', 'metavar': '<level>',
+                               'validator': validate_threshold}),
+         ('Report all system messages.  (Same as "--report=1".)',
+          ['--verbose', '-v'], {'action': 'store_const', 'const': 1,
+                                'dest': 'report_level'}),
+         ('Report no system messages.  (Same as "--report=5".)',
+          ['--quiet', '-q'], {'action': 'store_const', 'const': 5,
+                              'dest': 'report_level'}),
+         ('Halt execution at system messages at or above <level>.  '
+          'Levels as in --report.  Default: 4 (severe).',
+          ['--halt'], {'choices': threshold_choices, 'dest': 'halt_level',
+                       'default': 4, 'metavar': '<level>',
+                       'validator': validate_threshold}),
+         ('Halt at the slightest problem.  Same as "--halt=info".',
+          ['--strict'], {'action': 'store_const', 'const': 1,
+                         'dest': 'halt_level'}),
+         ('Enable a non-zero exit status for non-halting system messages at '
+          'or above <level>.  Default: 5 (disabled).',
+          ['--exit-status'], {'choices': threshold_choices,
+                              'dest': 'exit_status_level',
+                              'default': 5, 'metavar': '<level>',
+                              'validator': validate_threshold}),
+         ('Enable debug-level system messages and diagnostics.',
+          ['--debug'], {'action': 'store_true', 'validator': validate_boolean}),
+         ('Disable debug output.  (default)',
+          ['--no-debug'], {'action': 'store_false', 'dest': 'debug'}),
+         ('Send the output of system messages to <file>.',
+          ['--warnings'], {'dest': 'warning_stream', 'metavar': '<file>'}),
+         ('Enable Python tracebacks when Docutils is halted.',
+          ['--traceback'], {'action': 'store_true', 'default': None,
+                            'validator': validate_boolean}),
+         ('Disable Python tracebacks.  (default)',
+          ['--no-traceback'], {'dest': 'traceback', 'action': 'store_false'}),
+         ('Specify the encoding and optionally the '
+          'error handler of input text.  Default: <locale-dependent>:strict.',
+          ['--input-encoding', '-i'],
+          {'metavar': '<name[:handler]>',
+           'validator': validate_encoding_and_error_handler}),
+         ('Specify the error handler for undecodable characters.  '
+          'Choices: "strict" (default), "ignore", and "replace".',
+          ['--input-encoding-error-handler'],
+          {'default': 'strict', 'validator': validate_encoding_error_handler}),
+         ('Specify the text encoding and optionally the error handler for '
+          'output.  Default: UTF-8:strict.',
+          ['--output-encoding', '-o'],
+          {'metavar': '<name[:handler]>', 'default': 'utf-8',
+           'validator': validate_encoding_and_error_handler}),
+         ('Specify error handler for unencodable output characters; '
+          '"strict" (default), "ignore", "replace", '
+          '"xmlcharrefreplace", "backslashreplace".',
+          ['--output-encoding-error-handler'],
+          {'default': 'strict', 'validator': validate_encoding_error_handler}),
+         ('Specify text encoding and error handler for error output.  '
+          'Default: %s:%s.'
+          % (default_error_encoding, default_error_encoding_error_handler),
+          ['--error-encoding', '-e'],
+          {'metavar': '<name[:handler]>', 'default': default_error_encoding,
+           'validator': validate_encoding_and_error_handler}),
+         ('Specify the error handler for unencodable characters in '
+          'error output.  Default: %s.'
+          % default_error_encoding_error_handler,
+          ['--error-encoding-error-handler'],
+          {'default': default_error_encoding_error_handler,
+           'validator': validate_encoding_error_handler}),
+         ('Specify the language (as BCP 47 language tag).  Default: en.',
+          ['--language', '-l'], {'dest': 'language_code', 'default': 'en',
+                                 'metavar': '<name>'}),
+         ('Write output file dependencies to <file>.',
+          ['--record-dependencies'],
+          {'metavar': '<file>', 'validator': validate_dependency_file,
+           'default': None}),           # default set in Values class
+         ('Read configuration settings from <file>, if it exists.',
+          ['--config'], {'metavar': '<file>', 'type': 'string',
+                         'action': 'callback', 'callback': read_config_file}),
+         ("Show this program's version number and exit.",
+          ['--version', '-V'], {'action': 'version'}),
+         ('Show this help message and exit.',
+          ['--help', '-h'], {'action': 'help'}),
+         # Typically not useful for non-programmatical use:
+         (SUPPRESS_HELP, ['--id-prefix'], {'default': ''}),
+         (SUPPRESS_HELP, ['--auto-id-prefix'], {'default': 'id'}),
+         # Hidden options, for development use only:
+         (SUPPRESS_HELP, ['--dump-settings'], {'action': 'store_true'}),
+         (SUPPRESS_HELP, ['--dump-internals'], {'action': 'store_true'}),
+         (SUPPRESS_HELP, ['--dump-transforms'], {'action': 'store_true'}),
+         (SUPPRESS_HELP, ['--dump-pseudo-xml'], {'action': 'store_true'}),
+         (SUPPRESS_HELP, ['--expose-internal-attribute'],
+          {'action': 'append', 'dest': 'expose_internals',
+           'validator': validate_colon_separated_string_list}),
+         (SUPPRESS_HELP, ['--strict-visitor'], {'action': 'store_true'}),
+         ))
+    """Runtime settings and command-line options common to all Docutils front
+    ends.  Setting specs specific to individual Docutils components are also
+    used (see `populate_from_components()`)."""
+
+    settings_defaults = {'_disable_config': None,
+                         '_source': None,
+                         '_destination': None,
+                         '_config_files': None}
+    """Defaults for settings that don't have command-line option equivalents."""
+
+    relative_path_settings = ('warning_stream',)
+
+    config_section = 'general'
+
+    version_template = ('%%prog (Docutils %s%s, Python %s, on %s)'
+                        % (docutils.__version__,
+                           docutils.__version_details__ and
+                           ' [%s]'%docutils.__version_details__ or '',
+                           sys.version.split()[0], sys.platform))
+    """Default version message."""
+
+    def __init__(self, components=(), defaults=None, read_config_files=None,
+                 *args, **kwargs):
+        """
+        `components` is a list of Docutils components each containing a
+        ``.settings_spec`` attribute.  `defaults` is a mapping of setting
+        default overrides.
+        """
+
+        self.lists = {}
+        """Set of list-type settings."""
+
+        self.config_files = []
+        """List of paths of applied configuration files."""
+
+        optparse.OptionParser.__init__(
+            self, option_class=Option, add_help_option=None,
+            formatter=optparse.TitledHelpFormatter(width=78),
+            *args, **kwargs)
+        if not self.version:
+            self.version = self.version_template
+        # Make an instance copy (it will be modified):
+        self.relative_path_settings = list(self.relative_path_settings)
+        self.components = (self,) + tuple(components)
+        self.populate_from_components(self.components)
+        self.set_defaults_from_dict(defaults or {})
+        if read_config_files and not self.defaults['_disable_config']:
+            try:
+                config_settings = self.get_standard_config_settings()
+            except ValueError, error:
+                self.error(SafeString(error))
+            self.set_defaults_from_dict(config_settings.__dict__)
+
+    def populate_from_components(self, components):
+        """
+        For each component, first populate from the `SettingsSpec.settings_spec`
+        structure, then from the `SettingsSpec.settings_defaults` dictionary.
+        After all components have been processed, check for and populate from
+        each component's `SettingsSpec.settings_default_overrides` dictionary.
+        """
+        for component in components:
+            if component is None:
+                continue
+            settings_spec = component.settings_spec
+            self.relative_path_settings.extend(
+                component.relative_path_settings)
+            for i in range(0, len(settings_spec), 3):
+                title, description, option_spec = settings_spec[i:i+3]
+                if title:
+                    group = optparse.OptionGroup(self, title, description)
+                    self.add_option_group(group)
+                else:
+                    group = self        # single options
+                for (help_text, option_strings, kwargs) in option_spec:
+                    option = group.add_option(help=help_text, *option_strings,
+                                              **kwargs)
+                    if kwargs.get('action') == 'append':
+                        self.lists[option.dest] = 1
+                if component.settings_defaults:
+                    self.defaults.update(component.settings_defaults)
+        for component in components:
+            if component and component.settings_default_overrides:
+                self.defaults.update(component.settings_default_overrides)
+
+    def get_standard_config_files(self):
+        """Return list of config files, from environment or standard."""
+        try:
+            config_files = os.environ['DOCUTILSCONFIG'].split(os.pathsep)
+        except KeyError:
+            config_files = self.standard_config_files
+
+        # If 'HOME' is not set, expandvars() requires the 'pwd' module which is
+        # not available under certain environments, for example, within
+        # mod_python.  The publisher ends up in here, and we need to publish
+        # from within mod_python.  Therefore we need to avoid expanding when we
+        # are in those environments.
+        expand = os.path.expanduser
+        if 'HOME' not in os.environ:
+            try:
+                import pwd
+            except ImportError:
+                expand = lambda x: x
+        return [expand(f) for f in config_files if f.strip()]
+
+    def get_standard_config_settings(self):
+        settings = Values()
+        for filename in self.get_standard_config_files():
+            settings.update(self.get_config_file_settings(filename), self)
+        return settings
+
+    def get_config_file_settings(self, config_file):
+        """Returns a dictionary containing appropriate config file settings."""
+        parser = ConfigParser()
+        parser.read(config_file, self)
+        self.config_files.extend(parser._files)
+        base_path = os.path.dirname(config_file)
+        applied = {}
+        settings = Values()
+        for component in self.components:
+            if not component:
+                continue
+            for section in (tuple(component.config_section_dependencies or ())
+                            + (component.config_section,)):
+                if section in applied:
+                    continue
+                applied[section] = 1
+                settings.update(parser.get_section(section), self)
+        make_paths_absolute(
+            settings.__dict__, self.relative_path_settings, base_path)
+        return settings.__dict__
+
+    def check_values(self, values, args):
+        """Store positional arguments as runtime settings."""
+        values._source, values._destination = self.check_args(args)
+        make_paths_absolute(values.__dict__, self.relative_path_settings)
+        values._config_files = self.config_files
+        return values
+
+    def check_args(self, args):
+        source = destination = None
+        if args:
+            source = args.pop(0)
+            if source == '-':           # means stdin
+                source = None
+        if args:
+            destination = args.pop(0)
+            if destination == '-':      # means stdout
+                destination = None
+        if args:
+            self.error('Maximum 2 arguments allowed.')
+        if source and source == destination:
+            self.error('Do not specify the same file for both source and '
+                       'destination.  It will clobber the source file.')
+        return source, destination
+
+    def set_defaults_from_dict(self, defaults):
+        self.defaults.update(defaults)
+
+    def get_default_values(self):
+        """Needed to get custom `Values` instances."""
+        defaults = Values(self.defaults)
+        defaults._config_files = self.config_files
+        return defaults
+
+    def get_option_by_dest(self, dest):
+        """
+        Get an option by its dest.
+
+        If you're supplying a dest which is shared by several options,
+        it is undefined which option of those is returned.
+
+        A KeyError is raised if there is no option with the supplied
+        dest.
+        """
+        for group in self.option_groups + [self]:
+            for option in group.option_list:
+                if option.dest == dest:
+                    return option
+        raise KeyError('No option with dest == %r.' % dest)
+
+
+class ConfigParser(CP.RawConfigParser):
+
+    old_settings = {
+        'pep_stylesheet': ('pep_html writer', 'stylesheet'),
+        'pep_stylesheet_path': ('pep_html writer', 'stylesheet_path'),
+        'pep_template': ('pep_html writer', 'template')}
+    """{old setting: (new section, new setting)} mapping, used by
+    `handle_old_config`, to convert settings from the old [options] section."""
+
+    old_warning = """
+The "[option]" section is deprecated.  Support for old-format configuration
+files may be removed in a future Docutils release.  Please revise your
+configuration files.  See <http://docutils.sf.net/docs/user/config.html>,
+section "Old-Format Configuration Files".
+"""
+
+    not_utf8_error = """\
+Unable to read configuration file "%s": content not encoded as UTF-8.
+Skipping "%s" configuration file.
+"""
+
+    def __init__(self, *args, **kwargs):
+        CP.RawConfigParser.__init__(self, *args, **kwargs)
+
+        self._files = []
+        """List of paths of configuration files read."""
+
+        self._stderr = ErrorOutput()
+        """Wrapper around sys.stderr catching en-/decoding errors"""
+
+    def read(self, filenames, option_parser):
+        if type(filenames) in (str, unicode):
+            filenames = [filenames]
+        for filename in filenames:
+            try:
+                # Config files must be UTF-8-encoded:
+                fp = codecs.open(filename, 'r', 'utf-8')
+            except IOError:
+                continue
+            try:
+                if sys.version_info < (3,2):
+                    CP.RawConfigParser.readfp(self, fp, filename)
+                else:
+                    CP.RawConfigParser.read_file(self, fp, filename)
+            except UnicodeDecodeError:
+                self._stderr.write(self.not_utf8_error % (filename, filename))
+                fp.close()
+                continue
+            fp.close()
+            self._files.append(filename)
+            if self.has_section('options'):
+                self.handle_old_config(filename)
+            self.validate_settings(filename, option_parser)
+
+    def handle_old_config(self, filename):
+        warnings.warn_explicit(self.old_warning, ConfigDeprecationWarning,
+                               filename, 0)
+        options = self.get_section('options')
+        if not self.has_section('general'):
+            self.add_section('general')
+        for key, value in options.items():
+            if key in self.old_settings:
+                section, setting = self.old_settings[key]
+                if not self.has_section(section):
+                    self.add_section(section)
+            else:
+                section = 'general'
+                setting = key
+            if not self.has_option(section, setting):
+                self.set(section, setting, value)
+        self.remove_section('options')
+
+    def validate_settings(self, filename, option_parser):
+        """
+        Call the validator function and implement overrides on all applicable
+        settings.
+        """
+        for section in self.sections():
+            for setting in self.options(section):
+                try:
+                    option = option_parser.get_option_by_dest(setting)
+                except KeyError:
+                    continue
+                if option.validator:
+                    value = self.get(section, setting)
+                    try:
+                        new_value = option.validator(
+                            setting, value, option_parser,
+                            config_parser=self, config_section=section)
+                    except Exception, error:
+                        raise (ValueError(
+                            'Error in config file "%s", section "[%s]":\n'
+                            '    %s\n'
+                            '        %s = %s'
+                            % (filename, section, ErrorString(error),
+                               setting, value)), None, sys.exc_info()[2])
+                    self.set(section, setting, new_value)
+                if option.overrides:
+                    self.set(section, option.overrides, None)
+
+    def optionxform(self, optionstr):
+        """
+        Transform '-' to '_' so the cmdline form of option names can be used.
+        """
+        return optionstr.lower().replace('-', '_')
+
+    def get_section(self, section):
+        """
+        Return a given section as a dictionary (empty if the section
+        doesn't exist).
+        """
+        section_dict = {}
+        if self.has_section(section):
+            for option in self.options(section):
+                section_dict[option] = self.get(section, option)
+        return section_dict
+
+
+class ConfigDeprecationWarning(DeprecationWarning):
+    """Warning for deprecated configuration file features."""

docutils/io.py

@@ -0,0 +1,490 @@
+# $Id: io.py 8129 2017-06-27 14:55:22Z grubert $
+# Author: David Goodger <goodger@python.org>
+# Copyright: This module has been placed in the public domain.
+
+"""
+I/O classes provide a uniform API for low-level input and output.  Subclasses
+exist for a variety of input/output mechanisms.
+"""
+
+__docformat__ = 'reStructuredText'
+
+import sys
+import os
+import re
+import codecs
+from docutils import TransformSpec
+from docutils._compat import b
+from docutils.utils.error_reporting import locale_encoding, ErrorString, ErrorOutput
+
+
+class InputError(IOError): pass
+class OutputError(IOError): pass
+
+def check_encoding(stream, encoding):
+    """Test, whether the encoding of `stream` matches `encoding`.
+
+    Returns
+
+    :None:  if `encoding` or `stream.encoding` are not a valid encoding
+            argument (e.g. ``None``) or `stream.encoding is missing.
+    :True:  if the encoding argument resolves to the same value as `encoding`,
+    :False: if the encodings differ.
+    """
+    try:
+        return codecs.lookup(stream.encoding) == codecs.lookup(encoding)
+    except (LookupError, AttributeError, TypeError):
+        return None
+
+
+class Input(TransformSpec):
+
+    """
+    Abstract base class for input wrappers.
+    """
+
+    component_type = 'input'
+
+    default_source_path = None
+
+    def __init__(self, source=None, source_path=None, encoding=None,
+                 error_handler='strict'):
+        self.encoding = encoding
+        """Text encoding for the input source."""
+
+        self.error_handler = error_handler
+        """Text decoding error handler."""
+
+        self.source = source
+        """The source of input data."""
+
+        self.source_path = source_path
+        """A text reference to the source."""
+
+        if not source_path:
+            self.source_path = self.default_source_path
+
+        self.successful_encoding = None
+        """The encoding that successfully decoded the source data."""
+
+    def __repr__(self):
+        return '%s: source=%r, source_path=%r' % (self.__class__, self.source,
+                                                  self.source_path)
+
+    def read(self):
+        raise NotImplementedError
+
+    def decode(self, data):
+        """
+        Decode a string, `data`, heuristically.
+        Raise UnicodeError if unsuccessful.
+
+        The client application should call ``locale.setlocale`` at the
+        beginning of processing::
+
+            locale.setlocale(locale.LC_ALL, '')
+        """
+        if self.encoding and self.encoding.lower() == 'unicode':
+            assert isinstance(data, unicode), (
+                'input encoding is "unicode" '
+                'but input is not a unicode object')
+        if isinstance(data, unicode):
+            # Accept unicode even if self.encoding != 'unicode'.
+            return data
+        if self.encoding:
+            # We believe the user/application when the encoding is
+            # explicitly given.
+            encodings = [self.encoding]
+        else:
+            data_encoding = self.determine_encoding_from_data(data)
+            if data_encoding:
+                # If the data declares its encoding (explicitly or via a BOM),
+                # we believe it.
+                encodings = [data_encoding]
+            else:
+                # Apply heuristics only if no encoding is explicitly given and
+                # no BOM found.  Start with UTF-8, because that only matches
+                # data that *IS* UTF-8:
+                encodings = ['utf-8', 'latin-1']
+                if locale_encoding:
+                    encodings.insert(1, locale_encoding)
+        for enc in encodings:
+            try:
+                decoded = unicode(data, enc, self.error_handler)
+                self.successful_encoding = enc
+                # Return decoded, removing BOMs.
+                return decoded.replace(u'\ufeff', u'')
+            except (UnicodeError, LookupError), err:
+                error = err # in Python 3, the <exception instance> is
+                            # local to the except clause
+        raise UnicodeError(
+            'Unable to decode input data.  Tried the following encodings: '
+            '%s.\n(%s)' % (', '.join([repr(enc) for enc in encodings]),
+                         ErrorString(error)))
+
+    coding_slug = re.compile(b(r"coding[:=]\s*([-\w.]+)"))
+    """Encoding declaration pattern."""
+
+    byte_order_marks = ((codecs.BOM_UTF8, 'utf-8'), # 'utf-8-sig' new in v2.5
+                        (codecs.BOM_UTF16_BE, 'utf-16-be'),
+                        (codecs.BOM_UTF16_LE, 'utf-16-le'),)
+    """Sequence of (start_bytes, encoding) tuples for encoding detection.
+    The first bytes of input data are checked against the start_bytes strings.
+    A match indicates the given encoding."""
+
+    def determine_encoding_from_data(self, data):
+        """
+        Try to determine the encoding of `data` by looking *in* `data`.
+        Check for a byte order mark (BOM) or an encoding declaration.
+        """
+        # check for a byte order mark:
+        for start_bytes, encoding in self.byte_order_marks:
+            if data.startswith(start_bytes):
+                return encoding
+        # check for an encoding declaration pattern in first 2 lines of file:
+        for line in data.splitlines()[:2]:
+            match = self.coding_slug.search(line)
+            if match:
+                return match.group(1).decode('ascii')
+        return None
+
+
+class Output(TransformSpec):
+
+    """
+    Abstract base class for output wrappers.
+    """
+
+    component_type = 'output'
+
+    default_destination_path = None
+
+    def __init__(self, destination=None, destination_path=None,
+                 encoding=None, error_handler='strict'):
+        self.encoding = encoding
+        """Text encoding for the output destination."""
+
+        self.error_handler = error_handler or 'strict'
+        """Text encoding error handler."""
+
+        self.destination = destination
+        """The destination for output data."""
+
+        self.destination_path = destination_path
+        """A text reference to the destination."""
+
+        if not destination_path:
+            self.destination_path = self.default_destination_path
+
+    def __repr__(self):
+        return ('%s: destination=%r, destination_path=%r'
+                % (self.__class__, self.destination, self.destination_path))
+
+    def write(self, data):
+        """`data` is a Unicode string, to be encoded by `self.encode`."""
+        raise NotImplementedError
+
+    def encode(self, data):
+        if self.encoding and self.encoding.lower() == 'unicode':
+            assert isinstance(data, unicode), (
+                'the encoding given is "unicode" but the output is not '
+                'a Unicode string')
+            return data
+        if not isinstance(data, unicode):
+            # Non-unicode (e.g. bytes) output.
+            return data
+        else:
+            return data.encode(self.encoding, self.error_handler)
+
+
+class FileInput(Input):
+
+    """
+    Input for single, simple file-like objects.
+    """
+    def __init__(self, source=None, source_path=None,
+                 encoding=None, error_handler='strict',
+                 autoclose=True, mode='rU', **kwargs):
+        """
+        :Parameters:
+            - `source`: either a file-like object (which is read directly), or
+              `None` (which implies `sys.stdin` if no `source_path` given).
+            - `source_path`: a path to a file, which is opened and then read.
+            - `encoding`: the expected text encoding of the input file.
+            - `error_handler`: the encoding error handler to use.
+            - `autoclose`: close automatically after read (except when
+              `sys.stdin` is the source).
+            - `mode`: how the file is to be opened (see standard function
+              `open`). The default 'rU' provides universal newline support
+              for text files.
+        """
+        Input.__init__(self, source, source_path, encoding, error_handler)
+        self.autoclose = autoclose
+        self._stderr = ErrorOutput()
+        # deprecation warning
+        for key in kwargs:
+            if key == 'handle_io_errors':
+                sys.stderr.write('deprecation warning: '
+                    'io.FileInput() argument `handle_io_errors` '
+                    'is ignored since "Docutils 0.10 (2012-12-16)" '
+                    'and will soon be removed.')
+            else:
+                raise TypeError('__init__() got an unexpected keyword '
+                                "argument '%s'" % key)
+
+        if source is None:
+            if source_path:
+                # Specify encoding in Python 3
+                if sys.version_info >= (3,0):
+                    kwargs = {'encoding': self.encoding,
+                              'errors': self.error_handler}
+                else:
+                    kwargs = {}
+
+                try:
+                    self.source = open(source_path, mode, **kwargs)
+                except IOError, error:
+                    raise InputError(error.errno, error.strerror, source_path)
+            else:
+                self.source = sys.stdin
+        elif (sys.version_info >= (3,0) and
+              check_encoding(self.source, self.encoding) is False):
+            # TODO: re-open, warn or raise error?
+            raise UnicodeError('Encoding clash: encoding given is "%s" '
+                               'but source is opened with encoding "%s".' %
+                               (self.encoding, self.source.encoding))
+        if not source_path:
+            try:
+                self.source_path = self.source.name
+            except AttributeError:
+                pass
+
+    def read(self):
+        """
+        Read and decode a single file and return the data (Unicode string).
+        """
+        try: # In Python < 2.5, try...except has to be nested in try...finally.
+            try:
+                if self.source is sys.stdin and sys.version_info >= (3,0):
+                    # read as binary data to circumvent auto-decoding
+                    data = self.source.buffer.read()
+                    # normalize newlines
+                    data = b('\n').join(data.splitlines()) + b('\n')
+                else:
+                    data = self.source.read()
+            except (UnicodeError, LookupError), err: # (in Py3k read() decodes)
+                if not self.encoding and self.source_path:
+                    # re-read in binary mode and decode with heuristics
+                    b_source = open(self.source_path, 'rb')
+                    data = b_source.read()
+                    b_source.close()
+                    # normalize newlines
+                    data = b('\n').join(data.splitlines()) + b('\n')
+                else:
+                    raise
+        finally:
+            if self.autoclose:
+                self.close()
+        return self.decode(data)
+
+    def readlines(self):
+        """
+        Return lines of a single file as list of Unicode strings.
+        """
+        return self.read().splitlines(True)
+
+    def close(self):
+        if self.source is not sys.stdin:
+            self.source.close()
+
+
+class FileOutput(Output):
+
+    """
+    Output for single, simple file-like objects.
+    """
+
+    mode = 'w'
+    """The mode argument for `open()`."""
+    # 'wb' for binary (e.g. OpenOffice) files (see also `BinaryFileOutput`).
+    # (Do not use binary mode ('wb') for text files, as this prevents the
+    # conversion of newlines to the system specific default.)
+
+    def __init__(self, destination=None, destination_path=None,
+                 encoding=None, error_handler='strict', autoclose=True,
+                 handle_io_errors=None, mode=None):
+        """
+        :Parameters:
+            - `destination`: either a file-like object (which is written
+              directly) or `None` (which implies `sys.stdout` if no
+              `destination_path` given).
+            - `destination_path`: a path to a file, which is opened and then
+              written.
+            - `encoding`: the text encoding of the output file.
+            - `error_handler`: the encoding error handler to use.
+            - `autoclose`: close automatically after write (except when
+              `sys.stdout` or `sys.stderr` is the destination).
+            - `handle_io_errors`: ignored, deprecated, will be removed.
+            - `mode`: how the file is to be opened (see standard function
+              `open`). The default is 'w', providing universal newline
+              support for text files.
+        """
+        Output.__init__(self, destination, destination_path,
+                        encoding, error_handler)
+        self.opened = True
+        self.autoclose = autoclose
+        if mode is not None:
+            self.mode = mode
+        self._stderr = ErrorOutput()
+        if destination is None:
+            if destination_path:
+                self.opened = False
+            else:
+                self.destination = sys.stdout
+        elif (# destination is file-type object -> check mode:
+              mode and hasattr(self.destination, 'mode')
+              and mode != self.destination.mode):
+                print >>self._stderr, ('Warning: Destination mode "%s" '
+                               'differs from specified mode "%s"' %
+                               (self.destination.mode, mode))
+        if not destination_path:
+            try:
+                self.destination_path = self.destination.name
+            except AttributeError:
+                pass
+
+    def open(self):
+        # Specify encoding in Python 3.
+        if sys.version_info >= (3,0) and 'b' not in self.mode:
+            kwargs = {'encoding': self.encoding,
+                      'errors': self.error_handler}
+        else:
+            kwargs = {}
+        try:
+            self.destination = open(self.destination_path, self.mode, **kwargs)
+        except IOError, error:
+            raise OutputError(error.errno, error.strerror,
+                              self.destination_path)
+        self.opened = True
+
+    def write(self, data):
+        """Encode `data`, write it to a single file, and return it.
+
+        With Python 3 or binary output mode, `data` is returned unchanged,
+        except when specified encoding and output encoding differ.
+        """
+        if not self.opened:
+            self.open()
+        if ('b' not in self.mode and sys.version_info < (3,0)
+            or check_encoding(self.destination, self.encoding) is False
+           ):
+            data = self.encode(data)
+            if sys.version_info >= (3,0) and os.linesep != '\n':
+                data = data.replace(b('\n'), b(os.linesep)) # fix endings
+
+        try: # In Python < 2.5, try...except has to be nested in try...finally.
+            try:
+                self.destination.write(data)
+            except TypeError, e:
+                if sys.version_info >= (3,0) and isinstance(data, bytes):
+                    try:
+                        self.destination.buffer.write(data)
+                    except AttributeError:
+                        if check_encoding(self.destination,
+                                          self.encoding) is False:
+                            raise ValueError('Encoding of %s (%s) differs \n'
+                                '  from specified encoding (%s)' %
+                                (self.destination_path or 'destination',
+                                self.destination.encoding, self.encoding))
+                        else:
+                            raise e
+            except (UnicodeError, LookupError), err:
+                raise UnicodeError(
+                    'Unable to encode output data. output-encoding is: '
+                    '%s.\n(%s)' % (self.encoding, ErrorString(err)))
+        finally:
+            if self.autoclose:
+                self.close()
+        return data
+
+    def close(self):
+        if self.destination not in (sys.stdout, sys.stderr):
+            self.destination.close()
+            self.opened = False
+
+
+class BinaryFileOutput(FileOutput):
+    """
+    A version of docutils.io.FileOutput which writes to a binary file.
+    """
+    # Used by core.publish_cmdline_to_binary() which in turn is used by
+    # rst2odt (OpenOffice writer)
+    mode = 'wb'
+
+
+class StringInput(Input):
+
+    """
+    Direct string input.
+    """
+
+    default_source_path = '<string>'
+
+    def read(self):
+        """Decode and return the source string."""
+        return self.decode(self.source)
+
+
+class StringOutput(Output):
+
+    """
+    Direct string output.
+    """
+
+    default_destination_path = '<string>'
+
+    def write(self, data):
+        """Encode `data`, store it in `self.destination`, and return it."""
+        self.destination = self.encode(data)
+        return self.destination
+
+
+class NullInput(Input):
+
+    """
+    Degenerate input: read nothing.
+    """
+
+    default_source_path = 'null input'
+
+    def read(self):
+        """Return a null string."""
+        return u''
+
+
+class NullOutput(Output):
+
+    """
+    Degenerate output: write nothing.
+    """
+
+    default_destination_path = 'null output'
+
+    def write(self, data):
+        """Do nothing ([don't even] send data to the bit bucket)."""
+        pass
+
+
+class DocTreeInput(Input):
+
+    """
+    Adapter for document tree input.
+
+    The document tree must be passed in the ``source`` parameter.
+    """
+
+    default_source_path = 'doctree input'
+
+    def read(self):
+        """Return the document tree."""
+        return self.source

docutils/languages/__init__.py

@@ -0,0 +1,48 @@
+# $Id: __init__.py 7648 2013-04-18 07:36:22Z milde $
+# Author: David Goodger <goodger@python.org>
+# 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'
+
+import sys
+
+from docutils.utils import normalize_language_tag
+if sys.version_info < (2,5):
+    from docutils._compat import __import__
+
+_languages = {}
+
+def get_language(language_code, reporter=None):
+    """Return module with language localizations.
+
+    `language_code` is a "BCP 47" language tag.
+    If there is no matching module, warn and fall back to English.
+    """
+    # TODO: use a dummy module returning emtpy strings?, configurable?
+    for tag in normalize_language_tag(language_code):
+        tag = tag.replace('-','_') # '-' not valid in module names
+        if tag in _languages:
+            return _languages[tag]
+        try:
+            module = __import__(tag, globals(), locals(), level=1)
+        except ImportError:
+            try:
+                module = __import__(tag, globals(), locals(), level=0)
+            except ImportError:
+                continue
+        _languages[tag] = module
+        return module
+    if reporter is not None:
+        reporter.warning(
+            'language "%s" not supported: ' % language_code +
+            'Docutils-generated text will be in English.')
+    module = __import__('en', globals(), locals(), level=1)
+    _languages[tag] = module # warn only one time!
+    return module

docutils/languages/af.py

@@ -0,0 +1,58 @@
+# $Id: af.py 4564 2006-05-21 20:44:42Z wiemann $
+# Author: Jannie Hofmeyr <jhsh@sun.ac.za>
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
+# translated for each language: one in docutils/languages, the other in
+# docutils/parsers/rst/languages.
+
+"""
+Afrikaans-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+labels = {
+      'author': 'Auteur',
+      'authors': 'Auteurs',
+      'organization': 'Organisasie',
+      'address': 'Adres',
+      'contact': 'Kontak',
+      'version': 'Weergawe',
+      'revision': 'Revisie',
+      'status': 'Status',
+      'date': 'Datum',
+      'copyright': 'Kopiereg',
+      'dedication': 'Opdrag',
+      'abstract': 'Opsomming',
+      'attention': 'Aandag!',
+      'caution': 'Wees versigtig!',
+      'danger': '!GEVAAR!',
+      'error': 'Fout',
+      'hint': 'Wenk',
+      'important': 'Belangrik',
+      'note': 'Nota',
+      'tip': 'Tip', # hint and tip both have the same translation: wenk
+      'warning': 'Waarskuwing',
+      'contents': 'Inhoud'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      'auteur': 'author',
+      'auteurs': 'authors',
+      'organisasie': 'organization',
+      'adres': 'address',
+      'kontak': 'contact',
+      'weergawe': 'version',
+      'revisie': 'revision',
+      'status': 'status',
+      'datum': 'date',
+      'kopiereg': 'copyright',
+      'opdrag': 'dedication',
+      'opsomming': 'abstract'}
+"""Afrikaans (lowcased) to canonical name mapping for bibliographic fields."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

docutils/languages/ca.py

@@ -0,0 +1,60 @@
+# $Id: ca.py 4564 2006-05-21 20:44:42Z wiemann $
+# Author: Ivan Vilata i Balaguer <ivan@selidor.net>
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
+# translated for each language: one in docutils/languages, the other in
+# docutils/parsers/rst/languages.
+
+"""
+Catalan-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+labels = {
+      # fixed: language-dependent
+      'author': u'Autor',
+      'authors': u'Autors',
+      'organization': u'Organitzaci\u00F3',
+      'address': u'Adre\u00E7a',
+      'contact': u'Contacte',
+      'version': u'Versi\u00F3',
+      'revision': u'Revisi\u00F3',
+      'status': u'Estat',
+      'date': u'Data',
+      'copyright': u'Copyright',
+      'dedication': u'Dedicat\u00F2ria',
+      'abstract': u'Resum',
+      'attention': u'Atenci\u00F3!',
+      'caution': u'Compte!',
+      'danger': u'PERILL!',
+      'error': u'Error',
+      'hint': u'Suggeriment',
+      'important': u'Important',
+      'note': u'Nota',
+      'tip': u'Consell',
+      'warning': u'Av\u00EDs',
+      'contents': u'Contingut'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      # language-dependent: fixed
+      u'autor': 'author',
+      u'autors': 'authors',
+      u'organitzaci\u00F3': 'organization',
+      u'adre\u00E7a': 'address',
+      u'contacte': 'contact',
+      u'versi\u00F3': 'version',
+      u'revisi\u00F3': 'revision',
+      u'estat': 'status',
+      u'data': 'date',
+      u'copyright': 'copyright',
+      u'dedicat\u00F2ria': 'dedication',
+      u'resum': 'abstract'}
+"""Catalan (lowcased) to canonical name mapping for bibliographic fields."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

docutils/languages/cs.py

@@ -0,0 +1,60 @@
+# $Id: cs.py 4564 2006-05-21 20:44:42Z wiemann $
+# Author: Marek Blaha <mb@dat.cz>
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
+# translated for each language: one in docutils/languages, the other in
+# docutils/parsers/rst/languages.
+
+"""
+Czech-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+labels = {
+      # fixed: language-dependent
+      'author': u'Autor',
+      'authors': u'Auto\u0159i',
+      'organization': u'Organizace',
+      'address': u'Adresa',
+      'contact': u'Kontakt',
+      'version': u'Verze',
+      'revision': u'Revize',
+      'status': u'Stav',
+      'date': u'Datum',
+      'copyright': u'Copyright',
+      'dedication': u'V\u011Bnov\u00E1n\u00ED',
+      'abstract': u'Abstrakt',
+      'attention': u'Pozor!',
+      'caution': u'Opatrn\u011B!',
+      'danger': u'!NEBEZPE\u010C\u00CD!',
+      'error': u'Chyba',
+      'hint': u'Rada',
+      'important': u'D\u016Fle\u017Eit\u00E9',
+      'note': u'Pozn\u00E1mka',
+      'tip': u'Tip',
+      'warning': u'Varov\u00E1n\u00ED',
+      'contents': u'Obsah'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      # language-dependent: fixed
+      u'autor': 'author',
+      u'auto\u0159i': 'authors',
+      u'organizace': 'organization',
+      u'adresa': 'address',
+      u'kontakt': 'contact',
+      u'verze': 'version',
+      u'revize': 'revision',
+      u'stav': 'status',
+      u'datum': 'date',
+      u'copyright': 'copyright',
+      u'v\u011Bnov\u00E1n\u00ED': 'dedication',
+      u'abstrakt': 'abstract'}
+"""Czech (lowcased) to canonical name mapping for bibliographic fields."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

docutils/languages/da.py

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+# $Id: da.py 7678 2013-07-03 09:57:36Z milde $
+# Author: E D
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
+# translated for each language: one in docutils/languages, the other in
+# docutils/parsers/rst/languages.
+
+"""
+Danish-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+labels = {
+      # fixed: language-dependent
+      'author': u'Forfatter',
+      'authors': u'Forfattere',
+      'organization': u'Organisation',
+      'address': u'Adresse',
+      'contact': u'Kontakt',
+      'version': u'Version',
+      'revision': u'Revision',
+      'status': u'Status',
+      'date': u'Dato',
+      'copyright': u'Copyright',
+      'dedication': u'Dedikation',
+      'abstract': u'Resumé',
+      'attention': u'Giv agt!',
+      'caution': u'Pas på!',
+      'danger': u'!FARE!',
+      'error': u'Fejl',
+      'hint': u'Vink',
+      'important': u'Vigtigt',
+      'note': u'Bemærk',
+      'tip': u'Tips',
+      'warning': u'Advarsel',
+      'contents': u'Indhold'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      # language-dependent: fixed
+      u'forfatter': 'author',
+      u'forfattere': 'authors',
+      u'organisation': 'organization',
+      u'adresse': 'address',
+      u'kontakt': 'contact',
+      u'version': 'version',
+      u'revision': 'revision',
+      u'status': 'status',
+      u'dato': 'date',
+      u'copyright': 'copyright',
+      u'dedikation': 'dedication',
+      u'resume': 'abstract',
+      u'resumé': 'abstract'}
+"""Danish (lowcased) to canonical name mapping for bibliographic fields."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

docutils/languages/de.py

@@ -0,0 +1,58 @@
+# $Id: de.py 4564 2006-05-21 20:44:42Z wiemann $
+# Author: Gunnar Schwant <g.schwant@gmx.de>
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
+# translated for each language: one in docutils/languages, the other in
+# docutils/parsers/rst/languages.
+
+"""
+German language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+labels = {
+    'author': 'Autor',
+    'authors': 'Autoren',
+    'organization': 'Organisation',
+    'address': 'Adresse',
+    'contact': 'Kontakt',
+    'version': 'Version',
+    'revision': 'Revision',
+    'status': 'Status',
+    'date': 'Datum',
+    'dedication': 'Widmung',
+    'copyright': 'Copyright',
+    'abstract': 'Zusammenfassung',
+    'attention': 'Achtung!',
+    'caution': 'Vorsicht!',
+    'danger': '!GEFAHR!',
+    'error': 'Fehler',
+    'hint': 'Hinweis',
+    'important': 'Wichtig',
+    'note': 'Bemerkung',
+    'tip': 'Tipp',
+    'warning': 'Warnung',
+    'contents': 'Inhalt'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+    'autor': 'author',
+    'autoren': 'authors',
+    'organisation': 'organization',
+    'adresse': 'address',
+    'kontakt': 'contact',
+    'version': 'version',
+    'revision': 'revision',
+    'status': 'status',
+    'datum': 'date',
+    'copyright': 'copyright',
+    'widmung': 'dedication',
+    'zusammenfassung': 'abstract'}
+"""German (lowcased) to canonical name mapping for bibliographic fields."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""

docutils/languages/en.py

@@ -0,0 +1,60 @@
+# $Id: en.py 4564 2006-05-21 20:44:42Z wiemann $
+# Author: David Goodger <goodger@python.org>
+# Copyright: This module has been placed in the public domain.
+
+# New language mappings are welcome.  Before doing a new translation, please
+# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
+# translated for each language: one in docutils/languages, the other in
+# docutils/parsers/rst/languages.
+
+"""
+English-language mappings for language-dependent features of Docutils.
+"""
+
+__docformat__ = 'reStructuredText'
+
+labels = {
+      # fixed: language-dependent
+      'author': 'Author',
+      'authors': 'Authors',
+      'organization': 'Organization',
+      'address': 'Address',
+      'contact': 'Contact',
+      'version': 'Version',
+      'revision': 'Revision',
+      'status': 'Status',
+      'date': 'Date',
+      'copyright': 'Copyright',
+      'dedication': 'Dedication',
+      'abstract': 'Abstract',
+      'attention': 'Attention!',
+      'caution': 'Caution!',
+      'danger': '!DANGER!',
+      'error': 'Error',
+      'hint': 'Hint',
+      'important': 'Important',
+      'note': 'Note',
+      'tip': 'Tip',
+      'warning': 'Warning',
+      'contents': 'Contents'}
+"""Mapping of node class name to label text."""
+
+bibliographic_fields = {
+      # language-dependent: fixed
+      'author': 'author',
+      'authors': 'authors',
+      'organization': 'organization',
+      'address': 'address',
+      'contact': 'contact',
+      'version': 'version',
+      'revision': 'revision',
+      'status': 'status',
+      'date': 'date',
+      'copyright': 'copyright',
+      'dedication': 'dedication',
+      'abstract': 'abstract'}
+"""English (lowcased) to canonical name mapping for bibliographic fields."""
+
+author_separators = [';', ',']
+"""List of separator strings for the 'Authors' bibliographic field. Tried in
+order."""