re-added docutils-0.3.9 tag one level deeper (without web/ and sandboxes/)docutils-0.3.9

git-svn-id: http://svn.code.sf.net/p/docutils/code/tags/docutils-0.3.9@3815 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

10 files changed, 4043 insertions, 0 deletions

diff --git a/docs/user/config.txt b/docs/user/config.txt
new file mode 100644
index 000000000..1b52511b4
--- /dev/null
+++ b/docs/user/config.txt
@@ -0,0 +1,959 @@
+==============================
+ Docutils Configuration Files
+==============================
+
+:Author: David Goodger
+:Contact: goodger@python.org
+:Revision: $Revision$
+:Date: $Date$
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+.. Cross-reference command-line options with configuration file
+   settings?  Make alphabetical indexes of both.
+
+Configuration files are used for persistent customization; they can be
+set once and take effect every time you use a front-end tool.
+Configuration file settings override the built-in defaults, and
+command-line options override all.
+
+By default, Docutils checks the following places for configuration
+files, in the following order:
+
+1. ``/etc/docutils.conf``: This is a system-wide configuration file,
+   applicable to all Docutils processing on the system.
+
+2. ``./docutils.conf``: This is a project-specific configuration file,
+   located in the current directory.  The Docutils front end has to be
+   executed from the directory containing this configuration file for
+   it to take effect (note that this may have nothing to do with the
+   location of the source files).  Settings in the project-specific
+   configuration file will override corresponding settings in the
+   system-wide file.
+
+3. ``~/.docutils``: This is a user-specific configuration file,
+   located in the user's home directory.  Settings in this file will
+   override corresponding settings in both the system-wide and
+   project-specific configuration files.
+
+If more than one configuration file is found, all will be read but
+later entries will override earlier ones.  For example, a "stylesheet"
+entry in a user-specific configuration file will override a
+"stylesheet" entry in the system-wide file.
+
+The default implicit config file paths can be overridden by the
+``DOCUTILSCONFIG`` environment variable.  ``DOCUTILSCONFIG`` should
+contain a colon-separated (semicolon-separated on Windows) sequence of
+config file paths to search for; leave it empty to disable implicit
+config files altogether.  Tilde-expansion is performed on paths.
+Paths are interpreted relative to the current working directory.
+Empty path items are ignored.
+
+In addition, a configuration file may be explicitly specified with the
+"--config" command-line option.  This configuration file is read after
+the three implicit ones listed above (or the ones defined by the
+``DOCUTILSCONFIG`` environment variable), and its entries will have
+priority.
+
+
+-------------------------
+Configuration File Syntax
+-------------------------
+
+Configuration files use the standard ConfigParser.py_ Python_ module.
+From its documentation:
+
+    The configuration file consists of sections, lead by a "[section]"
+    header and followed by "name: value" entries, with continuations
+    in the style of `RFC 822`_; "name=value" is also accepted.  Note
+    that leading whitespace is removed from values.  ...  Lines
+    beginning with "#" or ";" are ignored and may be used to provide
+    comments.
+
+.. Note:: No format string interpolation is done.
+
+Configuration file entry names correspond to internal runtime
+settings.  Underscores ("_") and hyphens ("-") can be used
+interchangably in entry names; hyphens are automatically converted to
+underscores.
+
+For on/off switch settings (booleans), the following values are
+recognized:
+
+* On: "true", "yes", "on", "1"
+* Off: "false", "no", "off", "0", "" (no value)
+
+
+-------------------------------------
+Configuration File Sections & Entries
+-------------------------------------
+
+Below are the Docutils runtime settings, listed by config file
+section.  Any setting may be specified in any section, but only
+settings from active sections will be used.  Sections correspond to
+Docutils components (module name or alias; section names are always in
+lowercase letters).  Each `Docutils application`_ uses a specific set
+of components; corresponding configuration file sections are applied
+when the application is used.  Configuration sections are applied in
+general-to-specific order, as follows:
+
+1. `[general]`_
+
+2. `[parsers]`_, parser dependencies, and the section specific to the
+   Parser used ("[... parser]").  Currently, only `[restructuredtext
+   parser]`_ is applicable.
+
+3. `[readers]`_, reader dependencies, and the section specific to the
+   Reader used ("[... reader]").  For example, `[pep reader]`_ depends
+   on `[standalone reader]`_.
+
+4. `[writers]`_, writer dependencies, and the section specific to the
+   Writer used ("[... writer]").  For example, `[pep_html writer]`_
+   depends on `[html4css1 writer]`_.
+
+5. `[applications]`_, application dependencies, and the section
+    specific to the Application (front-end tool) in use
+    ("[... application]").
+
+Since any setting may be specified in any section, this ordering
+allows component- or application-specific overrides of earlier
+settings.  For example, there may be Reader-specific overrides of
+general settings; Writer-specific overrides of Parser settings;
+Application-specific overrides of Writer settings; and so on.
+
+If multiple configuration files are applicable, the process is
+completed (all sections are applied in the order given) for each one
+before going on to the next.  For example, a "[pep_html writer]
+stylesheet" setting in an earlier configuration file would be
+overridden by an "[html4css1 writer] stylesheet" setting in a later
+file.
+
+Some knowledge of Python_ is assumed for some attributes.
+
+.. _ConfigParser.py:
+   http://www.python.org/doc/current/lib/module-ConfigParser.html
+.. _Python: http://www.python.org/
+.. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt
+.. _Docutils application: tools.html
+
+
+[general]
+=========
+
+Settings in the "[general]" section are always applied.
+
+_`auto_id_prefix`
+    Prefix prepended to all auto-generated IDs generated within the
+    document, after id_prefix_.
+
+    Default: "id".  Options: ``--auto-id-prefix`` (hidden, intended
+    mainly for programmatic use).
+    
+_`datestamp`
+    Include a time/datestamp in the document footer.  Contains a
+    format string for Python's ``time.strftime``.  See the `time
+    module documentation`__.
+
+    Default: None.  Options: ``--date, -d, --time, -t,
+    --no-datestamp``.
+
+    Configuration file entry examples::
+
+        # Equivalent to --date command-line option, results in
+        # ISO 8601 extended format datestamp, e.g. "2001-12-21":
+        datestamp: %Y-%m-%d
+
+        # Equivalent to --time command-line option, results in
+        # date/timestamp like "2001-12-21 18:43 UTC":
+        datestamp: %Y-%m-%d %H:%M UTC
+
+        # Disables datestamp; equivalent to --no-datestamp:
+        datestamp:
+
+    __ http://www.python.org/doc/current/lib/module-time.html
+
+_`debug`
+    Report debug-level system messages.
+
+    Default: don't (None).  Options: ``--debug, --no-debug``.
+
+_`dump_internals`
+    At the end of processing, write all internal attributes of the
+    document (``document.__dict__``) to stderr.
+
+    Default: don't (None).  Options: ``--dump-internals`` (hidden, for
+    development use only).
+
+_`dump_pseudo_xml`
+    At the end of processing, write the pseudo-XML representation of
+    the document to stderr.
+
+    Default: don't (None).  Options: ``--dump-pseudo-xml`` (hidden,
+    for development use only).
+
+_`dump_settings`
+    At the end of processing, write all Docutils settings to stderr.
+
+    Default: don't (None).  Options: ``--dump-settings`` (hidden, for
+    development use only).
+
+_`dump_transforms`
+    At the end of processing, write a list of all transforms applied
+    to the document to stderr.
+
+    Default: don't (None).  Options: ``--dump-transforms`` (hidden,
+    for development use only).
+
+_`error_encoding`
+    The text encoding for error output.
+
+    Default: "ascii".  Options: ``--error-encoding, -e``.
+
+_`error_encoding_error_handler`
+    The error handler for unencodable characters in error output.  See
+    output_encoding_error_handler_ for acceptable values.
+
+    Default: "backslashreplace" for Python 2.3 and later; "replace"
+    otherwise.  Options: ``--error-encoding-error-handler,
+    --error-encoding, -e``.
+
+_`exit_status_level`
+    A system message level threshold; non-halting system messages at
+    or above this level will produce a non-zero exit status at normal
+    exit.  Exit status is the maximum system message level plus 10 (11
+    for INFO, etc.).
+
+    Default: disabled (5).  Options: ``--exit-status``.
+
+_`expose_internals`
+    List of internal attribues to expose as external attributes (with
+    "internal:" namespace prefix).  To specify multiple attributes in
+    configuration files, use colons to separate names; on the command
+    line, the option may be used more than once.
+
+    Default: don't (None).  Options: ``--expose-internal-attribute``
+    (hidden, for development use only).
+
+_`footnote_backlinks`
+    Enable or disable backlinks from footnotes and citations to their
+    references.
+
+    Default: enabled (1).  Options: ``--footnote-backlinks,
+    --no-footnote-backlinks``.
+
+_`generator`
+    Include a "Generated by Docutils" credit and link in the document
+    footer.
+
+    Default: off (None).  Options: ``--generator, -g,
+    --no-generator``.
+
+_`halt_level`
+    The threshold at or above which system messages are converted to
+    exceptions, halting execution immediately.  If `traceback`_ is
+    set, the exception will propagate; otherwise, Docutils will exit.
+
+    Default: severe (4).  Options: ``--halt, --strict``.
+
+_`id_prefix`
+    Prefix prepended to all IDs generated within the document.  See
+    also auto_id_prefix_.
+
+    Default: "" (empty).  Options: ``--id-prefix`` (hidden, intended
+    mainly for programmatic use).
+    
+_`input_encoding`
+    The text encoding for input.
+
+    Default: auto-detect (None).  Options: ``--input-encoding, -i``.
+
+_`input_encoding_error_handler`
+    The error handler for undecodable characters in the input.
+    Acceptable values include:
+
+    strict
+        Raise an exception in case of an encoding error.
+    replace
+        Replace malformed data with the official Unicode replacement
+        character, U+FFFD.
+    ignore
+        Ignore malformed data and continue without further notice.
+
+    Acceptable values are the same as for the "error" parameter of
+    Python's ``unicode`` function; other values may be defined in
+    applications or in future versions of Python.
+
+    Default: "strict".  Options: ``--input-encoding-error-handler,
+    --input-encoding, -i``.
+
+_`language_code`
+    `ISO 639`_ 2-letter language code (3-letter codes used only if no
+    2-letter code exists).
+
+    Default: English ("en").  Options: ``--language, -l``.
+
+_`output_encoding`
+    The text encoding for output.
+
+    Default: "UTF-8".  Options: ``--output-encoding, -o``.
+
+_`output_encoding_error_handler`
+    The error handler for unencodable characters in the output.
+    Acceptable values include:
+
+    strict
+        Raise an exception in case of an encoding error.
+    replace
+        Replace malformed data with a suitable replacement marker,
+        such as "?".
+    ignore
+        Ignore malformed data and continue without further notice.
+    xmlcharrefreplace
+        Replace with the appropriate XML character reference, such as
+        "``†``".
+    backslashreplace
+        (Python 2.3+)  Replace with backslashed escape sequences, such
+        as "``\u2020``".
+
+    Acceptable values are the same as for the "error" parameter of
+    Python's ``encode`` string method; other values may be defined in
+    applications or in future versions of Python.
+
+    Default: "strict".  Options: ``--output-encoding-error-handler,
+    --output-encoding, -o``.
+
+_`record_dependencies`
+
+    Path to a file to which Docutils writes a list of files the input
+    file(s) depends on [#dependencies]_, e.g. due to file
+    inclusion. [#pwd]_ The format is one filename per line.  This
+    option is particularly useful in conjunction with programs like
+    ``make``.
+
+    Set to ``-`` in order to write dependencies to stdout.
+
+    Default: None.  Option: ``--record-dependencies``.
+
+_`report_level`
+    Verbosity threshold at or above which system messages are
+    reported.
+
+    Default: warning (2).  Options: ``--report, -r, --verbose, -v,
+    --quiet, -q``.
+
+_`sectnum_xform`
+    Enable or disable the section numbering transform
+    (docutils.transforms.parts.SectNum).
+
+    Default: enabled (1).  Options: ``--no-section-numbering``.
+
+_`source_link`
+    Include a "View document source" link in the document footer.  URL
+    will be relative to the destination.
+
+    Default: don't (None).  Options: ``--source-link, -s,
+    --no-source-link``.
+
+_`source_url`
+    An explicit URL for a "View document source" link, used verbatim.
+
+    Default: compute if source_link (None).  Options: ``--source-url,
+    --no-source-link``.
+
+_`strict_visitor`
+    When processing a document tree with the Visitor pattern, raise an
+    error if a writer does not support a node type listed as optional.
+    For transitional development use.
+
+    Default: disabled (None).  Option: ``--strict-visitor`` (hidden,
+    for development use only).
+
+_`toc_backlinks`
+    Enable backlinks from section titles to table of contents entries
+    ("entry"), to the top of the TOC ("top"), or disable ("none").
+
+    Default: "entry".  Options: ``--toc-entry-backlinks,
+    --toc-top-backlinks, --no-toc-backlinks``.
+
+_`traceback`
+    Enable Python tracebacks when halt-level system messages and other
+    exceptions occur.  Useful for debugging, and essential for issue
+    reports.  Exceptions are allowed to propagate, instead of being
+    caught and reported (in a user-friendly way) by Docutils.
+
+    Default: disabled (None) unless Docutils is run programmatically
+    using the `Publisher Interface`_.  Options: ``--traceback,
+    --no-traceback``.
+
+    .. _Publisher Interface: ../api/publisher.html
+
+_`warning_stream`
+    Path to a file for the output of system messages (warnings)
+    [#pwd]_.
+
+    Default: stderr (None).  Options: ``--warnings``.
+
+
+[parsers]
+---------
+
+Docutils currently supports only one parser, for reStructuredText.
+
+
+[restructuredtext parser]
+`````````````````````````
+
+_`file_insertion_enabled`
+    Enable or disable directives that insert the contents of external
+    files, such as the "include_" & "raw_".  A "warning" system
+    message (including the directive text) is inserted instead.  (See
+    also raw_enabled_ for another security-relevant setting.)
+
+    Default: enabled (1).  Options: ``--file-insertion-enabled,
+    --no-file-insertion``.
+
+    .. _include: ../ref/rst/directives.html#include
+    .. _raw: ../ref/rst/directives.html#raw
+
+_`pep_references`
+    Recognize and link to standalone PEP references (like "PEP 258").
+
+    Default: disabled (None); enabled (1) in PEP Reader.  Options:
+    ``--pep-references``.
+
+_`pep_base_url`
+    Base URL for PEP references.  
+
+    Default: "http://www.python.org/peps/".  Option:
+    ``--pep-base-url``.
+
+_`raw_enabled`
+    Enable or disable the "raw_" directive.  A "warning" system
+    message (including the directive text) is inserted instead.  (See
+    also file_insertion_enabled_ for another security-relevant
+    setting.)
+
+    Default: enabled (1).  Options: ``--raw-enabled, --no-raw``.
+
+_`rfc_references`
+    Recognize and link to standalone RFC references (like "RFC 822").
+
+    Default: disabled (None); enabled (1) in PEP Reader.  Options:
+    ``--rfc-references``.
+
+_`rfc_base_url`
+    Base URL for RFC references.  
+
+    Default: "http://www.faqs.org/rfcs/".  Option: ``--rfc-base-url``.
+
+_`tab_width`
+    Number of spaces for hard tab expansion.
+
+    Default: 8.  Options: ``--tab-width``.
+
+_`trim_footnote_reference_space`
+    Remove spaces before footnote references.
+
+    Default: don't (None); may be overriden by a writer-specific
+    footnote_references__ default though.  Options:
+    ``--trim-footnote-reference-space,
+    --leave-footnote-reference-space``.
+
+__ `footnote_references [latex2e writer]`_
+
+
+[readers]
+---------
+
+
+[standalone reader]
+```````````````````
+
+_`docinfo_xform`
+    Enable or disable the bibliographic field list transform
+    (docutils.transforms.frontmatter.DocInfo).
+
+    Default: enabled (1).  Options: ``--no-doc-info``.
+
+_`doctitle_xform`
+    Enable or disable the promotion of a lone top-level section title
+    to document title (and subsequent section title to document
+    subtitle promotion; docutils.transforms.frontmatter.DocTitle).
+
+    Default: enabled (1).  Options: ``--no-doc-title``.
+
+_`sectsubtitle_xform`
+
+    Enable or disable the promotion of the title of a lone subsection
+    to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
+
+    Default: disabled (0).  Options: ``--section-subtitles,
+    --no-section-subtitles``.
+
+
+[pep reader]
+````````````
+
+The `pep_references`_ and `rfc_references`_ options
+(`[restructuredtext parser]`_) are set on by default.
+
+
+[python reader]
+```````````````
+
+Under construction.
+
+
+[writers]
+---------
+
+[docutils_xml writer]
+`````````````````````
+
+_`doctype_declaration`
+    Generate XML with a DOCTYPE declaration.
+
+    Default: do (1).  Options: ``--no-doctype``.
+
+_`indents`
+    Generate XML with indents and newlines.
+
+    Default: don't (None).  Options: ``--indents``.
+
+_`newlines`
+    Generate XML with newlines before and after tags.
+
+    Default: don't (None).  Options: ``--newlines``.
+
+.. _xml_declaration [docutils_xml writer]:
+
+xml_declaration
+    Generate XML with an XML declaration.  Also defined for the
+    `HTML Writer`__.
+
+    .. Caution:: The XML declaration carries text encoding
+       information, without which standard tools may be unable to read
+       the generated XML.
+
+    Default: do (1).  Options: ``--no-xml-declaration``.
+
+    __ `xml_declaration [html4css1 writer]`_
+
+
+[html4css1 writer]
+``````````````````
+
+.. _attribution [html4css1 writer]:
+
+attribution
+    Format for block quote attributions: one of "dash" (em-dash
+    prefix), "parentheses"/"parens", or "none".  Also defined for the
+    `LaTeX Writer`__.
+
+    Default: "dash".  Options: ``--attribution``.
+
+    __ `attribution [latex2e writer]`_
+
+_`cloak_email_addresses`
+    Scramble email addresses to confuse harvesters.  In the visible
+    text of an email address, the "@" will be replaced by "at", and
+    all periods (".") will be replaced by "dot", with spaces added.
+    In the reference URI, the address will be replaced by %-escapes.
+    For example, "abc@example.org" will be output as::
+
+        <a class="reference"
+         href="mailto:%61%62%63%40%65%78%61%6D%70%6C%65%2E%6F%72%67">
+        abc at example dot org</a>
+
+    Default: don't cloak (None).  Option: ``--cloak-email-addresses``.
+
+_`compact_lists`
+    Remove extra vertical whitespace between items of bullet lists and
+    enumerated lists, when list items are "simple" (i.e., all items
+    each contain one paragraph and/or one "simple" sublist only).
+
+    Default: enabled (1).  Options: ``--compact-lists,
+    --no-compact-lists``.
+
+_`embed_stylesheet`
+    Embed the stylesheet in the output HTML file.  The stylesheet file
+    must be accessible during processing.
+
+    Default: link, don't embed (None).  Options: ``--embed-stylesheet,
+    --link-stylesheet``.
+
+_`field_name_limit`
+    The maximum width (in characters) for one-column field names.
+    Longer field names will span an entire row of the table used to
+    render the field list.  0 indicates "no limit".  See also
+    option_limit_.
+
+    Default: 14 characters.  Option: ``--field-name-limit``.
+
+.. _footnote_references [html4css1 writer]:
+
+footnote_references
+    Format for footnote references, one of "superscript" or
+    "brackets".  Also defined for the `LaTeX Writer`__.
+
+    Overrides [#override]_ trim_footnote_reference_space_, if
+    applicable. [#footnote_space]_
+
+    Default: "brackets".  Option: ``--footnote-references``.
+
+    __ `footnote_references [latex2e writer]`_
+
+_`initial_header_level`
+    The initial level for header elements.  This does not affect the
+    document title & subtitle; see doctitle_xform_.
+
+    Default: 1 (for "<h1>").  Option: ``--initial-header-level``.
+
+.. _stylesheet [html4css1 writer]:
+
+_`option_limit`
+    The maximum width (in characters) for options in option lists.
+    Longer options will span an entire row of the table used to render
+    the option list.  0 indicates "no limit".  See also
+    field_name_limit_.
+
+    Default: 14 characters.  Option: ``--option-limit``.
+
+stylesheet
+    CSS stylesheet URL, used verbatim.  Overrides stylesheet_path
+    [#override]_.
+
+    Default: "default.css".  Options: ``--stylesheet``.
+
+    (Setting also defined for the `LaTeX Writer`__.)
+
+    __ `stylesheet [latex2e writer]`_
+
+.. _stylesheet_path [html4css1 writer]:
+
+stylesheet_path
+    Path to CSS stylesheet [#pwd]_.  Overrides "stylesheet" URL
+    setting (``--stylesheet``) [#override]_.  Path is adjusted
+    relative to the output HTML file.  Also defined for the `LaTeX
+    Writer`__.
+
+    Default: None.  Options: ``--stylesheet-path``.
+
+    __ `stylesheet_path [latex2e writer]`_
+
+.. _xml_declaration [html4css1 writer]:
+
+xml_declaration
+    Generate XML with an XML declaration.  Also defined for the
+    `Docutils XML Writer`__.
+
+    .. Caution:: The XML declaration carries text encoding
+       information, without which standard tools may be unable to read
+       the generated XML.
+
+    Default: do (1).  Options: ``--no-xml-declaration``.
+
+    __ `xml_declaration [docutils_xml writer]`_
+
+
+[pep_html writer]
+.................
+
+The PEP/HTML Writer derives from the standard HTML Writer, and shares
+all settings defined in the `[html4css1 writer]`_ section.  The
+"[html4css1 writer]" section is processed before "[pep_html writer]".
+
+_`no_random`
+    Do not use a random banner image.  Mainly used to get predictable
+    results when testing.
+
+    Default: random enabled (None).  Options: ``--no-random``
+    (hidden).
+
+_`pep_home`
+    Home URL prefix for PEPs.
+
+    Default: current directory (".").  Options: ``--pep-home``.
+
+_`template`
+    Path to PEP template file [#pwd]_.
+
+    Default: "pep-html-template" (in current directory).  Options:
+    ``--template``.
+
+_`python_home`
+    Python's home URL.
+
+    Default: parent directory ("..").  Options: ``--python-home``.
+
+
+[latex2e writer]
+````````````````
+
+_`use_latex_toc`
+    To get pagenumbers in the table of contents the table of contents
+    must be generated by latex. Usually latex must be run twice to get
+    numbers correct.
+
+    *Note:* LaTeX will number the sections, which might be a bug in
+    this case.
+
+    Default: off.  Option: ``--use-latex-toc``.
+
+.. XXX Missing: use_latex_docinfo
+
+_`use_latex_footnotes`
+    Use LaTeX-footnotes not a figure simulation. This might give no
+    Hyperrefs on /to footnotes, but should be able to handle an
+    unlimited number of footnotes.
+
+    Default: off.  Option: ``--use-latex-footnotes``.
+
+_`hyperlink_color`
+    Color of any hyperlinks embedded in text. Use "0" to disable
+    coloring of links.
+
+    Default: "blue".  Option: ``--hyperlink-color``.
+
+_`documentclass`
+    Specify latex documentclass, *but* beaware that books have chapters
+    articles not.
+
+    Default: "article".  Option: ``--documentclass``.
+
+_`documentoptions`
+    Specify document options.  Multiple options can be given, separated by
+    commas.
+
+    Default: "10pt,a4paper".  Option: ``--documentoptions``.
+
+.. _stylesheet [latex2e writer]:
+
+stylesheet
+    Specify a stylesheet file.  Overrides stylesheet_path
+    [#override]_.  The file will be ``\input`` by latex in the
+    document header.  Also defined for the `HTML Writer`__.
+
+    Default: no stylesheet ("").  Option: ``--stylesheet``.
+
+    __ `stylesheet [html4css1 writer]`_
+
+.. _stylesheet_path [latex2e writer]:
+
+stylesheet_path
+    Path to stylesheet [#pwd]_.  Overrides "stylesheet" setting
+    (``--stylesheet``) [#override]_.
+
+    Please note that you will have to run ``latex`` from the directory
+    containing the output file; otherwise the stylesheet reference
+    will be invalid.
+
+    This setting is also defined for the `HTML Writer`__.
+
+    Default: None.  Option: ``--stylesheet-path``.
+
+    __ `stylesheet_path [html4css1 writer]`_
+
+.. XXX Missing: embed_stylesheet
+
+.. _footnote_references [latex2e writer]:
+
+footnote_references
+    Format for footnote references: one of "superscript" or
+    "brackets".  Also defined for the `HTML Writer`__.
+
+    Overrides [#override]_ trim_footnote_reference_space_, if
+    applicable. [#footnote_space]_
+
+    Default: "superscript".  Option: ``--footnote-references``.
+
+    __ `footnote_references [html4css1 writer]`_
+
+.. _attribution [latex2e writer]:
+
+attribution
+    Format for block quote attributions, the same as for the
+    html-writer: one of "dash" (em-dash prefix),
+    "parentheses"/"parens" or "none".  Also defined for the `HTML
+    Writer`__.
+
+    Default: "dash".  Option: ``--attribution``.
+
+    __ `attribution [html4css1 writer]`_
+
+_`compound_enumerators`
+    Enable or disable compound enumerators for nested enumerated lists
+    (e.g. "1.2.a.ii").
+
+    Default: disabled (None).  Options: ``--compound-enumerators``,
+    ``--no-compound-enumerators``.
+
+_`section_prefix_for_enumerators`
+    Enable or disable section ("." subsection ...) prefixes for
+    compound enumerators.  This has no effect unless
+    `compound_enumerators`_ are enabled.
+    
+    Default: disabled (None).  Options:
+    ``--section-prefix-for-enumerators``,
+    ``--no-section-prefix-for-enumerators``.
+
+_`section_enumerator_separator`
+    The separator between section number prefix and enumerator for
+    compound enumerated lists (see `compound_enumerators`_).
+
+    Generally it isn't recommended to use both sub-sections and nested
+    enumerated lists with compound enumerators.  This setting avoids
+    ambiguity in the situation where a section "1" has a list item
+    enumerated "1.1", and subsection "1.1" has list item "1".  With a
+    separator of ".", these both would translate into a final compound
+    enumerator of "1.1.1".  With a separator of "-", we get the
+    unambiguous "1-1.1" and "1.1-1".
+
+    Default: "-".  Option: ``--section-enumerator-separator``.
+
+_`table_style`
+    Specify the drawing of separation lines.
+
+    - "standard" lines around and between cells.
+    - "booktabs" a line above and below the table and one after the
+      head.
+    - "nolines".
+
+    Default: "standard".  Option: ``--table-style``.
+
+
+[pseudoxml writer]
+``````````````````
+
+No settings are defined for this Writer.
+
+
+[applications]
+--------------
+
+[buildhtml application]
+```````````````````````
+
+_`prune`
+    List of directories not to process.  To specify multiple
+    directories in configuration files, use colon-separated paths; on
+    the command line, the option may be used more than once.
+
+    Default: none ([]).  Options: ``--prune``.
+
+_`recurse`
+    Recursively scan subdirectories, or ignore subdirectories.
+
+    Default: recurse (1).  Options: ``--recurse, --local``.
+
+_`silent`
+    Work silently (no progress messages).  Independent of
+    "report_level".
+
+    Default: show progress (None).  Options: ``--silent``.
+
+
+[docfactory application]
+````````````````````````
+
+(To be completed.)
+
+
+Other Settings
+==============
+
+These settings are only effective as command-line options, positional
+arguments, or for internal use; setting them in configuration files
+has no effect.
+
+_`config`
+    Path to a configuration file to read (if it exists) [#pwd]_.
+    Settings may override defaults and earlier settings.  The config
+    file is processed immediately.  Multiple ``--config`` options may
+    be specified; each will be processed in turn.
+
+    Filesystem path settings contained within the config file will be
+    interpreted relative to the config file's location (*not* relative
+    to the current working directory).
+
+    Default: None.  Options: ``--config``.
+
+_`_directories`
+    (``buildhtml.py`` front end.)  List of paths to source
+    directories, set from positional arguments.
+
+    Default: current working directory (None).  No command-line
+    options.
+
+_`_disable_config`
+    Prevent standard configuration files from being read.  For
+    internal use only.
+
+    Default: config files enabled (None).  No command-line options.
+
+_`_destination`
+    Path to output destination, set from positional arguments.
+
+    Default: stdout (None).  No command-line options.
+
+_`_source`
+    Path to input source, set from positional arguments.
+
+    Default: stdin (None).  No command-line options.
+
+
+.. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html
+
+.. [#pwd] Path relative to the working directory of the process at
+   launch.
+
+.. [#override] The overridden setting will automatically be set to
+   ``None`` for command-line options and config file settings.  Client
+   programs which specify defaults that override other settings must
+   do the overriding explicitly, by assigning ``None`` to the other
+   settings.
+
+.. [#dependencies] Some notes on the dependency recorder:
+
+   * Images are only added to the dependency list if the
+     reStructuredText parser extracted image dimensions from the file.
+
+   * Stylesheets are only added if they are embedded.
+
+   * For practical reasons, the output of the LaTeX writer is
+     considered merely an *intermediate* processing stage.  The
+     dependency recorder records all files the *rendered* file
+     (e.g. in PDF or DVI format) depends on.  Thus, images and
+     stylesheets are both unconditionally recorded as dependencies
+     when using the LaTeX writer.
+   
+.. [#footnote_space] The footnote space is trimmed if the reference
+   style is "superscript", and it is left if the reference style is
+   "brackets".
+
+   The overriding only happens if the parser supports the
+   trim_footnote_reference_space option.
+
+
+------------------------------
+Old-Format Configuration Files
+------------------------------
+
+Formerly, Docutils configuration files contained a single "[options]"
+section only.  This was found to be inflexible, and in August 2003
+Docutils adopted the current component-based configuration file
+sections as described above.  Docutils will still recognize the old
+"[options]" section, but complains with a deprecation warning.
+
+To convert existing config files, the easiest way is to change the
+section title: change "[options]" to "[general]".  Most settings
+haven't changed.  The only ones to watch out for are these:
+
+=====================  =====================================
+Old-Format Setting     New Section & Setting
+=====================  =====================================
+pep_stylesheet         [pep_html writer] stylesheet
+pep_stylesheet_path    [pep_html writer] stylesheet_path
+pep_template           [pep_html writer] template
+=====================  =====================================
diff --git a/docs/user/latex.txt b/docs/user/latex.txt
new file mode 100644
index 000000000..d66586bc7
--- /dev/null
+++ b/docs/user/latex.txt
@@ -0,0 +1,388 @@
+================================
+ Generating LaTeX with Docutils
+================================
+
+:Author: Engelbert Gruber
+:Contact: grubert@users.sourceforge.net
+:Revision: $Revision$
+:Date: $Date$
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+
+Introduction
+============
+
+Producing LaTeX code from reST input could be done in at least two ways:
+
+a. Transform the internal markup into corresponding LaTeX markup e.g.
+   a section title would be written as ```\section{this section ...}``.
+b. Using LaTeX as a typesetting system to produce desired paperwork
+   without caring about loosing document structure information.
+
+The former might be preferable, but limits to LaTeXs capabilities, so 
+in reality it is a mix. The reality is that LaTeX has a titlepage with
+title, author and date, by default only title is used. Author and date
+are shown in the docutils docinfo table and set to blank for LaTeX.
+To get author and date set by LaTeX specify option "use-LaTeX-docinfo".
+
+Options
+=======
+
+Configuration can be done in two ways (again):
+
+1. Options to the docutils tool: e.g. language selection.
+2. Options to LaTeX via the stylesheet file.
+
+The generated LaTeX documents should be kept processable by a standard
+LaTeX installation (if such a thing exists), therefore the document
+contains default settings. To allow *overwriting defaults* the stylesheet
+is included at last.
+
+Run ``rst2latex.py --help`` to see the command-line options, or have look in
+config documentytion.
+
+
+=====================  ================================================
+Configuration Issue    Description
+=====================  ================================================
+papersize              Default: a4paper. Paper geometry can be changed  
+                       using ``\geometry{xxx}`` entries.
+
+                       Some possibilities:
+
+                       * a4paper, b3paper, letterpaper, executivepaper,
+                         legalpaper
+                       * landscape, portrait, twoside.
+
+                       and a ton of other option setting margins.
+
+                       An example::
+
+                         \geometry{a5paper,landscape}
+---------------------  ------------------------------------------------
+paragraph indent       By default LaTeX indents the forst line in a
+                       paragraph. The following lines set indentation 
+                       to zero but add a vertical space between 
+                       paragraphs.::
+
+                         \setlength{\parindent}{0pt}
+                         \setlength{\parskip}{6pt plus 2pt minus 1pt}
+---------------------  ------------------------------------------------
+admonitionwidth        The width for admonitions.
+                       Default: 0.9*textwidth, this can be changed 
+                       e.g.::
+
+                         \setlength{\admonitionwidth}{0.7\textwidth}
+---------------------  ------------------------------------------------
+docinfowidth           The width for the docinfo table.
+                       Default: 0.9*textwidth, changed to e.g.::
+
+                         \setlength{\docinfowidth}{0.7\textwidth}
+---------------------  ------------------------------------------------
+rubric style           The header contains the definition of a new
+                       LaTeX command rubric. Inserting::
+
+                         \renewcommand{\rubric}[1]{\subsection*{
+                           ~\hfill {\color{red} #1} \hfill ~}}
+
+                       sets rubric to subsection style in red.
+
+                       Default: subsection style italic.
+---------------------  ------------------------------------------------
+line spacing           Is done with package *setspace*, which gives
+                       singlespace, onehalfspace and doublespace 
+                       commands. To get documentwide double spacing, 
+                       add this to your stylesheet ::
+
+                         \usepackage{setspace} 
+                         \doublespacing
+
+                       Another way ::
+
+                         \linespread{1.55}
+
+                       And yet another, add ``doublesp`` to the
+                       documentoptions and e.g. ::
+
+                         \setstretch{1.7}
+
+                       for bigger linespacing.
+---------------------  ------------------------------------------------
+font selection         see below
+=====================  ================================================
+
+
+Font selection
+--------------
+
+When generating pdf-files from LaTeX, use the pdflatex command, the files
+are a lot smaller if postscript fonts are used. This *was* fixed by putting 
+``\usepackage{times}`` into the stylesheet. 
+
+It is said that the typewriter font in computer modern font, the default
+LaTeX font package, is too heavy compared to the others. There is a package
+or some commands too fix this, which i currently cannot find.
+
+Some people diagnose a similar unbalance for the postscript fonts, the
+package to fix this is ``\usepackage{pslatex}``.
+pslatex in contrast to the standard LaTeX fonts has a bold typewriter font.
+
+As ``times`` does not use the appropriate mathematical fonts and ``pslatex``
+does not work with T1 encodings one should use::
+
+  \usepackage{mathptmx}
+  \usepackage[scaled=.90]{helvet}
+  \usepackage{courier}
+
+*font encoding* can be selected with option "font-encoding". Default
+uses package "ae" for old style font encoding use "OT1". 
+
+Hyphenation
+-----------
+
+The amount of hyphenation is influenced by ``\hyphenpenalty``, setting it to 
+10000 almost prevents hyphenation. As this produces lines with more spcea 
+between words one should increase LaTeX's ``\tolerance`` for this.
+
+E.g. try ::
+
+  \hyphenpenalty=5000
+  \tolerance=1000
+
+Unicode
+-------
+
+The generated LaTeX documents are in latin1 encoding per default, if unicode
+characters are required one must set ``--output-encoding=utf-8`` install
+`LaTeX unicode`_ support and add::
+
+    \usepackage{ucs}
+    \usepackage[utf8]{inputenc}
+
+to the stylesheet. If LaTeX issues a Warning about unloaded/known characters
+adding ::
+
+    \PreloadUnicodePage{n}
+
+where *n* is the unicode pagenumber, might help.
+
+.. _LaTeX unicode: http://www.unruh.de/DniQ/latex/unicode/
+
+Table of figures
+----------------
+
+A table of figures can be generated by a command directly to LaTeX::
+
+  .. raw:: LaTeX
+
+     \listoffigures
+
+LaTeX also has a command ``\listoftables``.
+
+Section numbering
+-----------------
+
+If section numbering and LaTeX table of contents is used LaTeX and 
+docutils will number sections. To switch off displaying of LaTeX's
+numbers one has to add following lines to the stylesheet ::
+
+  % no section number display
+  \makeatletter
+  \def\@seccntformat#1{}
+  \makeatother
+  % no numbers in toc
+  \renewcommand{\numberline}[1]{}
+
+
+Number pages by chapter
+-----------------------
+
+This can be accomplished with ::
+
+  \usepackage{chappg}
+
+From the documentation 
+
+  Basic operation of the package is to redefine ``\thepage`` to be
+  ``\thechapter-\arabic{page}``, and to cause the page number to be reset
+  (to 1) at the start of each chapter.  So the pages of chapter 3 will
+  be numbered 3-1, 3-2, ..., and the pages of appendix B will be
+  numbered B-1, B-2, ...
+
+See documentation for details and other possibilities.
+
+Images
+------
+
+Images are included in LaTeX by the graphicx package. The supported
+image formats depend on the used driver (dvi, dvips, pdftex, ...).
+
+pdf-image inclusion in pdf files fails, specify ``--graphicx-option=pdftex``
+or ``--graphicx-option=auto``.
+
+
+Commands directly to LaTeX
+==========================
+
+By means of the reST-raw directive one can give commands directly to 
+LaTeX, e.g. forcing a page break::
+
+  .. raw:: LaTeX
+
+     \newpage
+
+
+Or setting formulas in LaTeX::
+
+  .. raw:: LaTeX
+
+     $$x^3 + 3x^2a + 3xa^2 + a^3,$$
+
+
+Or making a colorbox: If someone wants to get a red background for a textblock,
+she/he can put \definecolor{bg}{rgb}{.9,0,0} into style.tex and in
+reStructuredText do something like this::
+
+  |begincolorbox|
+  Nobody expects the spanish inquisition.
+  |endcolorbox|
+
+  .. |begincolorbox| raw:: LaTeX
+
+     \\begin{center}
+     \\colorbox{bg}{
+     \\parbox{0.985\\linewidth}{
+
+  .. |endcolorbox| raw:: LaTeX
+
+     }}
+     \\end{center}
+
+
+Custom title page
+-----------------
+
+Currently maketitle only shows the title and subtitle, date and author are shown 
+in the docinfo table.
+
+To change the titlepage layout, e.g. see fancyhdr, one must redefine the
+maketitle command in the stylesheet::
+
+  \renewcommand{\maketitle}{
+    \begin{titlepage}
+      \begin{center}
+      \textsf{TITLE \@title} \\
+      Date: \today
+      \end{center}
+    \end{titlepage}
+  }
+
+``\@title`` contains the title.
+
+Problems
+========
+
+Open to be fixed or open to discussion.
+
+footnotes and citations
+-----------------------
+
+Initially both were implemented using figures, because hyperlinking back
+and forth seemed to be impossible. Later images were put into figures.
+
+This results in footnotes images and figures possibly being mixed at page 
+foot.
+
+* Use LaTeX footnotes and citations for printing or more complex layout.
+* Footnotes and citations done with figures might excell in hyperlink
+  support.
+
+If ``use-latex-citations`` is used a bibliography is inserted right at
+the end of the document. *This should be customizable*.
+
+Tables
+------
+
+:Tablewidth: reST-documents line length is assumed to be 80 characters. The
+             tablewidth is set relative to this value. If someone produces
+             documents with line length of 132 this will fail.
+
+             Table width is tried to fit in page even if it is wider than
+             the assumed linewidth, still assumed linewidth is a hook. 
+
+* In tools.txt the option tables right column, there should be some more spacing
+  between the description and the next paragraph "Default:".
+
+  Paragraph separation in tables is hairy. 
+  see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab
+
+  - The strut solution did not work.
+  - setting extrarowheight added ad top of row not between paragraphs in
+    a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.
+  - baselineskip/stretch does not help.
+* Should there be two hlines after table head and on table end ?
+* Table: multicol cells are always {l}.
+* The contents of a rowspan cell do not influence table height.
+  (Maybe if we put a tabular inside ?)
+* Table heads and footer for longtable (firstpage lastpage ..).
+* Table cells with multirow and multicolumn
+* literal-blocks in table cells: 
+
+  - If verbatim or flushleft is used one gets vertical space above and below.
+  - This is bad for the topmost paragraph in a cell, therefore the writer
+    uses raggedright. 
+  - Ragged right fails on followup paragraphs as the vertical space would be
+    missing.
+
+Notes
+~~~~~
+
+* table-style booktabs: booktabs.sty 1.00 does not work with longtable.
+
+Miscellaneous
+-------------
+
+* Selection of LaTeX fontsize configurable.
+* Assumed reST linelength for table width setting configurable.
+* literal-block indentation configurable.
+* recongize LaTeX and replace by ``\LaTeX``.
+* Support embed-stylesheet.
+* Sidebar handling.
+* Maybe add end of line after term in definition list. see
+    http://roundup.sf.net/doc-0.5/features.pdf
+* Pdfbookmark level 4 (and greater) does not work (might be settable but OTOH).
+* center subsection{Abstract} gives a LaTeX error here.
+  ``! LaTeX Error: Something's wrong--perhaps a missing \item.``
+  Committed a HACK: centering by hfill.
+* Document errors are also too silent.
+* Use optionlist for docinfo, the table does only work for single page.
+* Consider peter funk's hooks for TeXpert:
+  
+  * Define his own document preamble (including the choice to
+    choose his own documentclass.  That would make the ``--documentclass``
+    option superfluous).  I suggest to call this option ``--preamble``
+  * Use two additional hooks to put additional stuff just behind the 
+    ``\begin{document}`` and just before the ``\end{document}`` macros.
+    Typical uses would be ``\tableofcontents``, ``\listoffigures`` and
+    ``\appendix``, ``\makeindex``, ``\makeglossary`` and some such 
+    for larger documents.
+
+* The indentional problematic error in docs/user/rst/demo.txt is not
+  referring anywhere.
+* Footnotes are not all on the same page (as in
+  docs/user/rst/demo.txt) and do not link back and forth.
+* No link to system errors.
+* Hyperlinks are not hyphenated; this leads to bad spacing. See
+  docs/user/rst/demo.txt 2.14 directives.
+* Meta keywords into pdf ?
+* Pagestyle headings does not work, when sections are starred.
+* For additional docinfo items: the field_body is inserted as text, i.e. no
+  markup is done.
+* Multiple author entries in docinfo (same thing as in html).
+* keep literal-blocks together on a page, avoid pagebreaks.
+
+  failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before
+  the block.
+
diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt
new file mode 100644
index 000000000..03eddf814
--- /dev/null
+++ b/docs/user/rst/cheatsheet.txt
@@ -0,0 +1,121 @@
+=====================================================
+ 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$
+:Revision: $Revision$
+:Description: This is a "docinfo block", or bibliographic field list
+
+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
+================  ============================================================
+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 <cheatsheet.txt>`_)
+================  ============================================================
+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
+================  ============================================================
+
+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]
+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 (requires Python 2.3+) [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
+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
+class             Set a "class" attribute on the next element
+role              Create a custom interpreted text role [0.3.2]
+================  ============================================================
+
+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
+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
+================  ============================================================
diff --git a/docs/user/rst/demo.txt b/docs/user/rst/demo.txt
new file mode 100644
index 000000000..7e57b6bad
--- /dev/null
+++ b/docs/user/rst/demo.txt
@@ -0,0 +1,550 @@
+.. 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: goodger@users.sourceforge.net
+:Authors: Me; Myself; I
+:organization: humankind
+:date: $Date$
+:status: This is a "work in progress"
+:revision: $Revision$
+: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.
+
+There should be five messages in the following, auto-generated
+section, "Docutils System Messages":
+
+.. section should be added by Docutils automatically
diff --git a/docs/user/rst/images/ball1.gif b/docs/user/rst/images/ball1.gif
new file mode 100644
index 000000000..3e14441d9
--- /dev/null
+++ b/docs/user/rst/images/ball1.gif
diff --git a/docs/user/rst/images/biohazard.png b/docs/user/rst/images/biohazard.png
new file mode 100644
index 000000000..ae4629d8b
--- /dev/null
+++ b/docs/user/rst/images/biohazard.png
diff --git a/docs/user/rst/images/title.png b/docs/user/rst/images/title.png
new file mode 100644
index 000000000..cc6218efe
--- /dev/null
+++ b/docs/user/rst/images/title.png
diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html
new file mode 100644
index 000000000..e391763c2
--- /dev/null
+++ b/docs/user/rst/quickref.html
@@ -0,0 +1,1319 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+   "http://www.w3.org/TR/html4/loose.dtd">
+
+<html>
+  <head>
+    <title>Quick reStructuredText</title>
+    <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+
+    <style type="text/css"><!--
+      a.backref { text-decoration: none ; color: black }
+      div.line-block { display: block }
+      div.line-block div.line-block { margin-left: 1.5em }
+    --></style>
+
+  </head>
+
+  <body>
+    <h1>Quick <i>re</i><font size="+4"><tt>Structured</tt></font><i>Text</i></h1>
+
+    <!-- Caveat: if you're reading the HTML for the examples, -->
+    <!-- beware that it was hand-generated, not by Docutils/ReST.  -->
+
+    <p align="right"><em><a href="http://docutils.sourceforge.net/docs/user/rst/quickref.html"
+    >http://docutils.sourceforge.net/docs/user/rst/quickref.html</a></em>
+    <br><em>Being a cheat-sheet for reStructuredText</em>
+    <br><em>Updated $Date$</em>
+
+    <blockquote>
+      <p>Copyright: This document has been placed in the public domain.
+    </blockquote>
+
+
+    <p>The full details of the markup may be found on the
+      <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>
+      page. This document is just intended as a reminder.
+
+    <p>Links that look like "(<a href="#details">details</a>)" point
+      into the HTML version of the full <a
+      href="../../ref/rst/restructuredtext.html">reStructuredText
+      specification</a> document.  These are relative links; if they
+      don't work, please use the <a
+      href="http://docutils.sourceforge.net/docs/user/rst/quickref.html"
+      >master "Quick reStructuredText"</a> document.
+
+    <h2><a name="contents">Contents</a></h2>
+
+    <ul>
+    <li><a href="#inline-markup">Inline Markup</a></li>
+    <li><a href="#escaping">Escaping with Backslashes</a></li>
+    <li><a href="#section-structure">Section Structure</a></li>
+    <li><a href="#paragraphs">Paragraphs</a></li>
+    <li><a href="#bullet-lists">Bullet Lists</a></li>
+    <li><a href="#enumerated-lists">Enumerated Lists</a></li>
+    <li><a href="#definition-lists">Definition Lists</a></li>
+    <li><a href="#field-lists">Field Lists</a></li>
+    <li><a href="#option-lists">Option Lists</a></li>
+    <li><a href="#literal-blocks">Literal Blocks</a></li>
+    <li><a href="#line-blocks">Line Blocks</a></li>
+    <li><a href="#block-quotes">Block Quotes</a></li>
+    <li><a href="#doctest-blocks">Doctest Blocks</a></li>
+    <li><a href="#tables">Tables</a></li>
+    <li><a href="#transitions">Transitions</a></li>
+    <li><a href="#explicit-markup">Explicit Markup</a>
+    <ul>
+    <li><a href="#footnotes">Footnotes</a></li>
+    <li><a href="#citations">Citations</a></li>
+    <li><a href="#hyperlink-targets">Hyperlink Targets</a>
+    <ul>
+    <li><a href="#external-hyperlink-targets">External Hyperlink Targets</a></li>
+    <li><a href="#internal-hyperlink-targets">Internal Hyperlink Targets</a></li>
+    <li><a href="#indirect-hyperlink-targets">Indirect Hyperlink Targets</a></li>
+    <li><a href="#implicit-hyperlink-targets">Implicit Hyperlink Targets</a></li>
+    </ul></li>
+    <li><a href="#directives">Directives</a></li>
+    <li><a href="#substitution-references-and-definitions">Substitution References and Definitions</a></li>
+    <li><a href="#comments">Comments</a></li>
+    </ul></li>
+    <li><a href="#getting-help">Getting Help</a></li>
+    </ul>
+
+    <h2><a href="#contents" name="inline-markup" class="backref"
+        >Inline Markup</a></h2>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#inline-markup">details</a>)
+
+    <p>Inline markup allows words and phrases within text to have
+    character styles (like italics and boldface) and functionality
+    (like hyperlinks).
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th>Plain text
+      <th>Typical result
+      <th>Notes
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td nowrap><samp>*emphasis*</samp>
+      <td><em>emphasis</em>
+      <td>Normally rendered as italics.
+
+    <tr valign="top">
+      <td nowrap><samp>**strong&nbsp;emphasis**</samp>
+      <td><strong>strong emphasis</strong>
+      <td>Normally rendered as boldface.
+
+    <tr valign="top">
+      <td nowrap><samp>`interpreted&nbsp;text`</samp>
+      <td>(see note at right)
+      <td>The rendering and <em>meaning</em> of interpreted text is
+      domain- or application-dependent.  It can be used for things
+      like index entries or explicit descriptive markup (like program
+      identifiers).
+
+    <tr valign="top">
+      <td nowrap><samp>``inline&nbsp;literal``</samp>
+      <td><code>inline&nbsp;literal</code>
+      <td>Normally rendered as monospaced text. Spaces should be
+      preserved, but line breaks will not be.
+
+    <tr valign="top">
+      <td nowrap><samp>reference_</samp>
+      <td><a href="#hyperlink-targets">reference</a>
+      <td>A simple, one-word hyperlink reference.  See <a
+      href="#hyperlinks" >Hyperlinks</a>.
+
+    <tr valign="top">
+      <td nowrap><samp>`phrase reference`_</samp>
+      <td><a href="#hyperlink-targets">phrase reference</a>
+      <td>A hyperlink reference with spaces or punctuation needs to be
+      quoted with backquotes.  See <a
+      href="#hyperlink-targets">Hyperlinks</a>.
+
+    <tr valign="top">
+      <td nowrap><samp>anonymous__</samp>
+      <td><a href="#hyperlink-targets">anonymous</a>
+      <td>With two underscores instead of one, both simple and phrase
+      references may be anonymous (the reference text is not repeated
+      at the target).  See <a
+      href="#hyperlink-targets">Hyperlinks</a>.
+
+    <tr valign="top">
+      <td nowrap><samp>_`inline internal target`</samp>
+      <td><a name="inline-internal-target">inline internal target</a>
+      <td>A crossreference target within text.
+      See <a href="#hyperlink-targets">Hyperlinks</a>.
+
+    <tr valign="top">
+      <td nowrap><samp>|substitution reference|</samp>
+      <td>(see note at right)
+      <td>The result is substituted in from the <a
+      href="#substitution-references-and-definitions">substitution
+      definition</a>.  It could be text, an image, a hyperlink, or a
+      combination of these and others.
+
+    <tr valign="top">
+      <td nowrap><samp>footnote reference [1]_</samp>
+      <td>footnote reference <sup><a href="#footnotes">1</a></sup>
+      <td>See <a href="#footnotes">Footnotes</a>.
+
+    <tr valign="top">
+      <td nowrap><samp>citation reference [CIT2002]_</samp>
+      <td>citation reference <a href="#citations">[CIT2002]</a>
+      <td>See <a href="#citations">Citations</a>.
+
+    <tr valign="top">
+      <td nowrap><samp>http://docutils.sf.net/</samp>
+      <td><a href="http://docutils.sf.net/">http://docutils.sf.net/</a>
+      <td>A standalone hyperlink.
+
+    </table>
+
+    <p>Asterisk, backquote, vertical bar, and underscore are inline
+    delimiter characters. Asterisk, backquote, and vertical bar act
+    like quote marks; matching characters surround the marked-up word
+    or phrase, whitespace or other quoting is required outside them,
+    and there can't be whitespace just inside them. If you want to use
+    inline delimiter characters literally, <a href="#escaping">escape
+    (with backslash)</a> or quote them (with double backquotes; i.e.
+    use inline literals).
+
+    <p>In detail, the reStructuredText specification says that in
+      inline markup, the following rules apply to start-strings and
+      end-strings (inline markup delimiters):
+
+    <ol>
+      <li>The start-string must start a text block or be
+    immediately preceded by whitespace or any of&nbsp;
+    <samp>' " ( [ {</samp> or&nbsp;<samp>&lt;</samp>.
+      <li>The start-string must be immediately followed by non-whitespace.
+      <li>The end-string must be immediately preceded by non-whitespace.
+      <li>The end-string must end a text block (end of document or
+    followed by a blank line) or be immediately followed by whitespace
+    or any of&nbsp;<samp>' " . , : ; ! ? - ) ] } / \</samp> 
+    or&nbsp;<samp>&gt;</samp>.
+      <li>If a start-string is immediately preceded by one of&nbsp;
+    <samp>' " ( [ {</samp> or&nbsp;<samp>&lt;</samp>, it must not be
+    immediately followed by the corresponding character from&nbsp;
+    <samp>' " ) ] }</samp> or&nbsp;<samp>&gt;</samp>.
+      <li>An end-string must be separated by at least one
+    character from the start-string.
+      <li>An <a href="#escaping">unescaped</a> backslash preceding a
+    start-string or end-string will disable markup recognition, except
+    for the end-string of inline literals.
+    </ol>
+
+    <p>Also remember that inline markup may not be nested (well,
+      except that inline literals can contain any of the other inline
+      markup delimiter characters, but that doesn't count because
+      nothing is processed).
+
+    <h2><a href="#contents" name="escaping" class="backref"
+        >Escaping with Backslashes</a></h2>
+
+    <p>(<a
+    href="../../ref/rst/restructuredtext.html#escaping-mechanism">details</a>)
+
+    <p>reStructuredText uses backslashes ("\") to override the special
+    meaning given to markup characters and get the literal characters
+    themselves. To get a literal backslash, use an escaped backslash
+    ("\\"). For example:
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Raw reStructuredText
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top"><td>
+        <samp>*escape*&nbsp;``with``&nbsp;"\"</samp>
+      <td><em>escape</em> <samp>with</samp> ""
+    <tr valign="top"><td>
+        <samp>\*escape*&nbsp;\``with``&nbsp;"\\"</samp>
+      <td>*escape* ``with`` "\"
+    </table>
+
+    <p>In Python strings it will, of course, be necessary
+      to escape any backslash characters so that they actually
+      <em>reach</em> reStructuredText.
+      The simplest way to do this is to use raw strings:
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Python string
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top"><td>
+        <samp>r"""\*escape*&nbsp;\`with`&nbsp;"\\""""</samp>
+      <td>*escape* `with` "\"
+    <tr valign="top"><td>
+        <samp>&nbsp;"""\\*escape*&nbsp;\\`with`&nbsp;"\\\\""""</samp>
+      <td>*escape* `with` "\"
+    <tr valign="top"><td>
+        <samp>&nbsp;"""\*escape*&nbsp;\`with`&nbsp;"\\""""</samp>
+      <td><em>escape</em> with ""
+    </table>
+
+    <h2><a href="#contents" name="section-structure" class="backref"
+        >Section Structure</a></h2>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#sections">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td>
+<samp>=====</samp>
+<br><samp>Title</samp>
+<br><samp>=====</samp>
+<br><samp>Subtitle</samp>
+<br><samp>--------</samp>
+<br><samp>Titles&nbsp;are&nbsp;underlined&nbsp;(or&nbsp;over-</samp>
+<br><samp>and&nbsp;underlined)&nbsp;with&nbsp;a&nbsp;printing</samp>
+<br><samp>nonalphanumeric&nbsp;7-bit&nbsp;ASCII</samp>
+<br><samp>character.&nbsp;Recommended&nbsp;choices</samp>
+<br><samp>are&nbsp;"``=&nbsp;-&nbsp;`&nbsp;:&nbsp;'&nbsp;"&nbsp;~&nbsp;^&nbsp;_&nbsp;*&nbsp;+&nbsp;#&nbsp;&lt;&nbsp;&gt;``".</samp>
+<br><samp>The&nbsp;underline/overline&nbsp;must&nbsp;be&nbsp;at</samp>
+<br><samp>least&nbsp;as&nbsp;long&nbsp;as&nbsp;the&nbsp;title&nbsp;text.</samp>
+<br><samp></samp>
+<br><samp>A&nbsp;lone&nbsp;top-level&nbsp;(sub)section</samp>
+<br><samp>is&nbsp;lifted&nbsp;up&nbsp;to&nbsp;be&nbsp;the&nbsp;document's</samp>
+<br><samp>(sub)title.</samp>
+
+      <td>
+        <font size="+2"><strong>Title</strong></font>
+        <p><font size="+1"><strong>Subtitle</strong></font>
+        <p>Titles are underlined (or over-
+          and underlined) with a printing
+          nonalphanumeric 7-bit ASCII
+          character. Recommended choices
+          are "<samp>= - ` : ' " ~ ^ _ * + # &lt; &gt;</samp>".
+          The underline/overline must be at
+          least as long as the title text.
+        <p>A lone top-level (sub)section is
+          lifted up to be the document's
+          (sub)title.
+    </table>
+
+    <h2><a href="#contents" name="paragraphs" class="backref"
+        >Paragraphs</a></h2>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#paragraphs">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td>
+<p><samp>This&nbsp;is&nbsp;a&nbsp;paragraph.</samp>
+
+<p><samp>Paragraphs&nbsp;line&nbsp;up&nbsp;at&nbsp;their&nbsp;left</samp>
+<br><samp>edges,&nbsp;and&nbsp;are&nbsp;normally&nbsp;separated</samp>
+<br><samp>by&nbsp;blank&nbsp;lines.</samp>
+
+      <td>
+        <p>This is a paragraph.
+
+        <p>Paragraphs line up at their left edges, and are normally
+        separated by blank lines.
+
+    </table>
+
+    <h2><a href="#contents" name="bullet-lists" class="backref"
+        >Bullet Lists</a></h2>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#bullet-lists">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td>
+<samp>Bullet&nbsp;lists:</samp>
+
+<p><samp>-&nbsp;This&nbsp;is&nbsp;item&nbsp;1</samp>
+<br><samp>-&nbsp;This&nbsp;is&nbsp;item&nbsp;2</samp>
+
+<p><samp>-&nbsp;Bullets&nbsp;are&nbsp;"-",&nbsp;"*"&nbsp;or&nbsp;"+".</samp>
+<br><samp>&nbsp;&nbsp;Continuing&nbsp;text&nbsp;must&nbsp;be&nbsp;aligned</samp>
+<br><samp>&nbsp;&nbsp;after&nbsp;the&nbsp;bullet&nbsp;and&nbsp;whitespace.</samp>
+
+<p><samp>Note&nbsp;that&nbsp;a&nbsp;blank&nbsp;line&nbsp;is&nbsp;required</samp>
+<br><samp>before&nbsp;the&nbsp;first&nbsp;item&nbsp;and&nbsp;after&nbsp;the</samp>
+<br><samp>last,&nbsp;but&nbsp;is&nbsp;optional&nbsp;between&nbsp;items.</samp>
+      <td>Bullet lists:
+        <ul>
+          <li>This is item 1
+          <li>This is item 2
+          <li>Bullets are "-", "*" or "+".
+        Continuing text must be aligned
+        after the bullet and whitespace.
+        </ul>
+        <p>Note that a blank line is required before the first
+          item and after the last, but is optional between items.
+    </table>
+
+    <h2><a href="#contents" name="enumerated-lists" class="backref"
+        >Enumerated Lists</a></h2>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#enumerated-lists">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td>
+<samp>Enumerated&nbsp;lists:</samp>
+
+<p><samp>3.&nbsp;This&nbsp;is&nbsp;the&nbsp;first&nbsp;item</samp>
+<br><samp>4.&nbsp;This&nbsp;is&nbsp;the&nbsp;second&nbsp;item</samp>
+<br><samp>5.&nbsp;Enumerators&nbsp;are&nbsp;arabic&nbsp;numbers,</samp>
+<br><samp>&nbsp;&nbsp;&nbsp;single&nbsp;letters,&nbsp;or&nbsp;roman&nbsp;numerals</samp>
+<br><samp>6.&nbsp;List&nbsp;items&nbsp;should&nbsp;be&nbsp;sequentially</samp>
+<br><samp>&nbsp;&nbsp;&nbsp;numbered,&nbsp;but&nbsp;need&nbsp;not&nbsp;start&nbsp;at&nbsp;1</samp>
+<br><samp>&nbsp;&nbsp;&nbsp;(although&nbsp;not&nbsp;all&nbsp;formatters&nbsp;will</samp>
+<br><samp>&nbsp;&nbsp;&nbsp;honour&nbsp;the&nbsp;first&nbsp;index).</samp>
+<br><samp>#.&nbsp;This&nbsp;item&nbsp;is&nbsp;auto-enumerated</samp>
+      <td>Enumerated lists:
+        <ol type="1">
+          <li value="3">This is the first item
+          <li>This is the second item
+          <li>Enumerators are arabic numbers, single letters,
+        or roman numerals
+          <li>List items should be sequentially numbered,
+        but need not start at 1 (although not all
+        formatters will honour the first index).
+          <li>This item is auto-enumerated
+        </ol>
+    </table>
+
+    <h2><a href="#contents" name="definition-lists" class="backref"
+        >Definition Lists</a></h2>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#definition-lists">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td>
+<samp>Definition&nbsp;lists:</samp>
+<br>
+<br><samp>what</samp>
+<br><samp>&nbsp;&nbsp;Definition&nbsp;lists&nbsp;associate&nbsp;a&nbsp;term&nbsp;with</samp>
+<br><samp>&nbsp;&nbsp;a&nbsp;definition.</samp>
+<br>
+<br><samp>how</samp>
+<br><samp>&nbsp;&nbsp;The&nbsp;term&nbsp;is&nbsp;a&nbsp;one-line&nbsp;phrase,&nbsp;and&nbsp;the</samp>
+<br><samp>&nbsp;&nbsp;definition&nbsp;is&nbsp;one&nbsp;or&nbsp;more&nbsp;paragraphs&nbsp;or</samp>
+<br><samp>&nbsp;&nbsp;body&nbsp;elements,&nbsp;indented&nbsp;relative&nbsp;to&nbsp;the</samp>
+<br><samp>&nbsp;&nbsp;term.&nbsp;Blank&nbsp;lines&nbsp;are&nbsp;not&nbsp;allowed</samp>
+<br><samp>&nbsp;&nbsp;between&nbsp;term&nbsp;and&nbsp;definition.</samp>
+      <td>Definition lists:
+        <dl>
+          <dt><strong>what</strong>
+          <dd>Definition lists associate a term with
+        a definition.
+
+          <dt><strong>how</strong>
+          <dd>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.
+        </dl>
+    </table>
+
+    <h2><a href="#contents" name="field-lists" class="backref"
+        >Field Lists</a></h2>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#field-lists">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td>
+<samp>:Authors:</samp>
+<br><samp>&nbsp;&nbsp;&nbsp;&nbsp;Tony&nbsp;J.&nbsp;(Tibs)&nbsp;Ibbs,</samp>
+<br><samp>&nbsp;&nbsp;&nbsp;&nbsp;David&nbsp;Goodger</samp>
+
+<p><samp>&nbsp;&nbsp;&nbsp;&nbsp;(and&nbsp;sundry&nbsp;other&nbsp;good-natured&nbsp;folks)</samp>
+
+<p><samp>:Version:&nbsp;1.0&nbsp;of&nbsp;2001/08/08</samp>
+<br><samp>:Dedication:&nbsp;To&nbsp;my&nbsp;father.</samp>
+      <td>
+        <table>
+          <tr valign="top">
+        <td><strong>Authors:</strong>
+        <td>Tony J. (Tibs) Ibbs,
+          David Goodger
+          <tr><td><td>(and sundry other good-natured folks)
+          <tr><td><strong>Version:</strong><td>1.0 of 2001/08/08
+          <tr><td><strong>Dedication:</strong><td>To my father.
+        </table>
+    </table>
+
+    <p>Field lists are used as part of an extension syntax, such as
+    options for <a href="#directives">directives</a>, or database-like
+    records meant for further processing.  Field lists may also be
+    used as generic two-column table constructs in documents.
+
+    <h2><a href="#contents" name="option-lists" class="backref"
+        >Option Lists</a></h2>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#option-lists">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+      <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td>
+        <p><samp>
+-a&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;command-line&nbsp;option&nbsp;"a"
+<br>-b&nbsp;file&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;options&nbsp;can&nbsp;have&nbsp;arguments
+<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;and&nbsp;long&nbsp;descriptions
+<br>--long&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;options&nbsp;can&nbsp;be&nbsp;long&nbsp;also
+<br>--input=file&nbsp;&nbsp;long&nbsp;options&nbsp;can&nbsp;also&nbsp;have
+<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;arguments
+<br>/V&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;DOS/VMS-style&nbsp;options&nbsp;too
+</samp>
+
+      <td>
+        <table border="0" width="100%">
+          <tbody valign="top">
+            <tr>
+              <td width="30%"><samp>-a</samp>
+              <td>command-line option "a"
+            <tr>
+              <td><samp>-b <i>file</i></samp>
+              <td>options can have arguments and long descriptions
+            <tr>
+              <td><samp>--long</samp>
+              <td>options can be long also
+            <tr>
+              <td><samp>--input=<i>file</i></samp>
+              <td>long options can also have arguments
+            <tr>
+              <td><samp>/V</samp>
+              <td>DOS/VMS-style options too
+        </table>
+    </table>
+
+    <p>There must be at least two spaces between the option and the
+    description.
+
+    <h2><a href="#contents" name="literal-blocks" class="backref"
+        >Literal Blocks</a></h2>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#literal-blocks">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td>
+<samp>A&nbsp;paragraph&nbsp;containing&nbsp;only&nbsp;two&nbsp;colons</samp>
+<br><samp>indicates&nbsp;that&nbsp;the&nbsp;following&nbsp;indented</samp>
+<br><samp>or&nbsp;quoted&nbsp;text&nbsp;is&nbsp;a&nbsp;literal&nbsp;block.</samp>
+<br>
+<br><samp>::</samp>
+<br>
+<br><samp>&nbsp;&nbsp;Whitespace,&nbsp;newlines,&nbsp;blank&nbsp;lines,&nbsp;and</samp>
+<br><samp>&nbsp;&nbsp;all&nbsp;kinds&nbsp;of&nbsp;markup&nbsp;(like&nbsp;*this*&nbsp;or</samp>
+<br><samp>&nbsp;&nbsp;\this)&nbsp;is&nbsp;preserved&nbsp;by&nbsp;literal&nbsp;blocks.</samp>
+<br>
+<br><samp>&nbsp;&nbsp;The&nbsp;paragraph&nbsp;containing&nbsp;only&nbsp;'::'</samp>
+<br><samp>&nbsp;&nbsp;will&nbsp;be&nbsp;omitted&nbsp;from&nbsp;the&nbsp;result.</samp>
+<br>
+<br><samp>The&nbsp;``::``&nbsp;may&nbsp;be&nbsp;tacked&nbsp;onto&nbsp;the&nbsp;very</samp>
+<br><samp>end&nbsp;of&nbsp;any&nbsp;paragraph.&nbsp;The&nbsp;``::``&nbsp;will&nbsp;be</samp>
+<br><samp>omitted&nbsp;if&nbsp;it&nbsp;is&nbsp;preceded&nbsp;by&nbsp;whitespace.</samp>
+<br><samp>The&nbsp;``::``&nbsp;will&nbsp;be&nbsp;converted&nbsp;to&nbsp;a&nbsp;single</samp>
+<br><samp>colon&nbsp;if&nbsp;preceded&nbsp;by&nbsp;text,&nbsp;like&nbsp;this::</samp>
+<br>
+<br><samp>&nbsp;&nbsp;It's&nbsp;very&nbsp;convenient&nbsp;to&nbsp;use&nbsp;this&nbsp;form.</samp>
+<br>
+<br><samp>Literal&nbsp;blocks&nbsp;end&nbsp;when&nbsp;text&nbsp;returns&nbsp;to</samp>
+<br><samp>the&nbsp;preceding&nbsp;paragraph's&nbsp;indentation.</samp>
+<br><samp>This&nbsp;means&nbsp;that&nbsp;something&nbsp;like&nbsp;this</samp>
+<br><samp>is&nbsp;possible::</samp>
+<br>
+<br><samp>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;We&nbsp;start&nbsp;here</samp>
+<br><samp>&nbsp;&nbsp;&nbsp;&nbsp;and&nbsp;continue&nbsp;here</samp>
+<br><samp>&nbsp;&nbsp;and&nbsp;end&nbsp;here.</samp>
+<br>
+<br><samp>Per-line&nbsp;quoting&nbsp;can&nbsp;also&nbsp;be&nbsp;used&nbsp;on</samp>
+<br><samp>unindented&nbsp;literal&nbsp;blocks:</samp>
+<br>
+<br><samp>&gt;&nbsp;Useful&nbsp;for&nbsp;quotes&nbsp;from&nbsp;email&nbsp;and</samp>
+<br><samp>&gt;&nbsp;for&nbsp;Haskell&nbsp;literate&nbsp;programming.</samp>
+
+      <td>
+        <p>A paragraph containing only two colons
+indicates that the following indented or quoted
+text is a literal block.
+
+        <pre>
+  Whitespace, newlines, blank lines, and
+  all kinds of markup (like *this* or
+  \this) is preserved by literal blocks.
+
+  The paragraph containing only '::'
+  will be omitted from the result.</pre>
+
+        <p>The <samp>::</samp> may be tacked onto the very
+end of any paragraph. The <samp>::</samp> will be
+omitted if it is preceded by whitespace.
+The <samp>::</samp> will be converted to a single
+colon if preceded by text, like this:
+
+        <pre>
+  It's very convenient to use this form.</pre>
+
+        <p>Literal blocks end when text returns to
+the preceding paragraph's indentation.
+This means that something like this is possible:
+
+        <pre>
+      We start here
+    and continue here
+  and end here.</pre>
+
+        <p>Per-line quoting can also be used on
+unindented literal blocks:
+
+        <pre>
+  &gt; Useful for quotes from email and
+  &gt; for Haskell literate programming.</pre>
+    </table>
+
+    <h2><a href="#contents" name="line-blocks" class="backref"
+        >Line Blocks</a></h2>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#line-blocks">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td>
+<samp>|&nbsp;Line&nbsp;blocks&nbsp;are&nbsp;useful&nbsp;for&nbsp;addresses,</samp>
+<br><samp>|&nbsp;verse,&nbsp;and&nbsp;adornment-free&nbsp;lists.</samp>
+<br><samp>|</samp>
+<br><samp>|&nbsp;Each&nbsp;new&nbsp;line&nbsp;begins&nbsp;with&nbsp;a</samp>
+<br><samp>|&nbsp;vertical&nbsp;bar&nbsp;("|").</samp>
+<br><samp>|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Line&nbsp;breaks&nbsp;and&nbsp;initial&nbsp;indents</samp>
+<br><samp>|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;are&nbsp;preserved.</samp>
+<br><samp>|&nbsp;Continuation&nbsp;lines&nbsp;are&nbsp;wrapped</samp>
+<br><samp>&nbsp;&nbsp;portions&nbsp;of&nbsp;long&nbsp;lines;&nbsp;they&nbsp;begin</samp>
+<br><samp>&nbsp;&nbsp;with&nbsp;spaces&nbsp;in&nbsp;place&nbsp;of&nbsp;vertical&nbsp;bars.</samp>
+
+      <td>
+        <div class="line-block">
+          <div class="line">Line blocks are useful for addresses,</div>
+          <div class="line">verse, and adornment-free lists.</div>
+          <div class="line"><br /></div>
+          <div class="line">Each new line begins with a</div>
+          <div class="line">vertical bar ("|").</div>
+          <div class="line-block">
+            <div class="line">Line breaks and initial indents</div>
+            <div class="line">are preserved.</div>
+          </div>
+          <div class="line">Continuation lines are wrapped portions
+            of long lines; they begin
+            with spaces in place of vertical bars.</div>
+        </div>
+    </table>
+
+    <h2><a href="#contents" name="block-quotes" class="backref"
+        >Block Quotes</a></h2>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#block-quotes">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+      <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td>
+<samp>Block&nbsp;quotes&nbsp;are&nbsp;just:</samp>
+
+<p><samp>&nbsp;&nbsp;&nbsp;&nbsp;Indented&nbsp;paragraphs,</samp>
+
+<p><samp>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;and&nbsp;they&nbsp;may&nbsp;nest.</samp>
+      <td>
+        Block quotes are just:
+        <blockquote>
+          <p>Indented paragraphs,
+          <blockquote>
+        <p>and they may nest.
+          </blockquote>
+        </blockquote>
+    </table>
+
+    <h2><a href="#contents" name="doctest-blocks" class="backref"
+        >Doctest Blocks</a></h2>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#doctest-blocks">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+      <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td>
+        <p><samp>Doctest&nbsp;blocks&nbsp;are&nbsp;interactive
+<br>Python&nbsp;sessions.&nbsp;They&nbsp;begin&nbsp;with
+<br>"``&gt;&gt;&gt;``"&nbsp;and&nbsp;end&nbsp;with&nbsp;a&nbsp;blank&nbsp;line.</samp>
+
+        <p><samp>&gt;&gt;&gt;&nbsp;print&nbsp;"This&nbsp;is&nbsp;a&nbsp;doctest&nbsp;block."
+<br>This&nbsp;is&nbsp;a&nbsp;doctest&nbsp;block.</samp>
+
+      <td>
+        <p>Doctest blocks are interactive
+        Python sessions. They begin with
+        "<samp>&gt;&gt;&gt;</samp>" and end with a blank line.
+
+        <p><samp>&gt;&gt;&gt;&nbsp;print&nbsp;"This&nbsp;is&nbsp;a&nbsp;doctest&nbsp;block."
+<br>This&nbsp;is&nbsp;a&nbsp;doctest&nbsp;block.</samp>
+    </table>
+
+    <p>"The <a
+    href="http://www.python.org/doc/current/lib/module-doctest.html">doctest</a>
+    module searches a module's docstrings for text that looks like an
+    interactive Python session, then executes all such sessions to
+    verify they still work exactly as shown." (From the doctest docs.)
+
+    <h2><a href="#contents" name="tables" class="backref"
+        >Tables</a></h2>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#tables">details</a>)
+
+    <p>There are two syntaxes for tables in reStructuredText.  Grid
+    tables are complete but cumbersome to create.  Simple tables are
+    easy to create but limited (no row spans, etc.).</p>
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td>
+<p><samp>Grid table:</samp></p>
+
+<p><samp>+------------+------------+-----------+</samp>
+<br><samp>|&nbsp;Header&nbsp;1&nbsp;&nbsp;&nbsp;|&nbsp;Header&nbsp;2&nbsp;&nbsp;&nbsp;|&nbsp;Header&nbsp;3&nbsp;&nbsp;|</samp>
+<br><samp>+============+============+===========+</samp>
+<br><samp>|&nbsp;body&nbsp;row&nbsp;1&nbsp;|&nbsp;column&nbsp;2&nbsp;&nbsp;&nbsp;|&nbsp;column&nbsp;3&nbsp;&nbsp;|</samp>
+<br><samp>+------------+------------+-----------+</samp>
+<br><samp>|&nbsp;body&nbsp;row&nbsp;2&nbsp;|&nbsp;Cells&nbsp;may&nbsp;span&nbsp;columns.|</samp>
+<br><samp>+------------+------------+-----------+</samp>
+<br><samp>|&nbsp;body&nbsp;row&nbsp;3&nbsp;|&nbsp;Cells&nbsp;may&nbsp;&nbsp;|&nbsp;-&nbsp;Cells&nbsp;&nbsp;&nbsp;|</samp>
+<br><samp>+------------+&nbsp;span&nbsp;rows.&nbsp;|&nbsp;-&nbsp;contain&nbsp;|</samp>
+<br><samp>|&nbsp;body&nbsp;row&nbsp;4&nbsp;|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;-&nbsp;blocks.&nbsp;|</samp>
+<br><samp>+------------+------------+-----------+</samp></p>
+      <td>
+        <p>Grid table:</p>
+        <table border="1">
+          <thead valign="bottom">
+            <tr>
+              <th>Header 1
+              <th>Header 2
+              <th>Header 3
+            </tr>
+          </thead>
+          <tbody valign="top">
+            <tr>
+              <td>body row 1
+              <td>column 2
+              <td>column 3
+            </tr>
+            <tr>
+              <td>body row 2
+              <td colspan="2">Cells may span columns.
+            </tr>
+            <tr>
+              <td>body row 3
+              <td rowspan="2">Cells may<br>span rows.
+              <td rowspan="2">
+                <ul>
+                  <li>Cells
+                  <li>contain
+                  <li>blocks.
+                </ul>
+            </tr>
+            <tr>
+              <td>body row 4
+            </tr>
+        </table>
+    <tr valign="top">
+      <td>
+<p><samp>Simple table:</samp></p>
+
+<p><samp>=====&nbsp;&nbsp;=====&nbsp;&nbsp;======</samp>
+<br><samp>&nbsp;&nbsp;&nbsp;Inputs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Output</samp>
+<br><samp>------------&nbsp;&nbsp;------</samp>
+<br><samp>&nbsp;&nbsp;A&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;B&nbsp;&nbsp;&nbsp;&nbsp;A&nbsp;or&nbsp;B</samp>
+<br><samp>=====&nbsp;&nbsp;=====&nbsp;&nbsp;======</samp>
+<br><samp>False&nbsp;&nbsp;False&nbsp;&nbsp;False</samp>
+<br><samp>True&nbsp;&nbsp;&nbsp;False&nbsp;&nbsp;True</samp>
+<br><samp>False&nbsp;&nbsp;True&nbsp;&nbsp;&nbsp;True</samp>
+<br><samp>True&nbsp;&nbsp;&nbsp;True&nbsp;&nbsp;&nbsp;True</samp>
+<br><samp>=====&nbsp;&nbsp;=====&nbsp;&nbsp;======</samp></p>
+
+      <td>
+        <p>Simple table:</p>
+        <table border="1">
+          <colgroup>
+            <col width="31%">
+            <col width="31%">
+            <col width="38%">
+          </colgroup>
+          <thead valign="bottom">
+            <tr>
+              <th colspan="2">Inputs
+              <th>Output
+            <tr>
+              <th>A
+              <th>B
+              <th>A or B
+          <tbody valign="top">
+            <tr>
+              <td>False
+              <td>False
+              <td>False
+            <tr>
+              <td>True
+              <td>False
+              <td>True
+            <tr>
+              <td>False
+              <td>True
+              <td>True
+            <tr>
+              <td>True
+              <td>True
+              <td>True
+        </table>
+
+    </table>
+
+    <h2><a href="#contents" name="transitions" class="backref"
+        >Transitions</a></h2>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#transitions">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+      <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td>
+        <p><samp>
+A&nbsp;transition&nbsp;marker&nbsp;is&nbsp;a&nbsp;horizontal&nbsp;line
+<br>of&nbsp;4&nbsp;or&nbsp;more&nbsp;repeated&nbsp;punctuation
+<br>characters.</samp>
+
+        <p><samp>------------</samp>
+
+        <p><samp>A&nbsp;transition&nbsp;should&nbsp;not&nbsp;begin&nbsp;or&nbsp;end&nbsp;a
+<br>section&nbsp;or&nbsp;document,&nbsp;nor&nbsp;should&nbsp;two
+<br>transitions&nbsp;be&nbsp;immediately&nbsp;adjacent.</samp>
+
+      <td>
+        <p>A transition marker is a horizontal line
+        of 4 or more repeated punctuation
+        characters.</p>
+
+        <hr>
+
+        <p>A transition should not begin or end a
+        section or document, nor should two
+        transitions be immediately adjacent.
+    </table>
+
+    <p>Transitions are commonly seen in novels and short fiction, as a
+    gap spanning one or more lines, marking text divisions or
+    signaling changes in subject, time, point of view, or emphasis.
+
+    <h2><a href="#contents" name="explicit-markup" class="backref"
+        >Explicit Markup</a></h2>
+
+    <p>Explicit markup blocks are used for constructs which float
+    (footnotes), have no direct paper-document representation
+    (hyperlink targets, comments), or require specialized processing
+    (directives).  They all begin with two periods and whitespace, the
+    "explicit markup start".
+
+    <h3><a href="#contents" name="footnotes" class="backref"
+        >Footnotes</a></h3>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#footnotes">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+
+    <tr valign="top">
+      <td>
+        <samp>Footnote&nbsp;references,&nbsp;like&nbsp;[5]_.</samp>
+        <br><samp>Note&nbsp;that&nbsp;footnotes&nbsp;may&nbsp;get</samp>
+        <br><samp>rearranged,&nbsp;e.g.,&nbsp;to&nbsp;the&nbsp;bottom&nbsp;of</samp>
+        <br><samp>the&nbsp;"page".</samp>
+
+        <p><samp>..&nbsp;[5]&nbsp;A&nbsp;numerical&nbsp;footnote.&nbsp;Note</samp>
+          <br><samp>&nbsp;&nbsp;&nbsp;there's&nbsp;no&nbsp;colon&nbsp;after&nbsp;the&nbsp;``]``.</samp>
+
+      <td>
+        Footnote references, like <sup><a href="#5">5</a></sup>.
+        Note that footnotes may get rearranged, e.g., to the bottom of
+        the "page".
+
+        <p><table>
+          <tr><td colspan="2"><hr>
+          <!-- <tr><td colspan="2">Footnotes: -->
+          <tr><td><a name="5"><strong>[5]</strong></a><td> A numerical footnote.
+          Note there's no colon after the <samp>]</samp>.
+          </table>
+
+    <tr valign="top">
+      <td>
+        <samp>Autonumbered&nbsp;footnotes&nbsp;are</samp>
+        <br><samp>possible,&nbsp;like&nbsp;using&nbsp;[#]_&nbsp;and&nbsp;[#]_.</samp>
+        <p><samp>..&nbsp;[#]&nbsp;This&nbsp;is&nbsp;the&nbsp;first&nbsp;one.</samp>
+          <br><samp>..&nbsp;[#]&nbsp;This&nbsp;is&nbsp;the&nbsp;second&nbsp;one.</samp>
+
+        <p><samp>They&nbsp;may&nbsp;be&nbsp;assigned&nbsp;'autonumber</samp>
+          <br><samp>labels'&nbsp;-&nbsp;for&nbsp;instance,
+        <br>[#fourth]_&nbsp;and&nbsp;[#third]_.</samp>
+
+        <p><samp>..&nbsp;[#third]&nbsp;a.k.a.&nbsp;third_</samp>
+        <p><samp>..&nbsp;[#fourth]&nbsp;a.k.a.&nbsp;fourth_</samp>
+      <td>
+        Autonumbered footnotes are possible, like using <sup><a
+        href="#auto1">1</a></sup> and <sup><a href="#auto2">2</a></sup>.
+
+        <p>They may be assigned 'autonumber labels' - for instance,
+          <sup><a href="#fourth">4</a></sup> and <sup><a
+          href="#third">3</a></sup>.
+
+        <p><table>
+          <tr><td colspan="2"><hr>
+          <!-- <tr><td colspan="2">Footnotes: -->
+          <tr><td><a name="auto1"><strong>[1]</strong></a><td> This is the first one.
+          <tr><td><a name="auto2"><strong>[2]</strong></a><td> This is the second one.
+          <tr><td><a name="third"><strong>[3]</strong></a><td> a.k.a. <a href="#third">third</a>
+          <tr><td><a name="fourth"><strong>[4]</strong></a><td> a.k.a. <a href="#fourth">fourth</a>
+        </table>
+
+    <tr valign="top">
+      <td>
+        <samp>Auto-symbol&nbsp;footnotes&nbsp;are&nbsp;also</samp>
+        <br><samp>possible,&nbsp;like&nbsp;this:&nbsp;[*]_&nbsp;and&nbsp;[*]_.</samp>
+        <p><samp>..&nbsp;[*]&nbsp;This&nbsp;is&nbsp;the&nbsp;first&nbsp;one.</samp>
+          <br><samp>..&nbsp;[*]&nbsp;This&nbsp;is&nbsp;the&nbsp;second&nbsp;one.</samp>
+
+      <td>
+        Auto-symbol footnotes are also
+        possible, like this: <sup><a href="#symbol1">*</a></sup>
+        and <sup><a href="#symbol2">&dagger;</a></sup>.
+
+        <p><table>
+          <tr><td colspan="2"><hr>
+          <!-- <tr><td colspan="2">Footnotes: -->
+          <tr><td><a name="symbol1"><strong>[*]</strong></a><td> This is the first symbol footnote
+          <tr><td><a name="symbol2"><strong>[&dagger;]</strong></a><td> This is the second one.
+        </table>
+
+    </table>
+
+    <p>The numbering of auto-numbered footnotes is determined by the
+    order of the footnotes, not of the references. For auto-numbered
+    footnote references without autonumber labels
+    ("<samp>[#]_</samp>"), the references and footnotes must be in the
+    same relative order. Similarly for auto-symbol footnotes
+    ("<samp>[*]_</samp>").
+
+    <h3><a href="#contents" name="citations" class="backref"
+        >Citations</a></h3>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#citations">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+
+    <tr valign="top">
+      <td>
+        <samp>Citation&nbsp;references,&nbsp;like&nbsp;[CIT2002]_.</samp>
+        <br><samp>Note&nbsp;that&nbsp;citations&nbsp;may&nbsp;get</samp>
+        <br><samp>rearranged,&nbsp;e.g.,&nbsp;to&nbsp;the&nbsp;bottom&nbsp;of</samp>
+        <br><samp>the&nbsp;"page".</samp>
+
+        <p><samp>..&nbsp;[CIT2002]&nbsp;A&nbsp;citation</samp>
+          <br><samp>&nbsp;&nbsp;&nbsp;(as&nbsp;often&nbsp;used&nbsp;in&nbsp;journals).</samp>
+
+        <p><samp>Citation&nbsp;labels&nbsp;contain&nbsp;alphanumerics,</samp>
+          <br><samp>underlines,&nbsp;hyphens&nbsp;and&nbsp;fullstops.</samp>
+          <br><samp>Case&nbsp;is&nbsp;not&nbsp;significant.</samp>
+
+        <p><samp>Given&nbsp;a&nbsp;citation&nbsp;like&nbsp;[this]_,&nbsp;one</samp>
+          <br><samp>can&nbsp;also&nbsp;refer&nbsp;to&nbsp;it&nbsp;like&nbsp;this_.</samp>
+
+        <p><samp>..&nbsp;[this]&nbsp;here.</samp>
+
+      <td>
+        Citation references, like <a href="#cit2002">[CIT2002]</a>.
+        Note that citations may get rearranged, e.g., to the bottom of
+        the "page".
+
+        <p>Citation labels contain alphanumerics, underlines, hyphens
+          and fullstops.  Case is not significant.
+
+        <p>Given a citation like <a href="#this">[this]</a>, one
+          can also refer to it like <a href="#this">this</a>.
+
+        <p><table>
+          <tr><td colspan="2"><hr>
+          <!-- <tr><td colspan="2">Citations: -->
+          <tr><td><a name="cit2002"><strong>[CIT2002]</strong></a><td> A citation
+          (as often used in journals).
+          <tr><td><a name="this"><strong>[this]</strong></a><td> here.
+          </table>
+
+    </table>
+
+    <h3><a href="#contents" name="hyperlink-targets" class="backref"
+        >Hyperlink Targets</a></h3>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#hyperlink-targets">details</a>)
+
+    <h4><a href="#contents" name="external-hyperlink-targets" class="backref"
+        >External Hyperlink Targets</a></h4>
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+
+    <tr valign="top">
+      <td>
+        <samp>External&nbsp;hyperlinks,&nbsp;like&nbsp;Python_.</samp>
+
+        <p><samp>..&nbsp;_Python:&nbsp;http://www.python.org/</samp>
+      <td>
+        <table width="100%">
+          <tr bgcolor="#99CCFF"><td><em>Fold-in form</em>
+          <tr><td>Indirect hyperlinks, like
+          <a href="http://www.python.org">Python</a>.
+          <tr bgcolor="#99CCFF"><td><em>Call-out form</em>
+          <tr><td>External hyperlinks, like
+          <a href="#labPython"><i>Python</i></a>.
+
+          <p><table>
+            <tr><td colspan="2"><hr>
+            <tr><td><a name="labPython"><i>Python:</i></a>
+              <td> <a href="http://www.python.org/">http://www.python.org/</a>
+          </table>
+        </table>
+    </table>
+
+    <p>"<em>Fold-in</em>" is the representation typically used in HTML
+      documents (think of the indirect hyperlink being "folded in" like
+      ingredients into a cake), and "<em>call-out</em>" is more suitable for
+      printed documents, where the link needs to be presented explicitly, for
+      example as a footnote.
+
+    <h4><a href="#contents" name="internal-hyperlink-targets" class="backref"
+        >Internal Hyperlink Targets</a></h4>
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+
+    <tr valign="top">
+      <td><samp>Internal&nbsp;crossreferences,&nbsp;like&nbsp;example_.</samp>
+
+        <p><samp>..&nbsp;_example:</samp>
+
+        <p><samp>This&nbsp;is&nbsp;an&nbsp;example&nbsp;crossreference&nbsp;target.</samp>
+      <td>
+        <table width="100%">
+          <tr bgcolor="#99CCFF"><td><em>Fold-in form</em>
+          <!-- Note that some browsers may not like an "a" tag that -->
+          <!-- does not have any content, so we could arbitrarily   -->
+          <!-- use the first word as content - *or* just trust to   -->
+          <!-- luck!                                                -->
+          <tr><td>Internal crossreferences, like <a href="#example-foldin">example</a>
+          <p><a name="example-foldin">This</a> is an example
+            crossreference target.
+          <tr><td bgcolor="#99CCFF"><em>Call-out form</em>
+          <tr><td>Internal crossreferences, like <a href="#example-callout">example</a>
+
+          <p><a name="example-callout"><i>example:</i></a>
+            <br>This is an example crossreference target.
+        </table>
+
+    </table>
+
+    <h4><a href="#contents" name="indirect-hyperlink-targets" class="backref"
+        >Indirect Hyperlink Targets</a></h4>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#indirect-hyperlink-targets">details</a>)
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+
+    <tr valign="top">
+      <td>
+        <samp>Python_&nbsp;is&nbsp;`my&nbsp;favourite
+<br>programming&nbsp;language`__.</samp>
+
+        <p><samp>..&nbsp;_Python:&nbsp;http://www.python.org/</samp>
+
+        <p><samp>__&nbsp;Python_</samp>
+
+      <td>
+        <p><a href="http://www.python.org/">Python</a> is
+        <a href="http://www.python.org/">my favourite
+        programming language</a>.
+
+    </table>
+
+    <p>The second hyperlink target (the line beginning with
+    "<samp>__</samp>") is both an indirect hyperlink target
+    (<i>indirectly</i> pointing at the Python website via the
+    "<samp>Python_</samp>" reference) and an <b>anonymous hyperlink
+    target</b>. In the text, a double-underscore suffix is used to
+    indicate an <b>anonymous hyperlink reference</b>.  In an anonymous
+    hyperlink target, the reference text is not repeated.  This is
+    useful for references with long text or throw-away references, but
+    the target should be kept close to the reference to prevent them
+    going out of sync.
+
+    <h4><a href="#contents" name="implicit-hyperlink-targets" class="backref"
+        >Implicit Hyperlink Targets</a></h4>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#implicit-hyperlink-targets">details</a>)
+
+    <p>Section titles, footnotes, and citations automatically generate
+    hyperlink targets (the title text or footnote/citation label is
+    used as the hyperlink name).
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+       <thead><tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+
+    <tr valign="top">
+      <td>
+        <samp>Titles&nbsp;are&nbsp;targets,&nbsp;too</samp>
+        <br><samp>=======================</samp>
+        <br><samp>Implict&nbsp;references,&nbsp;like&nbsp;`Titles&nbsp;are</samp>
+        <br><samp>targets,&nbsp;too`_.</samp>
+      <td>
+        <font size="+2"><strong><a name="title">Titles are targets, too</a></strong></font>
+        <p>Implict references, like <a href="#title">Titles are
+        targets, too</a>.
+    </table>
+
+    <h3><a href="#contents" name="directives" class="backref"
+        >Directives</a></h3>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#directives">details</a>)
+
+    <p>Directives are a general-purpose extension mechanism, a way of
+    adding support for new constructs without adding new syntax.  For
+    a description of all standard directives, see <a
+    href="../../ref/rst/directives.html" >reStructuredText
+    Directives</a>.
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td><samp>For&nbsp;instance:</samp>
+
+        <p><samp>..&nbsp;image::&nbsp;images/ball1.gif</samp>
+
+      <td>
+        For instance:
+        <p><img src="images/ball1.gif" alt="ball1">
+    </table>
+
+    <h3><a href="#contents" name="substitution-references-and-definitions"
+        class="backref" >Substitution References and Definitions</a></h3>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#substitution-definitions">details</a>)
+
+    <p>Substitutions are like inline directives, allowing graphics and
+    arbitrary constructs within text.
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td><samp>
+The&nbsp;|biohazard|&nbsp;symbol&nbsp;must&nbsp;be
+used&nbsp;on&nbsp;containers&nbsp;used&nbsp;to
+dispose&nbsp;of&nbsp;medical&nbsp;waste.</samp>
+
+        <p><samp>
+..&nbsp;|biohazard|&nbsp;image::&nbsp;biohazard.png</samp>
+
+      <td>
+
+        <p>The <img src="images/biohazard.png" align="bottom" alt="biohazard"> symbol
+        must be used on containers used to dispose of medical waste.
+
+    </table>
+
+    <h3><a href="#contents" name="comments" class="backref"
+        >Comments</a></h3>
+
+    <p>(<a href="../../ref/rst/restructuredtext.html#comments">details</a>)
+
+    <p>Any text which begins with an explicit markup start but doesn't
+    use the syntax of any of the constructs above, is a comment.
+
+    <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
+      <thead>
+    <tr align="left" bgcolor="#99CCFF">
+      <th width="50%">Plain text
+      <th width="50%">Typical result
+      </thead>
+      <tbody>
+    <tr valign="top">
+      <td><samp>..&nbsp;This&nbsp;text&nbsp;will&nbsp;not&nbsp;be&nbsp;shown</samp>
+        <br><samp>&nbsp;&nbsp;&nbsp;(but,&nbsp;for&nbsp;instance,&nbsp;in&nbsp;HTML&nbsp;might&nbsp;be</samp>
+        <br><samp>&nbsp;&nbsp;&nbsp;rendered&nbsp;as&nbsp;an&nbsp;HTML&nbsp;comment)</samp>
+
+      <td>&nbsp;
+          <!-- This text will not be shown         -->
+          <!-- (but, for instance in HTML might be -->
+          <!-- rendered as an HTML comment)        -->
+
+    <tr valign="top">
+      <td>
+        <samp>An&nbsp;empty&nbsp;"comment"&nbsp;does&nbsp;not</samp>
+        <br><samp>"consume"&nbsp;following&nbsp;blocks.</samp>
+        <p><samp>..</samp>
+        <p><samp>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;So&nbsp;this&nbsp;block&nbsp;is&nbsp;not&nbsp;"lost",</samp>
+          <br><samp>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;despite&nbsp;its&nbsp;indentation.</samp>
+      <td>
+        An empty "comment" does not
+        "consume" following blocks.
+        <blockquote>
+          So this block is not "lost",
+          despite its indentation.
+        </blockquote>
+    </table>
+
+    <h2><a href="#contents" name="getting-help" class="backref"
+        >Getting Help</a></h2>
+
+    <p>Users who have questions or need assistance with Docutils or
+    reStructuredText should <a
+    href="mailto:docutils-users@lists.sourceforge.net" >post a
+    message</a> to the <a
+    href="http://lists.sourceforge.net/lists/listinfo/docutils-users"
+    >Docutils-Users mailing list</a>.  The <a
+    href="http://docutils.sourceforge.net/" >Docutils project web
+    site</a> has more information.
+
+    <p><hr>
+    <address>
+      <p>Authors:
+    <a href="http://www.tibsnjoan.co.uk/">Tibs</a>
+    (<a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>)
+    and David Goodger
+    (<a href="mailto:goodger@python.org">goodger@python.org</a>)
+    </address>
+    <!-- Created: Fri Aug 03 09:11:57 GMT Daylight Time 2001 -->
+  </body>
+</html>
diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt
new file mode 100644
index 000000000..bf6b21275
--- /dev/null
+++ b/docs/user/rst/quickstart.txt
@@ -0,0 +1,390 @@
+A ReStructuredText Primer
+=========================
+
+:Author: Richard Jones
+:Version: $Revision$
+: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
+
+
+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**``".
+
+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 * asterisk is handled just fine.  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
+
+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`_.  The `Docutils project web site`_ has more
+information.
+
+.. [#] 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
+.. _post a message: mailto:docutils-users@lists.sourceforge.net
+.. _Docutils-Users mailing list:
+   http://lists.sourceforge.net/lists/listinfo/docutils-users
+.. _Docutils project web site: http://docutils.sourceforge.net/
diff --git a/docs/user/tools.txt b/docs/user/tools.txt
new file mode 100644
index 000000000..ab31e0917
--- /dev/null
+++ b/docs/user/tools.txt
@@ -0,0 +1,316 @@
+==========================
+ Docutils Front-End Tools
+==========================
+
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:Revision: $Revision$
+:Date: $Date$
+: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 pep2html.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 as well.
+
+
+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`_.  The `Docutils project web site`_ has more
+information.
+
+.. _post a message: mailto:docutils-users@lists.sourceforge.net
+.. _Docutils-Users mailing list:
+   http://lists.sourceforge.net/lists/listinfo/docutils-users
+.. _Docutils project web site: http://docutils.sourceforge.net/
+
+
+The 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 stylesheets, templates, and 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
+
+The ``rst2html.py`` front end reads standalone reStructuredText source
+files and produces HTML 4 (XHTML 1) output compatible with modern
+browsers.  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 projects, add some options::
+
+    rst2html.py -stg test.txt test.html
+
+
+Stylesheets
+```````````
+
+``rst2html.py`` inserts into the generated HTML a link to a cascading
+stylesheet, defaulting to "``default.css``" (override with a
+"``--stylesheet``" or "``--stylesheet-path``" command-line option or
+with configuration file settings).  The
+"``tools/stylesheets/default.css``" stylesheet is provided for basic
+use.  To experiment with styles, rather than editing the default
+stylesheet (which will be updated as the project evolves), it is
+recommended to use an "``@import``" statement to create a "wrapper"
+stylesheet.  For example, a "``my.css``" stylesheet could contain the
+following::
+
+    @import url(default.css);
+
+    h1, h2, h3, h4, h5, h6, p.topic-title {
+      font-family: sans-serif }
+
+Generate HTML with the following command::
+
+    rst2html.py -stg --stylesheet my.css test.txt test.html
+
+When viewed in a browser, the new "wrapper" stylesheet will change the
+typeface family of titles to "sans serif", typically Helvetica or
+Arial.  Other styles will not be affected.  Styles in wrapper
+stylesheets override styles in imported stylesheets, enabling
+incremental experimentation.
+
+
+pep.py
+------
+
+:Reader: PEP
+:Parser: reStructuredText
+:Writer: PEP/HTML
+
+``pep.py`` reads a new-style PEP (marked up with reStructuredText) and
+produces HTML.  It requires a template file and a stylesheet.  By
+default, it makes use of a "``pep-html-template``" file and a
+"``default.css``" stylesheet in the current directory, but these can
+be overridden by command-line options or configuration files.  The
+"``tools/stylesheets/pep.css``" stylesheet is intended specifically
+for PEP use.
+
+The "``docutils.conf``" `configuration file`_ in the "``tools``"
+directory of Docutils contains a default setup for use in processing
+the PEP files (``docs/peps/pep-*.txt``) into HTML.  It specifies a
+default template (``tools/pep-html-template``) and a default
+stylesheet (``tools/stylesheets/pep.css``).  See Stylesheets_ above
+for more information.
+
+``pep.py`` can be run from the ``tools`` directory or from the
+``docs/peps/`` directory, by adjusting the settings.  These two sets
+of commands are equivalent::
+
+    cd <path-to-docutils>/tools
+    # This will pick up the "docutils.conf" file automatically:
+    pep.py ../docs/peps/pep-0287.txt ../docs/peps/pep-0287.html
+
+    cd <path-to-docutils>/docs/peps
+    # Must tell the tool where to find the config file:
+    ../../tools/pep.py --config ../../tools/docutils.conf \
+        pep-0287.txt pep-0287.html
+
+
+pep2html.py
+-----------
+
+:Reader: PEP
+:Parser: reStructuredText
+:Writer: PEP/HTML
+
+``pep2html.py`` is a modified version of the original script by
+Fredrik Lundh, with support for Docutils added.  It reads the
+beginning of a PEP text file to determine the format (old-style
+indented or new-style reStructuredText) and processes accordingly.
+Since it does not use the Docutils front end mechanism (the common
+command-line options are not supported), it can only be configured
+using `configuration files`_.  The template and stylesheet
+requirements of ``pep2html.py`` are the same as those of `pep.py`_
+above.
+
+Arguments to ``pep2html.py`` may be a list of PEP numbers or .txt
+files.  If no arguments are given, all files of the form
+"``pep-*.txt``" are processed.
+
+
+rst2latex.py
+------------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: LaTeX2e
+
+The ``rst2latex.py`` front end reads standalone reStructuredText
+source files and produces LaTeX2e 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 typeset document.
+
+Some limitations and difference apply:
+
+- GIF, JPG and PNG images are not handled, when processed with
+  ``latex``; use ``pdflatex`` instead.
+- Only the Latin-1 output encoding has been tested up to now (Latin-1
+  has been made the default output encoding for LaTeX).
+- The optional stylesheet file allows the inclusion of special packages 
+  or overwriting default settings for LaTeX.
+- Not all constructs are possible, see `Generating LaTeX with Docutils`_.
+
+
+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.
+
+
+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: