Release 0.4: tagging released revisiondocutils-0.4

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

32 files changed, 7264 insertions, 0 deletions

diff --git a/docs/user/Makefile.docutils-update b/docs/user/Makefile.docutils-update
new file mode 100644
index 000000000..89097b5ff
--- /dev/null
+++ b/docs/user/Makefile.docutils-update
@@ -0,0 +1,6 @@
+slide-shows.s5.html: slide-shows.txt
+	rst2s5.py slide-shows.txt slide-shows.s5.html \
+		--config ../../tools/docutils.conf \
+		--overwrite-theme-files \
+		--link-stylesheet \
+		--no-generator --no-datestamp --no-source-link
diff --git a/docs/user/config.txt b/docs/user/config.txt
new file mode 100644
index 000000000..0413dd5be
--- /dev/null
+++ b/docs/user/config.txt
@@ -0,0 +1,1041 @@
+==============================
+ 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 where Docutils will write a list of files that the
+    input and output depend 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: ``--section-numbering``,
+    ``--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).
+
+_`strip_comments`
+    Enable the removal of comment elements from the document tree.
+
+    Default: disabled (None).  Options: ``--strip-comment``,
+    ``--leave-comments``.
+
+_`title`
+    The document title as metadata, which does not become part of the
+    document body.  It overrides a document-supplied title.  For
+    example, in HTML output the metadata document title appears in the
+    title bar of the browser window.
+
+    Default: none.  Option: ``--title``.
+
+_`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 reference
+    URI, the "@" will be replaced by %-escapes (as of RFC 1738).  In
+    the visible text (link text) of an email reference, the "@" and
+    all periods (".") will be surrounded by ``<span>`` tags.
+    Furthermore, HTML entities are used to encode these characters in
+    order to further complicate decoding the email address.  For
+    example, "abc@example.org" will be output as::
+
+        <a class="reference" href="mailto:abc&#37;&#52;&#48;example&#46;org">
+        abc<span>&#64;</span>example<span>&#46;</span>org</a>
+
+    .. Note:: While cloaking email addresses will have little to no
+       impact on the rendering and usability of email links in most
+       browsers, some browsers (e.g. the ``links`` browser) may decode
+       cloaked email addresses incorrectly.
+
+    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 all "simple" (i.e., items
+    each contain one paragraph and/or one "simple" sublist only).  The
+    behaviour can be specified directly via "class" attributes (values
+    "compact" and "open") in the document.
+
+    Default: enabled (1).  Options: ``--compact-lists,
+    --no-compact-lists``.
+
+_`compact_field_lists`
+    Remove extra vertical whitespace between items of field lists that
+    are "simple" (i.e., all field bodies each contain at most one
+    paragraph).  The behaviour can be specified directly via "class"
+    attributes (values "compact" and "open") in the document.
+
+    Default: enabled (1).  Options: ``--compact-field-lists,
+    --no-compact-field-lists``.
+
+_`embed_stylesheet`
+    Embed the stylesheet in the output HTML file.  The stylesheet file
+    must be accessible during processing.
+
+    Default: enabled.  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``.
+
+_`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 [html4css1 writer]:
+
+stylesheet
+    CSS stylesheet URL, used verbatim.  Overrides the
+    "stylesheet_path" setting [#override]_.  Pass an empty string to
+    deactivate stylesheet inclusion.
+
+    Default: None.  Options: ``--stylesheet``.
+
+    (Setting also defined for the `LaTeX Writer`__.)
+
+    __ `stylesheet [latex2e writer]`_
+
+.. _stylesheet_path [html4css1 writer]:
+
+stylesheet_path
+    Path to CSS stylesheet [#pwd]_.  Overrides the "stylesheet" URL
+    setting [#override]_.  Path is adjusted relative to the output
+    HTML file.  Also defined for the `LaTeX Writer`__.
+
+    Default: "html4css1.css" in the docutils/writers/html4css1/
+    directory (installed automatically; for the exact machine-specific
+    path, use the ``--help`` option).  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 of configuration files is processed
+before the "[pep_html writer]" section.
+
+The PEP/HTML Writer's default for the ``stylesheet_path`` setting
+differs from that of the standard HTML Writer:
+``docutils/writers/pep_html/pep.css`` in the installation directory is
+used.  For the exact machine-specific path, use the ``--help`` option.
+
+_`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``.
+
+
+[s5_html writer]
+.................
+
+The S5/HTML Writer derives from the standard HTML Writer, and shares
+all settings defined in the `[html4css1 writer]`_ section.  The
+"[html4css1 writer]" section of configuration files is processed
+before the "[s5_html writer]" section.
+
+The S5/HTML Writer's default for the ``compact_lists`` setting differs
+from that of the standard HTML Writer: the default here is to disable
+compact lists.
+
+_`current_slide`
+
+    Enable or disable the current slide indicator ("1/15").
+
+    Default: disabled (None).  Options: ``--current-slide``,
+    ``--no-current-slide``.
+
+_`overwrite_theme_files`
+    Allow or prevent the overwriting of existing theme files in the
+    ``ui/<theme>`` directory.  This has no effect if "theme_url_" is
+    used.
+
+    Default: keep existing theme files (None).  Options:
+    ``--keep-theme-files``, ``--overwrite-theme-files``.
+
+_`theme`
+    Name of an installed S5 theme, to be copied into a ``ui/<theme>``
+    subdirectory, beside the destination file (output HTML).  Note
+    that existing theme files will not be overwritten; the existing
+    theme directory you must be deleted manually.  Overrides the
+    "theme_url_" setting [#override]_.
+
+    Default: "default".  Option: ``--theme``.
+
+_`theme_url`
+    The URL of an S5 theme directory.  The destination file (output
+    HTML) will link to this theme; nothing will be copied.  Overrides
+    the "theme_" setting [#override]_.
+
+    Default: None.  Option: ``--theme-url``.
+
+
+[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
+    programmatic 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://www.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/emacs.txt b/docs/user/emacs.txt
new file mode 100644
index 000000000..49687f599
--- /dev/null
+++ b/docs/user/emacs.txt
@@ -0,0 +1,497 @@
+.. -*- coding: utf-8 -*-
+
+========================================
+   Emacs Support for reStructuredText
+========================================
+
+:Author: Martin Blais <blais@furius.ca>
+:Date: $Date$
+:Abstract:
+
+    High-level description of the existing emacs support for editing
+    reStructuredText text documents.  Suggested setup code and usage
+    instructions are provided.
+
+.. contents::
+
+
+Introduction
+============
+
+reStructuredText_ is a series of conventions that allows a
+toolset--docutils--to extract generic document structure from simple
+text files.  For people who use Emacs_, there is a package that adds
+some support for the conventions that reStructuredText_ specifies:
+``rst.el``.
+
+This document describes the most important features that it provides,
+how to setup your emacs to use them and how to invoke them.
+
+
+Basic Setup
+===========
+
+The emacs support is completely provided by the ``rst.el`` emacs
+package.  In order to use these features, you need to put the file in
+your emacs load-path, and to load it with::
+
+  (require 'rst)  ;; or (load "rst")
+
+Additional configuration variables can be customized and can be found
+by browsing the source code for ``rst.el``.
+
+Then you will want to bind keys to the most common commands it
+provides.  A standard text-mode hook function is maintained and
+provided by the package for this use, set it up like this::
+
+  (add-hook 'text-mode-hook 'rst-text-mode-bindings)
+
+A prefix map is defined for all the ``rst.el`` commands.  By default,
+it is bound to the mode-specific-map and ``p``, e.g. ``C-c p ...``.
+
+
+Section Decoration Adjustment
+=============================
+
+The rst package does not completely parse all the reStructuredText_
+constructs, but it contains the ability to recognize the section
+decorations and to build the hierarchy of the document.  What we call
+section decorations or adornments are the underlines or under- and
+overlines used to mark a section title.
+
+There is a function that helps a great deal to maintain these
+decorations: ``rst-adjust`` (bound on ``C-c p a``, ``C-c p =`` or
+``C-=`` by default).  This function is a Swiss army knife that can be
+invoked repeatedly and whose behaviour depends on context:
+
+#. If there is an incomplete underline, e.g.::
+
+      My Section Title
+      ^^
+
+   Invocation will complete the section title.  You can simply enter a
+   few characters of the title and invoke the function to complete it.
+   It can also be used to adjust the length of the existing decoration
+   when you need to edit the title.
+
+#. If there is no section decoration, a decoration one level under the
+   last encountered section level is added;
+
+#. If there is already a section decoration, it is promoted to the
+   next level.  You can invoke it like this repeatedly to cycle the
+   title through the hierarchy of existing decorations.
+
+Invoking the function with a negative prefix argument, e.g. ``C--
+C-=``, will effectively reverse the direction of decoration cycling.
+To alternate between underline-only and over-and-under styles, you can
+use a regular prefix argument, e.g. ``C-u C-=``.  See the
+documentation of ``rst-adjust`` for more description of the prefix
+arguments to alter the behaviour of the function.
+
+
+Promoting and Demoting Many Sections
+------------------------------------
+
+When you are re-organizing the structure of a document, it can be
+useful to change the level of a number of section titles.  The same
+key binding can be used to do that: if the region is active when the
+binding is invoked, all the section titles that are within the region
+are promoted accordingly (or demoted, with negative prefix arg).
+
+
+Customizations
+--------------
+
+You can set the variable ``rst-preferred-decorations`` to a list of
+the decorations that you like to use for documents.  Everyone has
+their preference.  ``rst-default-indent`` can be set to the number of
+indent spaces preferred for the over-and-under decoration style.
+
+
+Viewing the Hierarchy of Section Decorations
+============================================
+
+You can visualize the hierarchy of the section decorations in the
+current buffer by invoking ``rst-display-decorations-hierarchy``,
+bound on ``C-c p h``.  A temporary buffer will appear with fake
+section titles rendered in the style of the current document.  This
+can be useful when editing other people's documents to find out which
+section decorations correspond to which levels.
+
+
+Table of Contents
+=================
+
+When you are editing long documents, it can be a bit difficult to
+orient yourself in the structure of your text.  To that effect, a
+function is provided that quickly parses the document and presents a
+hierarchically indented table of contents of the document in a
+temporary buffer, in which you can navigate and press ``Return`` to go
+to a specific section.
+
+Invoke this function (``rst-toc``) with ``C-c p t``.  It should
+present a temporary buffer that looks something like this::
+
+  Table of Contents: 
+  Debugging Meta-Techniques
+    Introduction
+    Debugging Solution Patterns
+      Recognize That a Bug Exists
+      Subdivide and Isolate
+      Identify and Verify Assumptions
+      Use a Tool for Introspection
+      Change one thing at a time
+      Learn about the System
+    Understanding a bug
+    The Basic Steps in Debugging
+    Attitude
+      Bad Feelings
+      Good Feelings
+    References
+
+When you select a section title, the temporary buffer disappears and
+you are left with the cursor positioned at the chosen section.
+
+
+Inserting a Table of Contents
+-----------------------------
+
+Oftentimes in long text documents that are meant to be read directly,
+a Table of Contents is inserted at the beginning of the text.  This is
+the case for most internet FAQs, for example.  In reStructuredText_
+documents, since the table of contents is automatically generated by
+the parser with the ``.. contents::`` directive, people generally have
+not been adding a text table of contents to their source documents,
+and partly because it is too much trouble to edit and maintain.
+
+The emacs support for reStructuredText_ provides a function to insert
+such a table of contents in your document.  Since it is not meant to
+be part of the document text, you should place such a table of
+contents within a comment, so that it is ignored by the parser.  This
+is the favoured usage::
+
+  .. contents::
+  .. 
+      1  Introduction
+      2  Debugging Solution Patterns
+        2.1  Recognize That a Bug Exists
+        2.2  Subdivide and Isolate
+        2.3  Identify and Verify Assumptions
+        2.4  Use a Tool for Introspection
+        2.5  Change one thing at a time
+        2.6  Learn about the System
+      3  Understanding a bug
+      4  The Basic Steps in Debugging
+      5  Attitude
+        5.1  Bad Feelings
+        5.2  Good Feelings
+      6  References
+
+Just place the cursor at the top-left corner where you want to insert
+the TOC and invoke the function with ``C-c p i``.  The table of
+contents will display all the section titles that are under the
+location where the insertion occurs.  This way you can insert local
+table of contents by placing them in the appropriate location.
+
+If you have deep nesting of sections, you can use a numeric prefix
+argument to limit the depth of rendering of the TOC.
+
+You can also customize the look of the TOC by setting the values of
+the following variables:: ``rst-toc-indent``,
+``rst-toc-insert-style``, ``rst-toc-insert-max-level``.
+
+
+Maintaining the Table of Contents Up-to-date
+--------------------------------------------
+
+One issue is that you will probably want to maintain the inserted
+table of contents up-to-date.  There is a function that will
+automatically look for the inserted TOC (``rst-toc-insert-update``)
+and it can be added to a hook on the section decoration adjustment
+function, so that every time you adjust a section title, the TOC is
+updated. Add this functionality with the following emacs
+configuration::
+
+  (add-hook 'rst-adjust-hook 'rst-toc-insert-update)
+
+You can invoke the update on the current buffer with ``C-c p u``.
+
+
+Navigating Between the Section Titles
+=====================================
+
+You can move the cursor between the different sections by using the
+``rst-backward-section`` and ``rst-forward-section`` functions, by
+default bound to the ``C-c p p`` and ``C-c p n`` keys (also ``C-c
+C-p`` and ``C-c C-n``).
+
+
+Shifting Bullet List Levels
+===========================
+
+Due to the nature of reStructuredText_, bullet lists are always
+indented by two characters (unless they are part of a blockquote),
+e.g. ::
+
+   - Fruits
+
+     - Bananas
+     - Apples
+     - Oranges
+
+   - Veggies
+
+     - Zucchini
+     - Chick Peas
+
+To this effect, when re-organizing bullet lists, it can be useful to
+shift regions of text by indents of two characters.  You can use the
+``C-c C-r`` and ``C-c C-l`` to shift the current region.  These
+bindings are similar to the ones provided by python-mode for editing
+python code and behave similarly.
+
+
+Major Mode for Editing reStructuredText Documents
+=================================================
+
+There is a major mode available for editing and syntax highlighting
+reStructuredText_ constructs.  This mode was written by Stefan Merten
+[#]_.  It mostly provides lazy syntax coloring for many of the
+constructs that reStructuredText_ prescribes.
+
+To enable this mode, type ``M-x rst-mode`` or you can set up an
+``auto-mode-alist`` to automatically turn it on whenever you visit
+reStructuredText_ documents::
+
+   (add-to-list 'auto-mode-alist '("\\.rst$" . rst-mode) )
+
+If have local variables enabled (see ``enable-local-variables`` in the
+Emacs manual), you can also add the following at the top of your
+documents to trigger rst-mode::
+
+   .. -*- mode: rst -*-
+
+Or add this at the end of your documents::
+
+   ..
+      Local Variables:
+      mode: rst
+      End:
+
+By default, the font-lock colouring is performed lazily.  If you don't
+like this, you can turn this off by setting the value of
+``rst-mode-lazy``.  You can also change the various colours (see the
+source file for the whole list of customizable faces).
+
+.. [#] This mode used to be provided by the file ``rst-mode.el`` and
+   has now been integrated with the rest of the emacs code.
+
+
+Converting Documents from Emacs
+===============================
+
+At the moment there is minimal support for calling the conversion
+tools from within Emacs.  You can add a key binding like this to
+invoke it::
+
+  (local-set-key [(control c)(?9)] 'rst-compile)
+
+This function basically creates a compilation command with the correct
+output name for the current buffer and then invokes Emacs' compile
+function.  It also looks for the presence of a ``docutils.conf``
+configuration file in the parent directories and adds it to the
+cmdline options.  You can customize which tool is used to perform the
+conversion and some standard options to always be added as well.
+
+Invocation uses the toolset indicated by
+``rst-compile-primary-toolset`` (default is ``'html``).  Invocation
+with a prefix argument uses ``rst-compile-secondary-toolset`` (default
+is ``'latex``).
+
+.. note:: 
+
+   In general it is preferred to use a Makefile to automate the
+   conversion of many documents or a hierarchy of documents.  The
+   functionality presented above is meant to be convenient for use on
+   single files.
+
+
+Other / External Useful Emacs Settings
+======================================
+
+This section covers general emacs text-mode settings that are useful
+in the context of reStructuredText_ conventions.  These are not
+provided by ``rst.el`` but you may find them useful specifically for
+reStructuredText_ documents.
+
+
+Settings for Filling Lists
+--------------------------
+
+One problem with the default text-mode settings is that *filling* long
+lines in bullet and enumerated lists that do not have an empty line
+between them merges them together, e.g.::
+
+     - Bananas;
+     - One Apple a day keeps the doctor away, and eating more keeps the pirates at bay;
+     - Oranges;
+
+Becomes::
+
+     - Bananas; One Apple a day keeps the doctor away, and eating more
+     - keeps the pirates at bay; Oranges;
+
+This is usually not what you want. What you want is this::
+
+     - Bananas;
+     - One Apple a day keeps the doctor away, and eating more keeps
+       the pirates at bay;
+     - Oranges;
+
+The problem is that emacs does not recognize the various consecutive
+items as forming paragraph boundaries.  You can fix this easily by
+changing the global value of the parapraph boundary detection to
+recognize such lists, using the ``rst-set-paragraph-separation``
+function::
+
+   (add-hook 'text-mode-hook 'rst-set-paragraph-separation)
+
+
+``text-mode`` Settings
+----------------------
+
+Consult the Emacs manual for more text-mode customizations.  In
+particular, you may be interested in setting the following variables,
+functions and modes that pertain somewhat to text-mode:
+
+- indent-tabs-mode
+- colon-double-space
+- auto-fill-mode
+- auto-mode-alist
+- fill-region
+
+
+Editing Tables: Emacs table mode
+--------------------------------
+
+You may want to check out `Emacs table mode`_ to create an edit
+tables, it allows creating ascii tables compatible with
+reStructuredText_.
+
+.. _Emacs table mode: http://table.sourceforge.net/
+
+
+Character Processing
+--------------------
+
+Since reStructuredText punts on the issue of character processing,
+here are some useful resources for Emacs users in the Unicode world:
+
+* `xmlunicode.el and unichars.el from Norman Walsh
+  <http://nwalsh.com/emacs/xmlchars/index.html>`__
+
+* `An essay by Tim Bray, with example code
+  <http://www.tbray.org/ongoing/When/200x/2003/09/27/UniEmacs>`__
+
+* For Emacs users on Mac OS X, here are some useful useful additions
+  to your .emacs file.
+
+  - To get direct keyboard input of non-ASCII characters (like
+    "option-e e" resulting in "é" [eacute]), first enable the option
+    key by setting the command key as your meta key::
+
+        (setq mac-command-key-is-meta t) ;; nil for option key
+
+    Next, use one of these lines::
+
+        (set-keyboard-coding-system 'mac-roman)
+        (setq mac-keyboard-text-encoding kTextEncodingISOLatin1)
+
+    I prefer the first line, because it enables non-Latin-1 characters
+    as well (em-dash, curly quotes, etc.).
+
+  - To enable the display of all characters in the Mac-Roman charset,
+    first create a fontset listing the fonts to use for each range of
+    characters using charsets that Emacs understands::
+
+      (create-fontset-from-fontset-spec
+       "-apple-monaco-medium-r-normal--10-*-*-*-*-*-fontset-monaco,
+        ascii:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman,
+        latin-iso8859-1:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman,
+        mule-unicode-0100-24ff:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman")
+
+    Latin-1 doesn't cover characters like em-dash and curly quotes, so
+    "mule-unicode-0100-24ff" is needed.
+
+    Next, use that fontset::
+
+        (set-frame-font "fontset-monaco")
+
+  - To enable cooperation between the system clipboard and the Emacs
+    kill ring, add this line::
+
+        (set-clipboard-coding-system 'mac-roman)
+
+  Other useful resources are in `Andrew Choi's Emacs 21 for Mac OS X
+  FAQ <http://members.shaw.ca/akochoi-emacs/stories/faq.html>`__.
+
+No matter what platform (or editor) you're using, I recommend the
+ProFont__ programmer's font.  It's monospaced, small but readable,
+similar characters are visually distinctive (like "I1l|", "0O", "ao",
+and ".,:;"), and free.
+
+__ http://www.tobias-jung.de/seekingprofont/
+
+
+Credits
+=======
+
+- The automatic section adjustment and table of contents features were
+  written by Martin Blais;
+- ``rst-mode`` and its syntax highlighting was implemented by Stefan
+  Merten;
+- Various other functions were implemented by David Goodger.
+
+
+Obsolete Files
+==============
+
+On 2005-10-30, ``restructuredtext.el``, ``rst-html.el`` and
+``rst-mode.el`` were merged to form the new ``rst.el``.  You can
+consider the old files obsolete and remove them.
+
+
+Future Work
+===========
+
+Here are some features and ideas that will be worked on in the future,
+in those frenzied mornings of excitement over the virtues of the
+one-true-way kitchen sink of editors:
+
+- It would be nice to differentiate between text files using
+  reStructuredText_ and other general text files.  If we had a
+  function to automatically guess whether a .txt file is following the
+  reStructuredText_ conventions, we could trigger rst-mode without
+  having to hard-code this in every text file, nor forcing the user to
+  add a local mode variable at the top of the file.
+
+  We could perform this guessing by searching for a valid decoration
+  at the top of the document or searching for reStructuredText_
+  directives further on.
+
+- The suggested decorations when adjusting should not have to cycle
+  below one below the last section decoration level preceding the
+  cursor.  We need to fix that.
+
+
+.. _Emacs: http://www.gnu.org/software/emacs/emacs.html
+.. _reStructuredText: http://docutils.sf.net/rst.html
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:
diff --git a/docs/user/images/big-black.png b/docs/user/images/big-black.png
new file mode 100644
index 000000000..869a0cf9f
--- /dev/null
+++ b/docs/user/images/big-black.png
diff --git a/docs/user/images/big-white.png b/docs/user/images/big-white.png
new file mode 100644
index 000000000..1ce6d7d7d
--- /dev/null
+++ b/docs/user/images/big-white.png
diff --git a/docs/user/images/default.png b/docs/user/images/default.png
new file mode 100644
index 000000000..509eeddad
--- /dev/null
+++ b/docs/user/images/default.png
diff --git a/docs/user/images/happy_monkey.png b/docs/user/images/happy_monkey.png
new file mode 100644
index 000000000..2164c06dd
--- /dev/null
+++ b/docs/user/images/happy_monkey.png
diff --git a/docs/user/images/medium-black.png b/docs/user/images/medium-black.png
new file mode 100644
index 000000000..f851e679e
--- /dev/null
+++ b/docs/user/images/medium-black.png
diff --git a/docs/user/images/medium-white.png b/docs/user/images/medium-white.png
new file mode 100644
index 000000000..e5a465a56
--- /dev/null
+++ b/docs/user/images/medium-white.png
diff --git a/docs/user/images/rsp-all.png b/docs/user/images/rsp-all.png
new file mode 100644
index 000000000..3e5f5ede3
--- /dev/null
+++ b/docs/user/images/rsp-all.png
diff --git a/docs/user/images/rsp-breaks.png b/docs/user/images/rsp-breaks.png
new file mode 100644
index 000000000..f2a31b098
--- /dev/null
+++ b/docs/user/images/rsp-breaks.png
diff --git a/docs/user/images/rsp-covers.png b/docs/user/images/rsp-covers.png
new file mode 100644
index 000000000..597c2c2a8
--- /dev/null
+++ b/docs/user/images/rsp-covers.png
diff --git a/docs/user/images/rsp-cuts.png b/docs/user/images/rsp-cuts.png
new file mode 100644
index 000000000..aa46b3876
--- /dev/null
+++ b/docs/user/images/rsp-cuts.png
diff --git a/docs/user/images/rsp-empty.png b/docs/user/images/rsp-empty.png
new file mode 100644
index 000000000..f6b93c38b
--- /dev/null
+++ b/docs/user/images/rsp-empty.png
diff --git a/docs/user/images/rsp-objects.png b/docs/user/images/rsp-objects.png
new file mode 100644
index 000000000..43ce276f1
--- /dev/null
+++ b/docs/user/images/rsp-objects.png
diff --git a/docs/user/images/rsp.svg b/docs/user/images/rsp.svg
new file mode 100644
index 000000000..03445d3bc
--- /dev/null
+++ b/docs/user/images/rsp.svg
@@ -0,0 +1,636 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://web.resource.org/cc/"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="1224.0000pt"
+   height="792.00000pt"
+   id="svg16130"
+   sodipodi:version="0.32"
+   inkscape:version="0.42"
+   sodipodi:docbase="/Users/david/projects/docutils/s5-branch/docs/user/images"
+   sodipodi:docname="rsp.svg"
+   inkscape:export-filename="/Users/david/projects/docutils/s5-branch/docs/user/images/rsp-empty.png"
+   inkscape:export-xdpi="90.000000"
+   inkscape:export-ydpi="90.000000">
+  <defs
+     id="defs16132">
+    <radialGradient
+       cx="64.960804"
+       cy="86.732626"
+       fx="64.394720"
+       fy="89.843742"
+       id="radialGradient1157"
+       r="4.6795605"
+       xlink:href="#linearGradient1125"
+       gradientTransform="scale(1.232968,0.811051)"
+       gradientUnits="userSpaceOnUse" />
+    <linearGradient
+       id="linearGradient1147"
+       x1="30.807715"
+       x2="9.1659926"
+       xlink:href="#linearGradient1129"
+       y1="134.41771"
+       y2="128.61883"
+       gradientTransform="scale(2.035443,0.491293)"
+       gradientUnits="userSpaceOnUse" />
+    <linearGradient
+       id="linearGradient1146"
+       x1="23.109005"
+       x2="23.655650"
+       xlink:href="#linearGradient1129"
+       y1="86.372661"
+       y2="75.530011"
+       gradientTransform="scale(1.564854,0.639037)"
+       gradientUnits="userSpaceOnUse" />
+    <linearGradient
+       id="linearGradient1150"
+       x1="7.1055503"
+       x2="37.417715"
+       xlink:href="#linearGradient1152"
+       y1="148.97907"
+       y2="149.31015"
+       gradientTransform="scale(1.328405,0.752782)"
+       gradientUnits="userSpaceOnUse" />
+    <linearGradient
+       id="linearGradient1152">
+      <stop
+         id="stop1153"
+         offset="0.00000000"
+         style="stop-color:#ffffff;stop-opacity:0.00000000;" />
+      <stop
+         id="stop1155"
+         offset="0.44302326"
+         style="stop-color:#ffffff;stop-opacity:0.46274510;" />
+      <stop
+         id="stop1154"
+         offset="1.0000000"
+         style="stop-color:#ffffff;stop-opacity:0.00000000;" />
+    </linearGradient>
+    <linearGradient
+       id="linearGradient1151"
+       x1="29.180973"
+       x2="12.077421"
+       xlink:href="#linearGradient1152"
+       y1="176.88234"
+       y2="176.49016"
+       gradientTransform="scale(1.503932,0.664924)"
+       gradientUnits="userSpaceOnUse" />
+    <linearGradient
+       id="linearGradient1135"
+       x1="5.6004575"
+       x2="57.337623"
+       xlink:href="#linearGradient1136"
+       y1="125.70108"
+       y2="125.70108"
+       gradientTransform="scale(1.240748,0.805966)"
+       gradientUnits="userSpaceOnUse" />
+    <linearGradient
+       id="linearGradient1129">
+      <stop
+         id="stop1130"
+         offset="0.00000000"
+         style="stop-color:#ffffff;stop-opacity:0.00000000;" />
+      <stop
+         id="stop1131"
+         offset="1.0000000"
+         style="stop-color:#ffffff;stop-opacity:0.64583331;" />
+    </linearGradient>
+    <linearGradient
+       id="linearGradient1128"
+       x1="76.620649"
+       x2="89.927438"
+       xlink:href="#linearGradient1129"
+       y1="79.202017"
+       y2="132.51965"
+       gradientTransform="scale(1.342210,0.745040)"
+       gradientUnits="userSpaceOnUse" />
+    <linearGradient
+       id="linearGradient1133"
+       x1="95.959445"
+       x2="95.959445"
+       xlink:href="#linearGradient1125"
+       y1="96.280971"
+       y2="6.0312801"
+       gradientTransform="scale(1.356086,0.737416)"
+       gradientUnits="userSpaceOnUse" />
+    <linearGradient
+       id="linearGradient1136">
+      <stop
+         id="stop1137"
+         offset="0.00000000"
+         style="stop-color:#000000;stop-opacity:1.0000000;" />
+      <stop
+         id="stop1138"
+         offset="1.0000000"
+         style="stop-color:#454545;stop-opacity:1.0000000;" />
+    </linearGradient>
+    <linearGradient
+       id="linearGradient1145"
+       x1="26.716417"
+       x2="57.535761"
+       xlink:href="#linearGradient1136"
+       y1="72.512797"
+       y2="104.12337"
+       gradientTransform="scale(1.435519,0.696612)"
+       gradientUnits="userSpaceOnUse" />
+    <linearGradient
+       id="linearGradient1125">
+      <stop
+         id="stop1126"
+         offset="0.00000000"
+         style="stop-color:#979797;stop-opacity:1.0000000;" />
+      <stop
+         id="stop1163"
+         offset="0.35050300"
+         style="stop-color:#fafafa;stop-opacity:1.0000000;" />
+      <stop
+         id="stop1164"
+         offset="0.36050299"
+         style="stop-color:#9f9f9f;stop-opacity:1.0000000;" />
+      <stop
+         id="stop1127"
+         offset="1.0000000"
+         style="stop-color:#ffffff;stop-opacity:1.0000000;" />
+    </linearGradient>
+    <linearGradient
+       id="linearGradient1134"
+       x1="66.560545"
+       x2="26.091148"
+       xlink:href="#linearGradient1125"
+       y1="135.98955"
+       y2="85.436682"
+       gradientTransform="scale(1.892867,0.528299)"
+       gradientUnits="userSpaceOnUse" />
+    <linearGradient
+       id="linearGradient1243">
+      <stop
+         id="stop1244"
+         offset="0.00000000"
+         style="stop-color:#000000;stop-opacity:0.19791667;" />
+      <stop
+         id="stop1245"
+         offset="1.0000000"
+         style="stop-color:#000000;stop-opacity:0.00000000;" />
+    </linearGradient>
+    <linearGradient
+       id="linearGradient1149"
+       x1="508.22840"
+       x2="505.28565"
+       xlink:href="#linearGradient1243"
+       y1="556.37391"
+       y2="107.87502"
+       gradientTransform="scale(1.347706,0.742001)"
+       gradientUnits="userSpaceOnUse" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient1243"
+       id="linearGradient16217"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="scale(1.347706,0.742001)"
+       x1="508.22840"
+       y1="556.37391"
+       x2="505.28565"
+       y2="107.87502" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient1243"
+       id="linearGradient16219"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="scale(1.347706,0.742001)"
+       x1="508.22840"
+       y1="556.37391"
+       x2="505.28565"
+       y2="107.87502" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient1243"
+       id="linearGradient16221"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="scale(1.347706,0.742001)"
+       x1="508.22840"
+       y1="556.37391"
+       x2="505.28565"
+       y2="107.87502" />
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient1243"
+       id="linearGradient16223"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="scale(1.347706,0.742001)"
+       x1="508.22840"
+       y1="556.37391"
+       x2="505.28565"
+       y2="107.87502" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.52132701"
+     inkscape:cx="650.00000"
+     inkscape:cy="497.00000"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer7"
+     showgrid="true"
+     inkscape:grid-bbox="false"
+     inkscape:grid-points="false"
+     gridspacingx="5.0000000px"
+     gridspacingy="5.0000000px"
+     gridtolerance="2.5000000px"
+     inkscape:window-width="920"
+     inkscape:window-height="603"
+     inkscape:window-x="20"
+     inkscape:window-y="73" />
+  <metadata
+     id="metadata16135">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="base"
+     inkscape:groupmode="layer"
+     id="layer1"
+     style="display:inline">
+    <g
+       id="g17404"
+       transform="translate(100.0000,-75.00000)"
+       style="stroke:none;stroke-opacity:1.0000000">
+      <rect
+         ry="38.000000"
+         rx="38.000000"
+         style="fill:#ffffff;fill-opacity:0.14999999;stroke:none;stroke-opacity:1.0000000"
+         id="rrect19"
+         width="1100.0000"
+         height="844.00000"
+         x="0.0000000"
+         y="146.00000" />
+      <rect
+         ry="36.000000"
+         rx="36.000000"
+         style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000"
+         id="rrect18"
+         width="1096.0000"
+         height="840.00000"
+         x="2.0000000"
+         y="148.00000" />
+      <rect
+         ry="34.000000"
+         rx="34.000000"
+         style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000"
+         id="rrect17"
+         width="1092.0000"
+         height="836.00000"
+         x="4.0000000"
+         y="150.00000" />
+      <rect
+         ry="32.000000"
+         rx="32.000000"
+         style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000"
+         id="rrect16"
+         width="1088.0000"
+         height="832.00000"
+         x="6.0000000"
+         y="152.00000" />
+      <rect
+         ry="30.000000"
+         rx="30.000000"
+         style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000"
+         id="rrect15"
+         width="1084.0000"
+         height="828.00000"
+         x="8.0000000"
+         y="154.00000" />
+      <rect
+         ry="28.000000"
+         rx="28.000000"
+         style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000"
+         id="rrect14"
+         width="1080.0000"
+         height="824.00000"
+         x="10.000000"
+         y="156.00000" />
+      <rect
+         ry="26.000000"
+         rx="26.000000"
+         style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000"
+         id="rrect13"
+         width="1076.0000"
+         height="820.00000"
+         x="12.000000"
+         y="158.00000" />
+      <rect
+         ry="24.000000"
+         rx="24.000000"
+         style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000"
+         id="rrect12"
+         width="1072.0000"
+         height="816.00000"
+         x="14.000000"
+         y="160.00000" />
+      <rect
+         ry="22.000000"
+         rx="22.000000"
+         style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000"
+         id="rrect11"
+         width="1068.0000"
+         height="812.00000"
+         x="16.000000"
+         y="162.00000" />
+      <rect
+         ry="20.000000"
+         rx="20.000000"
+         style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000"
+         id="rrect10"
+         width="1064.0000"
+         height="808.00000"
+         x="18.000000"
+         y="164.00000" />
+      <rect
+         ry="18.000000"
+         rx="18.000000"
+         style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000"
+         id="rrect9"
+         width="1060.0000"
+         height="804.00000"
+         x="20.000000"
+         y="166.00000" />
+      <rect
+         ry="16.000000"
+         rx="16.000000"
+         style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000"
+         id="rrect8"
+         width="1056.0000"
+         height="800.00000"
+         x="22.000000"
+         y="168.00000" />
+      <rect
+         ry="14.000000"
+         rx="14.000000"
+         style="fill:#ffffff;fill-opacity:0.11999995;stroke:none;stroke-opacity:1.0000000"
+         id="rrect7"
+         width="1052.0000"
+         height="796.00000"
+         x="24.000000"
+         y="170.00000" />
+      <rect
+         ry="12.000000"
+         rx="12.000000"
+         style="fill:#ffffff;fill-opacity:0.14000000;stroke:none;stroke-opacity:1.0000000"
+         id="rrect6"
+         width="1048.0000"
+         height="792.00000"
+         x="26.000000"
+         y="172.00000" />
+      <rect
+         ry="10.000000"
+         rx="10.000000"
+         style="fill:#ffffff;fill-opacity:0.15999998;stroke:none;stroke-opacity:1.0000000"
+         id="rrect5"
+         width="1044.0000"
+         height="788.00000"
+         x="28.000000"
+         y="174.00000" />
+      <rect
+         ry="8.0000000"
+         rx="8.0000000"
+         style="fill:#ffffff;fill-opacity:0.17999996;stroke:none;stroke-opacity:1.0000000"
+         id="rrect4"
+         width="1040.0000"
+         height="784.00000"
+         x="30.000000"
+         y="176.00000" />
+      <rect
+         ry="6.0000000"
+         rx="6.0000000"
+         style="fill:#ffffff;fill-opacity:0.20000000;stroke:none;stroke-opacity:1.0000000"
+         id="rrect3"
+         width="1036.0000"
+         height="780.00000"
+         x="32.000000"
+         y="178.00000" />
+      <rect
+         ry="4.0000000"
+         rx="4.0000000"
+         style="fill:#ffffff;fill-opacity:0.21999998;stroke:none;stroke-opacity:1.0000000"
+         id="rrect2"
+         width="1032.0000"
+         height="776.00000"
+         x="34.000000"
+         y="180.00000" />
+      <rect
+         ry="2.0000000"
+         rx="2.0000000"
+         style="fill:#ffffff;fill-opacity:0.49999997;stroke:none;stroke-opacity:1.0000000"
+         id="rrect1"
+         width="1028.0000"
+         height="772.00000"
+         x="36.000000"
+         y="182.00000" />
+      <rect
+         style="fill:#ffffff;fill-opacity:1.0000000;stroke:none;stroke-width:2.0000000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+         id="rect7529"
+         width="1024.0000"
+         height="768.00000"
+         x="38.000000"
+         y="184.00000" />
+    </g>
+  </g>
+  <g
+     inkscape:groupmode="layer"
+     id="layer6"
+     inkscape:label="cuts"
+     style="display:inline">
+    <g
+       style="display:inline"
+       id="g17268"
+       transform="matrix(3.955288,0.000000,0.000000,3.955288,-1133.851,-788.5280)">
+      <g
+         transform="matrix(-1.028194e-2,1.033891e-2,-1.033891e-2,-1.028194e-2,587.3686,366.0048)"
+         style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000"
+         id="g17126">
+        <path
+           style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000"
+           sodipodi:nodetypes="ccccc"
+           id="path17128"
+           d="M 7602.2995,10592.638 L 6351.2995,11841.638 L 7603.2995,9842.6385 L 8851.2995,11843.638 L 7602.2995,10592.638 z " />
+      </g>
+      <path
+         id="text17130"
+         d="M 346.56856,325.28003 C 346.01656,325.52003 345.34456,325.66403 344.48056,325.66403 C 342.70456,325.66403 341.26456,324.51203 341.26456,322.35203 C 341.24056,320.43204 342.48856,319.06403 344.40856,319.06403 C 345.36856,319.06403 346.01656,319.23203 346.44856,319.42403 L 347.02456,316.71203 C 346.25656,316.42403 345.20056,316.25603 344.24056,316.25603 C 339.87256,316.25603 337.52056,319.06404 337.52056,322.49603 C 337.52056,326.19203 339.94456,328.52003 343.73656,328.52003 C 345.12856,328.52003 346.35256,328.28003 347.00056,327.96803 L 346.56856,325.28003 M 360.08468,316.52003 L 356.43668,316.52003 L 356.43668,323.50403 C 356.43668,323.81603 356.38868,324.08003 356.29268,324.29603 C 356.07668,324.87203 355.47668,325.56803 354.46868,325.56803 C 353.17269,325.56803 352.62068,324.53603 352.62068,322.83203 L 352.62068,316.52003 L 348.97268,316.52003 L 348.97268,323.40803 C 348.97268,327.03203 350.70069,328.52003 353.10068,328.52003 C 355.21268,328.52003 356.31669,327.32003 356.77268,326.60003 L 356.84468,326.60003 L 357.01268,328.25603 L 360.18068,328.25603 C 360.13268,327.27204 360.08468,326.02403 360.08468,324.48803 L 360.08468,316.52003 M 363.54031,314.31203 L 363.54031,316.52003 L 361.98031,316.52003 L 361.98031,319.20803 L 363.54031,319.20803 L 363.54031,324.03203 C 363.54031,325.68803 363.87631,326.81603 364.54831,327.51203 C 365.14831,328.11203 366.13231,328.52003 367.30831,328.52003 C 368.31631,328.52003 369.20431,328.37603 369.66031,328.20803 L 369.63631,325.44803 C 369.30031,325.52003 369.06031,325.54403 368.55631,325.54403 C 367.47631,325.54403 367.11631,324.89603 367.11631,323.48003 L 367.11631,319.20803 L 369.73231,319.20803 L 369.73231,316.52003 L 367.11631,316.52003 L 367.11631,313.32803 L 363.54031,314.31203 M 371.17681,327.68003 C 372.06481,328.16003 373.43281,328.52003 374.96881,328.52003 C 378.32881,328.52003 380.03281,326.91203 380.03281,324.70403 C 380.00881,323.00004 379.09681,321.84803 376.86481,321.10403 C 375.42481,320.60003 374.96881,320.31203 374.96881,319.73603 C 374.96881,319.16003 375.47281,318.80003 376.36081,318.80003 C 377.34481,318.80003 378.37681,319.18403 378.90481,319.44803 L 379.52881,316.95203 C 378.80881,316.59203 377.60881,316.25603 376.24081,316.25603 C 373.33681,316.25603 371.46481,317.91204 371.46481,320.12003 C 371.44081,321.48803 372.37681,322.83203 374.82481,323.62403 C 376.16881,324.08003 376.52881,324.36803 376.52881,324.99203 C 376.52881,325.59203 376.07281,325.95203 374.96881,325.95203 C 373.88881,325.95203 372.49681,325.49603 371.82481,325.08803 L 371.17681,327.68003"
+         style="font-size:24.000000px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:125.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#007f00;fill-opacity:1.0000000;stroke:none;stroke-width:1.0000000pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000;font-family:Myriad" />
+    </g>
+  </g>
+  <g
+     inkscape:groupmode="layer"
+     id="layer5"
+     inkscape:label="scissors"
+     style="display:inline">
+    <g
+       style="display:inline"
+       transform="matrix(-0.261242,0.531875,-0.531875,-0.261243,609.4123,269.4384)"
+       id="g834">
+      <path
+         transform="matrix(-0.974540,0.224211,0.224211,0.974540,434.7533,-39.90828)"
+         style="font-size:12.000000px;fill:#dadadb;fill-rule:evenodd;stroke:#000000;stroke-width:10.000006;stroke-linejoin:round;stroke-dasharray:none"
+         id="path693"
+         d="M 130.58000,19.228100 C 131.42800,19.228100 283.20600,268.51700 283.20600,268.51700 C 283.20600,268.51700 237.41800,294.80300 238.26600,294.80300 C 239.11400,294.80300 112.77400,100.62900 130.58000,19.228100 z " />
+      <path
+         style="font-size:12.000000px;fill:#1f1f61;fill-opacity:1.0000000;fill-rule:evenodd;stroke:#000000;stroke-width:10.000000;stroke-linejoin:bevel;stroke-dasharray:none"
+         id="path596"
+         d="M 267.36640,300.28500 C 267.36640,300.28500 221.96450,419.33820 230.36720,437.01870 C 230.00410,447.80450 196.57070,496.47240 174.95750,496.94460 C 156.32120,498.11630 95.023300,483.45520 104.85110,423.19450 C 116.53670,361.19710 166.80670,382.68650 186.68190,380.35660 C 206.55780,378.02600 240.34010,301.17560 216.89540,284.78780 C 243.06010,291.66780 266.70660,302.06270 267.36640,300.28500 z M 178.01080,388.46270 C 110.22310,370.58330 97.043850,476.92290 157.42350,483.15570 C 225.11850,486.03500 224.54920,396.02940 178.01080,388.46270 z " />
+      <path
+         transform="matrix(0.984591,0.174877,-0.174877,0.984591,41.27270,-35.37063)"
+         style="font-size:12.000000px;fill:#dadadb;fill-rule:evenodd;stroke:#000000;stroke-width:9.9999933;stroke-linejoin:bevel;stroke-dasharray:none"
+         id="path674"
+         d="M 130.58000,19.228100 C 131.42800,19.228100 283.20600,268.51700 283.20600,268.51700 C 283.20600,268.51700 237.41800,294.80300 238.26600,294.80300 C 239.11400,294.80300 112.77400,100.62900 130.58000,19.228100 z " />
+      <path
+         transform="translate(161.5948,57.16911)"
+         style="font-size:12.000000px;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:6.2500000;stroke-dasharray:none"
+         sodipodi:nodetypes="ccc"
+         id="path710"
+         d="M 81.400500,200.68300 C 66.137900,201.53100 63.594200,225.27300 81.400500,226.12100 C 98.359000,225.27300 98.359200,200.68300 81.400500,200.68300 z " />
+      <path
+         transform="translate(161.5948,57.16911)"
+         style="font-size:12.000000px;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:6.2500000;stroke-dasharray:none"
+         id="path711"
+         d="M 69.529600,209.16300 C 71.225500,209.16300 86.488100,224.42500 86.488100,224.42500" />
+      <path
+         transform="translate(161.5948,57.16911)"
+         style="font-size:12.000000px;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:6.2500000;stroke-dasharray:none"
+         sodipodi:nodetypes="cc"
+         id="path712"
+         d="M 76.313000,203.22700 C 77.160900,203.22700 92.423500,218.49000 92.423500,218.49000" />
+      <path
+         style="font-size:12.000000px;fill:#e6ffff;fill-opacity:0.75000000;fill-rule:evenodd;stroke-width:1.0000000pt"
+         sodipodi:nodetypes="cccc"
+         id="path717"
+         d="M 311.59912,21.282200 C 312.44712,21.282200 250.54912,207.82500 250.54912,207.82500 C 250.54912,207.82500 257.17737,220.62188 259.72037,219.77388 C 262.26437,218.92588 318.38312,30.609400 311.59912,21.282200 z " />
+      <path
+         transform="translate(-3.750000,3.750000)"
+         style="font-size:12.000000px;fill-opacity:0.31851897;fill-rule:evenodd;stroke-width:1.0000000pt"
+         sodipodi:nodetypes="ccccc"
+         id="path718"
+         d="M 236.85900,262.03100 L 240.39000,257.08300 L 256.63200,272.60800 L 252.68100,276.70800 L 236.85900,262.03100 z " />
+      <path
+         style="font-size:12.000000px;fill:#1f1f61;fill-opacity:1.0000000;fill-rule:evenodd;stroke:#000000;stroke-width:10.000000;stroke-linejoin:bevel;stroke-dasharray:none"
+         id="path590"
+         d="M 319.25070,379.53570 C 386.05280,358.26700 404.56760,463.80860 344.57810,473.07250 C 277.11370,479.35530 273.15220,389.43500 319.25070,379.53570 z M 225.57020,295.96700 C 225.57020,295.96700 276.90680,412.58430 269.40450,430.66530 C 270.31010,441.41910 306.15060,488.34270 327.76030,487.72650 C 346.43190,487.95870 406.91430,470.23100 394.06590,410.54120 C 379.27480,349.21050 330.15000,373.20280 310.18270,371.87620 C 290.21460,370.54890 252.60710,295.49620 275.19730,277.94910 C 249.41200,286.13730 226.31860,297.70920 225.57020,295.96700 z " />
+    </g>
+  </g>
+  <g
+     inkscape:groupmode="layer"
+     id="layer4"
+     inkscape:label="breaks"
+     style="display:inline">
+    <g
+       style="display:inline"
+       id="g17263"
+       transform="matrix(3.955288,0.000000,0.000000,3.955288,-654.3060,-855.6644)">
+      <g
+         transform="matrix(0.000000,1.458120e-2,1.458120e-2,0.000000,167.9907,189.6206)"
+         style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000"
+         id="g2604">
+        <path
+           style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000"
+           sodipodi:nodetypes="ccccc"
+           id="path2606"
+           d="M 7601.0000,11063.000 L 6350.0000,12312.000 L 7602.0000,10313.000 L 8850.0000,12314.000 L 7601.0000,11063.000 z " />
+      </g>
+      <path
+         id="text17114"
+         d="M 299.55643,273.07213 C 299.55643,274.39213 299.50843,275.80813 299.46043,276.57613 L 302.55643,276.57613 L 302.70043,274.94413 L 302.74843,274.94413 C 303.56443,276.33613 304.90843,276.84013 306.27643,276.84013 C 308.96443,276.84013 311.62843,274.72813 311.62843,270.50413 C 311.65243,266.90413 309.61243,264.57613 306.80443,264.57613 C 305.17243,264.57613 303.94843,265.22413 303.25243,266.23213 L 303.20443,266.23213 L 303.20443,259.53613 L 299.55643,259.53613 L 299.55643,273.07213 M 303.20443,269.85613 C 303.20443,269.61613 303.22843,269.40013 303.27643,269.18413 C 303.51643,268.12813 304.42843,267.38413 305.41243,267.38413 C 307.11643,267.38413 307.93243,268.82413 307.93243,270.64813 C 307.93243,272.76013 306.97243,273.96013 305.41243,273.96013 C 304.35643,273.96013 303.51643,273.19213 303.27643,272.23213 C 303.22843,272.04013 303.20443,271.82413 303.20443,271.58413 L 303.20443,269.85613 M 313.90018,276.57613 L 317.54818,276.57613 L 317.54818,270.64813 C 317.54818,270.33613 317.57218,270.07213 317.62018,269.83213 C 317.86018,268.68013 318.77218,267.98413 320.11618,267.98413 C 320.52418,267.98413 320.81218,268.03213 321.12418,268.08013 L 321.12418,264.64813 C 320.86018,264.60013 320.69218,264.57613 320.35618,264.57613 C 319.20418,264.57613 317.78818,265.29613 317.18818,267.02413 L 317.09218,267.02413 L 316.94818,264.84013 L 313.82818,264.84013 C 313.90018,265.84813 313.92418,266.97613 313.92418,268.70413 L 313.90018,276.57613 M 333.40881,271.87213 C 333.45681,271.58413 333.52881,271.03213 333.52881,270.40813 C 333.52881,267.50413 332.08880,264.55213 328.29681,264.55213 C 324.24081,264.55213 322.36881,267.84013 322.36881,270.81613 C 322.36881,274.51213 324.64881,276.81613 328.63281,276.81613 C 330.21681,276.81613 331.68081,276.57613 332.88081,276.07213 L 332.40081,273.60013 C 331.41681,273.93613 330.40881,274.10413 329.16081,274.10413 C 327.45681,274.10413 325.96881,273.38413 325.84881,271.84813 L 333.40881,271.87213 M 325.82481,269.35213 C 325.92081,268.39213 326.54481,266.97613 328.10481,266.97613 C 329.76081,266.97613 330.14481,268.48813 330.14481,269.35213 L 325.82481,269.35213 M 345.46506,269.64013 C 345.46506,266.88013 344.24105,264.57613 340.32906,264.57613 C 338.19306,264.57613 336.58506,265.17613 335.76906,265.63213 L 336.44106,267.96013 C 337.20906,267.50413 338.48106,267.09613 339.68106,267.09613 C 341.48106,267.09613 341.81706,267.98413 341.81706,268.60813 L 341.81706,268.75213 C 337.66506,268.75213 334.92906,270.19213 334.92906,273.24013 C 334.92906,275.11213 336.34506,276.84013 338.72106,276.84013 C 340.11306,276.84013 341.31306,276.33613 342.08106,275.40013 L 342.15306,275.40013 L 342.36906,276.57613 L 345.65706,276.57613 C 345.51306,275.92813 345.46506,274.84813 345.46506,273.74413 L 345.46506,269.64013 M 341.93706,272.30413 C 341.93706,272.52013 341.91306,272.73613 341.86506,272.92813 C 341.62506,273.67213 340.85706,274.27213 339.96906,274.27213 C 339.15306,274.27213 338.52906,273.81613 338.52906,272.88013 C 338.52906,271.48813 340.01706,271.03213 341.93706,271.03213 L 341.93706,272.30413 M 352.00131,259.53613 L 348.35331,259.53613 L 348.35331,276.57613 L 352.00131,276.57613 L 352.00131,272.92813 L 352.91331,271.75213 L 355.76931,276.57613 L 360.25731,276.57613 L 355.45731,269.59213 L 359.65731,264.84013 L 355.26531,264.84013 L 352.88931,268.39213 C 352.60131,268.82413 352.31331,269.30413 352.04931,269.80813 L 352.00131,269.80813 L 352.00131,259.53613 M 360.71256,276.00013 C 361.60056,276.48013 362.96856,276.84013 364.50456,276.84013 C 367.86455,276.84013 369.56856,275.23213 369.56856,273.02413 C 369.54456,271.32013 368.63256,270.16813 366.40056,269.42413 C 364.96056,268.92013 364.50456,268.63213 364.50456,268.05613 C 364.50456,267.48013 365.00856,267.12013 365.89656,267.12013 C 366.88056,267.12013 367.91256,267.50413 368.44056,267.76813 L 369.06456,265.27213 C 368.34456,264.91213 367.14456,264.57613 365.77656,264.57613 C 362.87256,264.57613 361.00056,266.23213 361.00056,268.44013 C 360.97656,269.80813 361.91256,271.15213 364.36056,271.94413 C 365.70456,272.40013 366.06456,272.68813 366.06456,273.31213 C 366.06456,273.91213 365.60856,274.27213 364.50456,274.27213 C 363.42456,274.27213 362.03256,273.81613 361.36056,273.40813 L 360.71256,276.00013"
+         style="font-size:24.000000px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:125.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#007f00;fill-opacity:1.0000000;stroke:none;stroke-width:1.0000000pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000;font-family:Myriad" />
+    </g>
+  </g>
+  <g
+     inkscape:groupmode="layer"
+     id="layer3"
+     inkscape:label="rock"
+     style="display:inline">
+    <g
+       style="display:inline"
+       transform="matrix(0.708388,0.000000,0.000000,0.708388,768.4189,171.0555)"
+       id="g2067">
+      <path
+         sodipodi:nodetypes="cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+         id="path10"
+         d="M 149.15160,130.25073 L 138.01458,125.99417 L 132.85423,131.15452 L 127.69388,137.17493 L 120.81341,144.91545 L 113.07289,154.37609 L 105.33236,163.83673 L 97.591837,173.29738 L 89.851312,183.61808 L 82.970845,194.79883 L 76.090379,205.11953 L 70.069971,215.44023 L 64.909621,224.04082 L 61.469388,232.64140 L 58.889213,240.38192 L 58.889213,246.40233 L 60.609329,250.70262 L 66.629738,257.58309 L 73.510204,263.60350 L 82.110787,269.62391 L 90.711370,275.64431 L 100.17201,280.80466 L 108.77259,285.96501 L 117.37318,291.98542 L 124.25364,296.28571 L 129.41399,300.58601 L 132.85423,304.02624 L 135.43440,306.60641 L 138.01458,308.32653 L 140.59475,310.04665 L 144.03499,311.76676 L 150.05539,314.34694 L 156.93586,316.92711 L 165.53644,319.50729 L 195.63848,318.64723 L 201.65889,318.64723 L 208.53936,318.64723 L 216.27988,319.50729 L 224.02041,320.36735 L 230.90087,321.22741 L 236.06122,323.80758 L 241.22157,325.52770 L 248.10204,325.52770 L 254.98251,325.52770 L 261.86297,324.66764 L 268.74344,322.94752 L 275.62391,321.22741 L 281.64431,318.64723 L 286.80466,316.92711 L 291.10496,314.34694 L 295.40525,310.90671 L 298.84548,306.60641 L 303.14577,302.30612 L 306.58601,298.00583 L 310.02624,293.70554 L 312.60641,291.12536 L 315.18659,290.26531 L 318.62682,290.26531 L 322.92711,289.40525 L 328.94752,287.68513 L 334.96793,285.10496 L 340.98834,283.38484 L 346.14869,280.80466 L 349.58892,279.08455 L 351.30904,277.36443 L 356.78718,268.76385 L 364.48397,254.32361 L 363.12536,245.36152 L 359.04956,237.80175 L 362.48980,236.94169 L 365.93003,234.36152 L 368.51020,230.92128 L 371.09038,225.76093 L 373.67055,221.46064 L 375.39067,218.02041 L 376.25073,215.44023 L 377.11079,214.58017 L 365.93003,182.75802 L 364.20991,181.03790 L 361.62974,176.73761 L 357.32945,171.57726 L 352.16910,164.69679 L 347.00875,158.67638 L 342.70845,153.51603 L 333.79008,153.06414 L 329.62682,149.89505 L 322.92711,148.35569 L 320.03207,145.27697 L 315.64140,143.64723 L 312.97085,142.01749 L 308.94169,139.52769 L 304.14285,137.62682 L 299.34403,135.63557 L 295.22449,130.56560 L 290.24490,127.71429 L 286.80466,123.41399 L 284.22449,119.97376 L 282.50437,117.39359 L 281.64431,116.53353 L 239.50146,101.91254 L 238.64140,101.91254 L 236.06122,101.05248 L 231.76093,100.19242 L 227.46064,99.332362 L 222.30029,98.472303 L 218.00000,98.472303 L 213.69971,98.472303 L 211.11953,98.472303 L 181.51020,124.82216 L 149.15160,130.25073 z "
+         style="fill:#b5abab;fill-opacity:1.0000000" />
+      <path
+         sodipodi:nodetypes="cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+         id="path1333"
+         d="M 272.27930,110.03646 L 278.00000,110.00000 L 281.00000,109.00000 L 285.00000,109.00000 L 288.00000,109.00000 L 290.00000,113.00000 L 293.00000,116.00000 L 295.00000,119.00000 L 298.00000,123.00000 L 300.00000,126.00000 L 302.00000,130.00000 L 303.00000,134.00000 L 303.00000,138.00000 L 302.00000,139.00000 L 302.00000,139.00000 L 301.00000,140.00000 L 301.00000,140.00000 L 297.00000,137.00000 L 293.00000,135.00000 L 290.00000,132.00000 L 287.00000,129.00000 L 284.00000,128.00000 L 280.00000,127.00000 L 277.00000,126.00000 L 273.00000,126.00000 L 270.00000,125.00000 L 266.00000,125.00000 L 262.00000,125.00000 L 259.00000,125.00000 L 254.00000,122.00000 L 249.00000,119.00000 L 245.00000,116.00000 L 240.00000,112.00000 L 235.00000,110.00000 L 230.00000,108.00000 L 225.00000,109.00000 L 219.00000,111.00000 L 214.00000,113.00000 L 209.00000,116.00000 L 204.00000,119.00000 L 199.00000,122.00000 L 194.00000,125.00000 L 190.00000,129.00000 L 186.00000,134.00000 L 183.00000,139.00000 L 177.00000,141.00000 L 171.00000,143.00000 L 164.00000,143.00000 L 157.00000,143.00000 L 150.00000,144.00000 L 143.00000,145.00000 L 137.00000,147.00000 L 131.00000,151.00000 L 129.00000,153.00000 L 127.00000,155.00000 L 125.00000,158.00000 L 124.00000,161.00000 L 117.00000,167.00000 L 111.00000,174.00000 L 106.00000,181.00000 L 101.00000,188.00000 L 96.000000,195.00000 L 92.000000,203.00000 L 87.000000,211.00000 L 81.000000,218.00000 L 78.000000,225.00000 L 74.000000,231.00000 L 70.000000,238.00000 L 69.000000,246.00000 L 74.000000,250.00000 L 79.000000,254.00000 L 83.000000,259.00000 L 88.000000,263.00000 L 93.000000,267.00000 L 97.000000,272.00000 L 102.00000,276.00000 L 107.00000,280.00000 L 111.00000,284.00000 L 116.00000,287.00000 L 121.00000,291.00000 L 126.00000,294.00000 L 132.00000,296.00000 L 138.00000,299.00000 L 144.00000,301.00000 L 150.00000,302.00000 L 155.00000,302.00000 L 159.00000,302.00000 L 164.00000,302.00000 L 168.00000,302.00000 L 172.00000,302.00000 L 176.00000,301.00000 L 180.00000,300.00000 L 184.00000,297.00000 L 188.00000,296.00000 L 191.00000,296.00000 L 193.00000,297.00000 L 196.00000,300.00000 L 198.00000,302.00000 L 201.00000,304.00000 L 204.00000,306.00000 L 207.00000,306.00000 L 211.00000,308.00000 L 214.00000,309.00000 L 218.00000,310.00000 L 222.00000,311.00000 L 226.00000,312.00000 L 230.00000,312.00000 L 233.00000,313.00000 L 237.00000,314.00000 L 240.00000,314.00000 L 244.00000,314.00000 L 246.00000,314.00000 L 249.00000,313.00000 L 252.00000,312.00000 L 255.00000,311.00000 L 258.00000,311.00000 L 261.00000,311.00000 L 267.00000,308.00000 L 273.00000,305.00000 L 279.00000,301.00000 L 285.00000,296.00000 L 290.00000,291.00000 L 296.00000,287.00000 L 302.00000,282.00000 L 308.00000,278.00000 L 312.00000,277.00000 L 316.00000,276.00000 L 321.00000,276.00000 L 325.00000,275.00000 L 329.00000,275.00000 L 334.00000,275.00000 L 338.00000,274.00000 L 343.00000,274.00000 L 344.00000,272.00000 L 346.00000,270.00000 L 349.00000,268.00000 L 351.00000,265.00000 L 354.00000,263.00000 L 356.00000,259.00000 L 357.00000,256.00000 L 359.00000,253.00000 L 357.00000,248.00000 L 355.00000,244.00000 L 353.00000,239.00000 L 352.00000,234.00000 L 355.00000,231.00000 L 359.00000,228.00000 L 363.00000,226.00000 L 366.00000,222.00000 L 363.00000,217.00000 L 359.00000,212.00000 L 355.00000,206.00000 L 354.00000,200.00000 L 356.00000,192.00000 L 358.00000,183.00000 L 358.00000,175.00000 L 354.00000,167.00000 L 352.00000,165.00000 L 349.00000,163.00000 L 347.00000,161.00000 L 344.00000,160.00000 L 341.00000,159.00000 L 338.00000,158.00000 L 335.00000,158.00000 L 332.00000,158.00000 L 330.00000,156.00000 L 328.00000,154.00000 L 327.00000,153.00000 L 327.00000,150.00000 L 329.00000,149.00000 L 335.00000,150.00000 L 342.00000,151.00000 L 349.00000,152.00000 L 355.00000,154.00000 L 361.00000,156.00000 L 367.00000,160.00000 L 371.00000,164.00000 L 374.00000,171.00000 L 374.00000,178.00000 L 373.00000,186.00000 L 372.00000,193.00000 L 375.00000,200.00000 L 379.00000,204.00000 L 382.00000,208.00000 L 386.00000,212.00000 L 388.00000,216.00000 L 389.00000,216.00000 L 389.00000,217.00000 L 389.00000,218.00000 L 389.00000,219.00000 L 389.00000,219.00000 L 391.00000,219.00000 L 391.00000,224.00000 L 390.00000,227.00000 L 388.00000,230.00000 L 385.00000,233.00000 L 382.00000,235.00000 L 378.00000,238.00000 L 375.00000,240.00000 L 373.00000,243.00000 L 372.00000,249.00000 L 372.00000,254.00000 L 370.00000,259.00000 L 367.00000,264.00000 L 365.00000,269.00000 L 362.00000,274.00000 L 358.00000,279.00000 L 353.00000,283.00000 L 348.00000,286.00000 L 343.00000,289.00000 L 338.00000,292.00000 L 332.00000,293.00000 L 328.00000,293.00000 L 325.00000,294.00000 L 321.00000,296.00000 L 319.00000,298.00000 L 317.00000,302.00000 L 315.00000,305.00000 L 313.00000,308.00000 L 311.00000,312.00000 L 308.00000,315.00000 L 306.00000,318.00000 L 302.00000,321.00000 L 299.00000,322.00000 L 295.00000,324.00000 L 291.00000,325.00000 L 288.00000,327.00000 L 284.00000,329.00000 L 276.00000,330.00000 L 267.00000,332.00000 L 259.00000,333.00000 L 250.00000,333.00000 L 242.00000,333.00000 L 233.00000,333.00000 L 225.00000,332.00000 L 217.00000,329.00000 L 212.00000,328.00000 L 207.00000,327.00000 L 202.00000,325.00000 L 197.00000,324.00000 L 192.00000,323.00000 L 187.00000,323.00000 L 182.00000,324.00000 L 178.00000,326.00000 L 168.00000,325.00000 L 158.00000,322.00000 L 149.00000,317.00000 L 140.00000,312.00000 L 131.00000,306.00000 L 123.00000,301.00000 L 115.00000,295.00000 L 108.00000,291.00000 L 105.00000,289.00000 L 102.00000,286.00000 L 98.000000,284.00000 L 94.000000,283.00000 L 90.000000,281.00000 L 86.000000,279.00000 L 83.000000,277.00000 L 79.000000,275.00000 L 75.000000,272.00000 L 71.000000,269.00000 L 66.000000,266.00000 L 62.000000,263.00000 L 58.000000,260.00000 L 54.000000,256.00000 L 51.000000,251.00000 L 49.000000,247.00000 L 51.000000,238.00000 L 54.000000,229.00000 L 58.000000,221.00000 L 63.000000,213.00000 L 85.000000,179.00000 L 89.000000,173.00000 L 94.000000,167.00000 L 99.000000,162.00000 L 104.00000,156.00000 L 108.00000,151.00000 L 113.00000,146.00000 L 117.00000,141.00000 L 121.00000,135.00000 L 125.00000,132.00000 L 128.00000,129.00000 L 132.00000,126.00000 L 135.00000,123.00000 L 139.00000,121.00000 L 143.00000,119.00000 L 148.00000,118.00000 L 152.00000,117.00000 L 157.00000,117.00000 L 162.00000,117.00000 L 167.00000,117.00000 L 172.00000,117.00000 L 176.00000,117.00000 L 181.00000,115.00000 L 185.00000,113.00000 L 189.00000,110.00000 L 192.00000,107.00000 L 196.00000,105.00000 L 200.00000,102.00000 L 203.00000,99.000000 L 207.00000,96.000000 L 210.00000,94.000000 L 214.00000,92.000000 L 219.00000,91.000000 L 221.00000,89.000000 L 223.00000,88.000000 L 227.00000,89.000000 L 230.00000,89.000000 L 234.00000,89.000000 L 237.00000,91.000000 L 241.00000,92.000000 L 244.00000,95.000000 L 247.00000,97.000000 L 250.00000,100.00000 L 253.00000,103.00000 L 257.03646,105.51823 L 262.08918,108.23892"
+         style="fill:#000000" />
+      <path
+         sodipodi:nodetypes="ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+         style="fill:#645858;fill-opacity:1.0000000"
+         d="M 289.76968,176.61808 L 294.76968,177.61808 L 298.76968,178.61808 L 303.76968,179.61808 L 308.76968,180.61808 L 312.76968,182.61808 L 316.76968,184.61808 L 320.76968,186.61808 L 322.88387,187.07485 L 323.76968,189.55120 L 325.24603,192.02754 L 322.76968,193.61808 L 320.88387,193.01571 L 319.76968,193.61808 L 316.76968,193.61808 L 313.58860,194.38970 L 311.00000,195.69680 L 307.54519,197.77551 L 303.00583,200.85423 L 298.46647,201.08455 L 293.92711,197.23616 L 287.84840,196.69680 L 283.30904,197.46648 L 279.53936,196.46648 L 275.76968,193.69680 L 269.32070,193.78135 L 264.55102,194.01167 L 259.78134,194.70263 L 256.55102,193.85423 L 252.62974,193.46648 L 245.24198,195.69680 L 240.70262,196.38776 L 235.62391,196.84840 L 230.31487,199.61808 L 225.77551,203.69680 L 218.92711,207.23616 L 213.16327,211.85423 L 206.31487,213.16327 L 201.23615,211.93295 L 193.84840,210.70263 L 187.99806,205.86607 L 181.57290,203.02154 L 174.66149,202.84239 L 166.45481,204.08455 L 159.37609,206.62391 L 151.06495,208.38970 L 147.76968,206.79916 L 144.29333,204.91335 L 142.58860,202.02754 L 141.58860,199.14173 L 142.47441,196.07485 L 146.76968,196.61808 L 151.76968,194.61808 L 156.76968,191.61808 L 161.76968,189.61808 L 165.76968,187.61808 L 170.76968,185.61808 L 175.76968,182.61808 L 180.76968,180.61808 L 183.76968,180.61808 L 187.76968,179.61808 L 190.76968,180.61808 L 193.76968,181.61808 L 196.76968,182.61808 L 198.76968,183.61808 L 201.76968,185.61808 L 204.76968,188.61808 L 208.76968,187.61808 L 212.76968,184.61808 L 215.76968,180.61808 L 217.76968,176.61808 L 221.76968,174.61808 L 225.76968,172.61808 L 229.76968,169.61808 L 233.76968,167.61808 L 237.76968,165.61808 L 242.76968,163.61808 L 246.76968,161.61808 L 250.76968,159.61808 L 256.76968,160.61808 L 261.76968,162.61808 L 265.76968,165.61808 L 269.76968,169.61808 L 274.76968,173.61808 L 278.76968,175.61808 L 283.76968,177.61808 L 289.76968,176.61808 z "
+         id="path2065" />
+      <path
+         id="path16"
+         d="M 289.00000,172.00000 L 294.00000,173.00000 L 298.00000,174.00000 L 303.00000,175.00000 L 308.00000,176.00000 L 312.00000,178.00000 L 316.00000,180.00000 L 320.00000,182.00000 L 323.00000,186.00000 L 323.00000,187.00000 L 323.00000,188.00000 L 322.00000,189.00000 L 321.00000,190.00000 L 319.00000,189.00000 L 316.00000,189.00000 L 314.00000,188.00000 L 311.00000,188.00000 L 308.00000,188.00000 L 305.00000,188.00000 L 303.00000,188.00000 L 300.00000,188.00000 L 296.00000,187.00000 L 293.00000,187.00000 L 290.00000,188.00000 L 287.00000,188.00000 L 284.00000,189.00000 L 281.00000,189.00000 L 278.00000,188.00000 L 275.00000,186.00000 L 272.00000,184.00000 L 268.00000,181.00000 L 264.00000,178.00000 L 260.00000,176.00000 L 256.00000,174.00000 L 252.00000,173.00000 L 247.00000,173.00000 L 243.00000,174.00000 L 239.00000,177.00000 L 235.00000,180.00000 L 232.00000,183.00000 L 229.00000,186.00000 L 228.00000,185.00000 L 226.00000,188.00000 L 223.00000,191.00000 L 221.00000,193.00000 L 218.00000,195.00000 L 215.00000,196.00000 L 212.00000,198.00000 L 210.00000,200.00000 L 207.00000,202.00000 L 204.00000,201.00000 L 202.00000,200.00000 L 199.00000,200.00000 L 197.00000,198.00000 L 194.00000,197.00000 L 192.00000,195.00000 L 190.00000,193.00000 L 189.00000,191.00000 L 185.00000,190.00000 L 182.00000,190.00000 L 178.00000,191.00000 L 174.00000,192.00000 L 150.00000,202.00000 L 147.00000,201.00000 L 145.00000,200.00000 L 143.00000,198.00000 L 142.00000,196.00000 L 142.00000,195.00000 L 146.00000,192.00000 L 151.00000,190.00000 L 156.00000,187.00000 L 161.00000,185.00000 L 165.00000,183.00000 L 170.00000,181.00000 L 175.00000,178.00000 L 180.00000,176.00000 L 183.00000,176.00000 L 187.00000,175.00000 L 190.00000,176.00000 L 193.00000,177.00000 L 196.00000,178.00000 L 198.00000,179.00000 L 201.00000,181.00000 L 204.00000,184.00000 L 208.00000,183.00000 L 212.00000,180.00000 L 215.00000,176.00000 L 217.00000,172.00000 L 221.00000,170.00000 L 225.00000,168.00000 L 229.00000,165.00000 L 233.00000,163.00000 L 237.00000,161.00000 L 242.00000,159.00000 L 246.00000,157.00000 L 250.00000,155.00000 L 256.00000,156.00000 L 261.00000,158.00000 L 265.00000,161.00000 L 269.00000,165.00000 L 274.00000,169.00000 L 278.00000,171.00000 L 283.00000,173.00000 L 289.00000,172.00000 z "
+         style="fill:#000000" />
+    </g>
+  </g>
+  <g
+     inkscape:groupmode="layer"
+     id="layer8"
+     inkscape:label="covers"
+     style="display:inline">
+    <g
+       id="g17273"
+       transform="matrix(3.955288,0.000000,0.000000,3.955288,155.1671,-915.1278)">
+      <g
+         id="g17118"
+         style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000"
+         transform="matrix(1.274278e-2,7.087528e-3,-7.087528e-3,1.274278e-2,147.7444,148.5166)">
+        <path
+           d="M 7601.0000,11063.000 L 6350.0000,12312.000 L 7602.0000,10313.000 L 8850.0000,12314.000 L 7601.0000,11063.000 z "
+           id="path17120"
+           sodipodi:nodetypes="ccccc"
+           style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000" />
+      </g>
+      <path
+         id="text17122"
+         d="M 187.95573,356.23294 C 187.40374,356.47294 186.73173,356.61694 185.86773,356.61694 C 184.09174,356.61694 182.65173,355.46494 182.65173,353.30494 C 182.62773,351.38494 183.87574,350.01694 185.79573,350.01694 C 186.75573,350.01694 187.40374,350.18494 187.83573,350.37694 L 188.41173,347.66494 C 187.64374,347.37694 186.58773,347.20894 185.62773,347.20894 C 181.25974,347.20894 178.90773,350.01694 178.90773,353.44894 C 178.90773,357.14493 181.33174,359.47294 185.12373,359.47294 C 186.51573,359.47294 187.73974,359.23294 188.38773,358.92094 L 187.95573,356.23294 M 195.83186,359.47294 C 198.95186,359.47294 201.99986,357.50493 201.99986,353.23294 C 201.99986,349.68094 199.59986,347.20894 196.02386,347.20894 C 192.23186,347.20894 189.73586,349.63294 189.73586,353.42494 C 189.73586,357.21693 192.37586,359.47294 195.80786,359.47294 L 195.83186,359.47294 M 195.85586,356.85694 C 194.31986,356.85694 193.47986,355.34494 193.47986,353.35294 C 193.47986,351.60094 194.15186,349.82494 195.87986,349.82494 C 197.53586,349.82494 198.20786,351.60094 198.20786,353.32894 C 198.20786,355.44094 197.31986,356.85694 195.87986,356.85694 L 195.85586,356.85694 M 202.98798,347.47294 L 207.25998,359.20894 L 210.90798,359.20894 L 215.27598,347.47294 L 211.43598,347.47294 L 209.92398,352.92094 C 209.65999,353.92894 209.46798,354.81694 209.27598,355.77694 L 209.20398,355.77694 C 209.01199,354.84094 208.81998,353.90494 208.53198,352.92094 L 206.94798,347.47294 L 202.98798,347.47294 M 227.30711,354.50494 C 227.35511,354.21694 227.42711,353.66494 227.42711,353.04094 C 227.42711,350.13694 225.98711,347.18494 222.19511,347.18494 C 218.13911,347.18494 216.26711,350.47294 216.26711,353.44894 C 216.26711,357.14493 218.54711,359.44894 222.53111,359.44894 C 224.11511,359.44894 225.57911,359.20894 226.77911,358.70494 L 226.29911,356.23294 C 225.31511,356.56894 224.30711,356.73694 223.05911,356.73694 C 221.35511,356.73694 219.86711,356.01694 219.74711,354.48094 L 227.30711,354.50494 M 219.72311,351.98494 C 219.81911,351.02494 220.44311,349.60894 222.00311,349.60894 C 223.65911,349.60894 224.04311,351.12094 224.04311,351.98494 L 219.72311,351.98494 M 229.59536,359.20894 L 233.24336,359.20894 L 233.24336,353.28094 C 233.24336,352.96894 233.26736,352.70494 233.31536,352.46494 C 233.55536,351.31294 234.46736,350.61694 235.81136,350.61694 C 236.21936,350.61694 236.50736,350.66494 236.81936,350.71294 L 236.81936,347.28094 C 236.55536,347.23294 236.38736,347.20894 236.05136,347.20894 C 234.89936,347.20894 233.48336,347.92894 232.88336,349.65694 L 232.78736,349.65694 L 232.64336,347.47294 L 229.52336,347.47294 C 229.59536,348.48094 229.61936,349.60894 229.61936,351.33694 L 229.59536,359.20894 M 238.06398,358.63294 C 238.95198,359.11294 240.31999,359.47294 241.85598,359.47294 C 245.21598,359.47294 246.91998,357.86494 246.91998,355.65694 C 246.89598,353.95294 245.98398,352.80094 243.75198,352.05694 C 242.31199,351.55294 241.85598,351.26494 241.85598,350.68894 C 241.85598,350.11294 242.35999,349.75294 243.24798,349.75294 C 244.23198,349.75294 245.26399,350.13694 245.79198,350.40094 L 246.41598,347.90494 C 245.69599,347.54494 244.49598,347.20894 243.12798,347.20894 C 240.22399,347.20894 238.35198,348.86494 238.35198,351.07294 C 238.32798,352.44094 239.26399,353.78494 241.71198,354.57694 C 243.05598,355.03294 243.41598,355.32094 243.41598,355.94494 C 243.41598,356.54494 242.95998,356.90494 241.85598,356.90494 C 240.77599,356.90494 239.38398,356.44894 238.71198,356.04094 L 238.06398,358.63294"
+         style="font-size:24.000000px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:125.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#007f00;fill-opacity:1.0000000;stroke:none;stroke-width:1.0000000pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000;font-family:Myriad" />
+    </g>
+  </g>
+  <g
+     inkscape:groupmode="layer"
+     id="layer7"
+     inkscape:label="paper"
+     style="display:inline">
+    <g
+       style="display:inline"
+       id="g17136"
+       transform="matrix(3.955288,0.000000,0.000000,3.955288,-708.3488,-857.6103)">
+      <path
+         sodipodi:nodetypes="cccccccc"
+         d="M 390.34708,372.49332 L 332.34539,427.86139 L 272.20460,392.33038 L 341.37790,339.74173 L 378.06120,351.10999 C 379.20468,351.78631 380.06344,352.64698 380.62363,353.61296 L 390.84522,371.30530 C 391.02046,371.60027 390.83244,372.00903 390.34708,372.49332 z "
+         style="fill:#ffff19;fill-opacity:1.0000000;stroke:#000000;stroke-width:1.6000000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+         id="path12105" />
+      <path
+         id="path12107"
+         style="fill:#bebe12;fill-opacity:1.0000000;stroke:#000000;stroke-width:1.6000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+         d="M 390.84798,371.31968 C 390.67230,371.01421 390.16897,370.87309 389.44281,370.86931 L 380.40026,370.92353 L 380.40026,370.92353 L 381.40039,356.76032 C 381.45531,355.66353 381.19370,354.58394 380.62363,353.61296 L 390.84798,371.31968 z "
+         sodipodi:nodetypes="ccccccc" />
+    </g>
+  </g>
+</svg>
diff --git a/docs/user/images/s5-files.png b/docs/user/images/s5-files.png
new file mode 100644
index 000000000..53cbbf250
--- /dev/null
+++ b/docs/user/images/s5-files.png
diff --git a/docs/user/images/s5-files.svg b/docs/user/images/s5-files.svg
new file mode 100644
index 000000000..a3e644a22
--- /dev/null
+++ b/docs/user/images/s5-files.svg
@@ -0,0 +1,639 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://web.resource.org/cc/"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="595.27559pt"
+   height="841.88976pt"
+   id="svg5904"
+   sodipodi:version="0.32"
+   inkscape:version="0.42"
+   sodipodi:docbase="/Users/david/projects/docutils/s5-branch/docs/user/images"
+   sodipodi:docname="s5-files.svg"
+   inkscape:export-filename="/Users/david/projects/docutils/s5-branch/docs/user/images/s5-files.png"
+   inkscape:export-xdpi="100.00000"
+   inkscape:export-ydpi="100.00000">
+  <defs
+     id="defs5906">
+    <marker
+       inkscape:stockid="Arrow1Mstart"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow1Mstart"
+       style="overflow:visible">
+      <path
+         sodipodi:nodetypes="ccccc"
+         id="path10526"
+         d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none"
+         transform="scale(0.4)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow1Lstart"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow1Lstart"
+       style="overflow:visible">
+      <path
+         sodipodi:nodetypes="ccccc"
+         id="path10529"
+         d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none"
+         transform="scale(0.8)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow2Mend"
+       style="overflow:visible;">
+      <path
+         sodipodi:nodetypes="cccc"
+         id="path10518"
+         style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;"
+         d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+         transform="scale(0.6) rotate(180) translate(-5,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Mstart"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow2Mstart"
+       style="overflow:visible">
+      <path
+         sodipodi:nodetypes="cccc"
+         id="path10509"
+         style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round"
+         d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+         transform="scale(0.6) translate(-5,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Lend"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow2Lend"
+       style="overflow:visible;">
+      <path
+         sodipodi:nodetypes="cccc"
+         id="path10521"
+         style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;"
+         d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+         transform="scale(1.1) rotate(180) translate(-5,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow2Lstart"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow2Lstart"
+       style="overflow:visible">
+      <path
+         sodipodi:nodetypes="cccc"
+         id="path10512"
+         style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round"
+         d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z "
+         transform="scale(1.1) translate(-5,0)" />
+    </marker>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.0050485"
+     inkscape:cx="359.99999"
+     inkscape:cy="345.00000"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     inkscape:window-width="1161"
+     inkscape:window-height="810"
+     inkscape:window-x="51"
+     inkscape:window-y="22"
+     showgrid="true"
+     inkscape:grid-bbox="true"
+     inkscape:grid-points="true"
+     gridspacingx="5.0000000px"
+     gridspacingy="5.0000000px"
+     gridtolerance="2.0000000px" />
+  <metadata
+     id="metadata5909">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     style="display:inline">
+    <g
+       id="g15792">
+      <g
+         transform="translate(-5.000000,-55.00000)"
+         id="g13828"
+         style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round">
+        <g
+           id="g13761"
+           style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round">
+          <path
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000"
+             d="M 451.84175,542.36220 L 490.47866,542.36220"
+             id="path13719" />
+          <path
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000"
+             d="M 515.00000,597.36220 L 491.83836,597.36220"
+             id="path13721" />
+          <path
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000"
+             d="M 515.00000,487.36218 L 491.83836,487.36218"
+             id="path13723" />
+          <path
+             id="path13725"
+             d="M 491.83836,487.36218 L 491.83836,597.36220 L 491.83836,707.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13757"
+             d="M 515.00000,707.36218 L 491.83836,707.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+        </g>
+        <g
+           id="g13695"
+           style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round">
+          <path
+             id="path10755"
+             d="M 451.84175,982.36220 L 490.47866,982.36220"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13691"
+             d="M 515.00000,1037.3622 L 491.83836,1037.3622"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13689"
+             d="M 515.00000,927.36218 L 491.83836,927.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13687"
+             d="M 491.83836,1037.3622 L 491.83836,927.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+        </g>
+        <g
+           id="g13174"
+           style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round">
+          <path
+             id="path9672"
+             d="M 205.00000,762.36217 L 275.47323,762.36217"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13150"
+             d="M 325.12023,762.36218 L 276.91055,762.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13148"
+             d="M 325.12023,872.36218 L 276.91055,872.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13146"
+             d="M 325.12023,982.36218 L 276.91055,982.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13156"
+             d="M 325.12023,542.36218 L 276.91055,542.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13154"
+             d="M 276.91055,982.36218 L 276.91055,542.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:none;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+          <path
+             id="path13144"
+             d="M 325.12023,652.36218 L 276.91055,652.36218"
+             style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" />
+        </g>
+      </g>
+      <g
+         transform="translate(-5.000000,-55.00000)"
+         id="g13805"
+         style="stroke:#000000;stroke-opacity:1.0000000">
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13533"
+           transform="translate(-160.0000,215.0000)">
+          <g
+             id="g13262"
+             transform="translate(522.7639,-102.4046)"
+             style="stroke:#000000;stroke-opacity:1.0000000">
+            <path
+               sodipodi:nodetypes="ccccccccc"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               id="path13264" />
+            <path
+               sodipodi:nodetypes="ccccccc"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               id="path13266" />
+          </g>
+          <text
+             sodipodi:linespacing="100.00000%"
+             id="text9098"
+             y="266.27817"
+             x="748.73212"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="266.27817"
+               x="748.73212"
+               id="tspan9100"
+               sodipodi:role="line">s5-core</tspan><tspan
+               id="tspan9102"
+               y="290.27818"
+               x="748.73212"
+               sodipodi:role="line">.css</tspan></text>
+        </g>
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13541"
+           transform="translate(-160.0000,215.0000)">
+          <g
+             style="stroke:#000000;stroke-opacity:1.0000000"
+             transform="translate(522.7639,7.595400)"
+             id="g13276">
+            <path
+               id="path13278"
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               sodipodi:nodetypes="ccccccccc" />
+            <path
+               id="path13280"
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               sodipodi:nodetypes="ccccccc" />
+          </g>
+          <text
+             sodipodi:linespacing="100.00000%"
+             id="text9104"
+             y="377.05817"
+             x="749.49524"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="377.05817"
+               x="749.49524"
+               id="tspan9106"
+               sodipodi:role="line">framing</tspan><tspan
+               id="tspan9108"
+               y="401.05818"
+               x="749.49524"
+               sodipodi:role="line">.css</tspan></text>
+        </g>
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13549"
+           transform="translate(-160.0000,215.0000)">
+          <g
+             style="stroke:#000000;stroke-opacity:1.0000000"
+             transform="translate(522.7639,117.5954)"
+             id="g13290">
+            <path
+               id="path13292"
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               sodipodi:nodetypes="ccccccccc" />
+            <path
+               id="path13294"
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               sodipodi:nodetypes="ccccccc" />
+          </g>
+          <text
+             transform="scale(1.075185,0.930073)"
+             sodipodi:linespacing="100.00000%"
+             id="text9110"
+             y="522.89044"
+             x="696.86365"
+             style="font-size:25.804459px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="522.89044"
+               x="696.86365"
+               id="tspan9112"
+               sodipodi:role="line">pretty</tspan><tspan
+               id="tspan9114"
+               y="548.69490"
+               x="696.86365"
+               sodipodi:role="line">.css</tspan></text>
+        </g>
+      </g>
+      <g
+         transform="translate(-5.000000,-55.00000)"
+         id="g13701"
+         style="stroke:#000000;stroke-opacity:1.0000000">
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13617"
+           transform="translate(-150.0000,240.0000)">
+          <g
+             id="g13322"
+             transform="translate(512.7639,312.5954)"
+             style="stroke:#000000;stroke-opacity:1.0000000">
+            <path
+               sodipodi:nodetypes="ccccccccc"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               id="path13324" />
+            <path
+               sodipodi:nodetypes="ccccccc"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               id="path13326" />
+          </g>
+          <text
+             sodipodi:linespacing="100.00000%"
+             id="text9122"
+             y="682.05817"
+             x="740.27032"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="682.05817"
+               x="740.27033"
+               id="tspan9124"
+               sodipodi:role="line">iepngfix</tspan><tspan
+               id="tspan9126"
+               y="706.05818"
+               x="740.27032"
+               sodipodi:role="line">.htc</tspan></text>
+        </g>
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13609"
+           transform="translate(-150.0000,240.0000)">
+          <g
+             style="stroke:#000000;stroke-opacity:1.0000000"
+             transform="translate(512.7639,422.5954)"
+             id="g13336">
+            <path
+               id="path13338"
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               sodipodi:nodetypes="ccccccccc" />
+            <path
+               id="path13340"
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               sodipodi:nodetypes="ccccccc" />
+          </g>
+          <text
+             sodipodi:linespacing="100.00000%"
+             id="text9116"
+             y="790.57019"
+             x="739.14758"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="790.57019"
+               x="739.14758"
+               id="tspan9118"
+               sodipodi:role="line">blank</tspan><tspan
+               id="tspan9120"
+               y="814.57020"
+               x="739.14758"
+               sodipodi:role="line">.gif</tspan></text>
+        </g>
+      </g>
+      <g
+         transform="translate(-5.000000,-55.00000)"
+         id="g13768"
+         style="stroke:#000000;stroke-opacity:1.0000000">
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g12998"
+           transform="translate(140.0000,160.0000)">
+          <g
+             id="g12960"
+             transform="translate(32.76392,117.5954)"
+             style="stroke:#000000;stroke-opacity:1.0000000">
+            <path
+               sodipodi:nodetypes="ccccccccc"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               id="path12962" />
+            <path
+               sodipodi:nodetypes="ccccccc"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               id="path12964" />
+          </g>
+          <text
+             sodipodi:linespacing="100.00000%"
+             id="text9080"
+             y="486.96219"
+             x="259.42813"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="486.96219"
+               x="259.42813"
+               id="tspan9082"
+               sodipodi:role="line">outline</tspan><tspan
+               id="tspan9084"
+               y="510.96220"
+               x="259.42813"
+               sodipodi:role="line">.css</tspan></text>
+        </g>
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13006"
+           transform="translate(140.0000,160.0000)">
+          <g
+             id="g12972"
+             transform="translate(32.76392,227.5954)"
+             style="stroke:#000000;stroke-opacity:1.0000000">
+            <path
+               sodipodi:nodetypes="ccccccccc"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               id="path12974" />
+            <path
+               sodipodi:nodetypes="ccccccc"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               id="path12976" />
+          </g>
+          <text
+             xml:space="preserve"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             x="259.34225"
+             y="596.96216"
+             id="text9284"
+             sodipodi:linespacing="100.00000%"><tspan
+               sodipodi:role="line"
+               id="tspan9290"
+               x="259.34226"
+               y="596.96216">print</tspan><tspan
+               sodipodi:role="line"
+               id="tspan9292"
+               x="259.34225"
+               y="620.96217">.css</tspan></text>
+        </g>
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13014"
+           transform="translate(140.0000,160.0000)">
+          <g
+             style="stroke:#000000;stroke-opacity:1.0000000"
+             transform="translate(32.76392,337.5954)"
+             id="g12978">
+            <path
+               id="path12980"
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               sodipodi:nodetypes="ccccccccc" />
+            <path
+               id="path12982"
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               sodipodi:nodetypes="ccccccc" />
+          </g>
+          <text
+             xml:space="preserve"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             x="259.56012"
+             y="706.32617"
+             id="text12043"
+             sodipodi:linespacing="100.00000%"><tspan
+               sodipodi:role="line"
+               id="tspan12045"
+               x="259.56012"
+               y="706.32617">opera</tspan><tspan
+               sodipodi:role="line"
+               x="259.56012"
+               y="730.32618"
+               id="tspan12047">.css</tspan></text>
+        </g>
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13022"
+           transform="translate(140.0000,160.0000)">
+          <g
+             id="g12984"
+             transform="translate(32.76392,447.5954)"
+             style="stroke:#000000;stroke-opacity:1.0000000">
+            <path
+               sodipodi:nodetypes="ccccccccc"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               id="path12986" />
+            <path
+               sodipodi:nodetypes="ccccccc"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               id="path12988" />
+          </g>
+          <text
+             sodipodi:linespacing="100.00000%"
+             id="text9092"
+             y="816.30219"
+             x="259.32312"
+             style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="816.30219"
+               x="259.32312"
+               id="tspan9094"
+               sodipodi:role="line">slides</tspan><tspan
+               id="tspan9096"
+               y="840.30220"
+               x="259.32312"
+               sodipodi:role="line">.js</tspan></text>
+        </g>
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g12990"
+           transform="translate(140.0000,160.0000)">
+          <g
+             style="stroke:#000000;stroke-opacity:1.0000000"
+             transform="translate(32.76392,7.595403)"
+             id="g12886">
+            <path
+               id="path2125"
+               style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+               d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z "
+               sodipodi:nodetypes="ccccccccc" />
+            <path
+               id="path2168"
+               style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+               d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z "
+               sodipodi:nodetypes="ccccccc" />
+          </g>
+          <text
+             transform="scale(1.003177,0.996833)"
+             sodipodi:linespacing="100.00000%"
+             id="text9074"
+             y="378.15045"
+             x="258.4964"
+             style="font-size:24.117754px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+             xml:space="preserve"><tspan
+               y="378.15045"
+               x="258.49640"
+               id="tspan9076"
+               sodipodi:role="line">slides</tspan><tspan
+               id="tspan9078"
+               y="402.26821"
+               x="258.49640"
+               sodipodi:role="line">.css</tspan></text>
+        </g>
+      </g>
+      <g
+         id="g14176">
+        <g
+           style="stroke:#000000;stroke-opacity:1.0000000"
+           id="g13130"
+           transform="translate(0.000000,-54.99999)">
+          <path
+             sodipodi:nodetypes="ccccccccc"
+             d="M 209.99815,696.86669 L 210.00000,852.36217 L 75.000000,852.36217 L 75.000000,672.36217 L 75.000000,672.36217 L 161.90250,672.36347 C 164.47041,672.36479 166.91132,672.97771 169.09117,674.07931 L 208.96319,694.29521 C 209.63463,694.62733 209.96767,695.52913 209.99815,696.86669 z "
+             style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000"
+             id="path12105" />
+          <path
+             id="path12107"
+             style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline"
+             d="M 208.98791,694.31734 C 208.30060,693.96748 207.39771,694.23853 206.38536,694.97620 L 193.92602,704.33788 L 193.92602,704.33788 L 174.73992,678.74312 C 173.22293,676.78417 171.29202,675.17947 169.09117,674.07931 L 208.98791,694.31734 z "
+             sodipodi:nodetypes="ccccccc" />
+        </g>
+        <text
+           xml:space="preserve"
+           style="font-size:36.814487px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad"
+           x="146.13911"
+           y="695.62231"
+           id="text9058"
+           sodipodi:linespacing="100.00000%"
+           transform="scale(0.997872,1.002133)"><tspan
+             sodipodi:role="line"
+             x="146.13911"
+             y="695.62231"
+             id="tspan9128"><tspan
+   id="tspan14172"
+   style="font-size:36.814487px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:99.999976%;writing-mode:lr-tb;text-anchor:middle;stroke:#000000;stroke-width:0.0000000;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000;font-family:Myriad" />*.html</tspan><tspan
+             sodipodi:role="line"
+             x="146.13912"
+             y="732.43680"
+             id="tspan14174">output</tspan></text>
+      </g>
+    </g>
+  </g>
+  <g
+     inkscape:groupmode="layer"
+     id="layer2"
+     inkscape:label="2"
+     style="display:inline" />
+</svg>
diff --git a/docs/user/images/small-black.png b/docs/user/images/small-black.png
new file mode 100644
index 000000000..f8d80d387
--- /dev/null
+++ b/docs/user/images/small-black.png
diff --git a/docs/user/images/small-white.png b/docs/user/images/small-white.png
new file mode 100644
index 000000000..65f96895d
--- /dev/null
+++ b/docs/user/images/small-white.png
diff --git a/docs/user/latex.txt b/docs/user/latex.txt
new file mode 100644
index 000000000..ce8447692
--- /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, ...).
+
+If 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/links.txt b/docs/user/links.txt
new file mode 100644
index 000000000..3bb2aaa70
--- /dev/null
+++ b/docs/user/links.txt
@@ -0,0 +1,137 @@
+=====================
+ Docutils_ Link List
+=====================
+
+:Author: Felix Wiemann
+:Contact: Felix.Wiemann@ososo.de
+:Revision: $Revision$
+:Date: $Date$
+:Copyright: This document has been placed in the public domain.
+
+.. title:: Docutils Links
+
+.. contents::
+
+This document contains links users of Docutils and reStructuredText
+may find useful, listed in no particular order.  Many of the project
+listed here are hosted in the `Docutils Sandbox`_.  If you have
+something to publish, you can get write access, too!
+
+The most current version of this link list can always be found at
+http://docutils.sourceforge.net/docs/user/links.html.
+
+
+Users
+-----
+
+This section contains links which are interesting for all users of
+Docutils.  All projects listed here are usable by end users in some
+way, however please do not expect all of them to run straight out of
+the box.
+
+* For Wikis, please see the `FAQ entry about Wikis`_.
+
+* For Blogs (Weblogs), please see the `FAQ entry about Blogs`_.
+
+* Alberto Berti is developing an `OpenDocument writer`_.
+
+* xml2rst_, an XSLT stylesheet written by Stefan Merten, converts XML
+  dumps of the document tree (e.g. created with rst2xml.py) back to
+  reStructuredText.
+
+* xhtml2rest_, written by Antonios Christofides, is a simple utility
+  to convert XHTML to reStructuredText.
+
+* rst2ht_, by Oliver Rutherfurd, converts reStructuredText to an .ht
+  template, for use with ht2html_.
+
+* htmlnav_, by Gunnar Schwant, is an HTML writer which supports
+  navigation bars.
+
+* rst2chm_, written by Oliver Rutherfurd, generates Microsoft HTML
+  Help files from reStructuredText files.
+
+* rest2web_, by Michael Foord, is a tool for creating web sites with
+  reStructuredText.
+
+* ZReST_, by Richard Jones, is a "ReStructuredText Document for Zope"
+  application that is complete and ready to install.
+
+* The Docutils interface to PythonPoint_, also by Richard Jones,
+  produces PDF presentations using ReportLabs.
+
+* Engelbert Gruber has begun a `ManPage Writer`_.
+
+* Oliver Rutherfurd has begun a `DocBook Writer`_.
+
+* Gunnar Schwant's DocFactory_ is a wxPython GUI application for
+  Docutils.
+
+* Patrick O'Brien has taken over the `OpenOffice.org Writer`_.
+
+* Bill Bumgarner has written a `simple HTML writer`_ that doesn't rely
+  on CSS (stylesheets).
+
+* Beni Cherniavsky has written a generic `preprocessing module`_ for
+  roles and/or directives and built preprocessors for TeX math for
+  both LaTeX and HTML output on top of it.
+
+* Beni Cherniavsky maintains a Makefile_ for driving Docutils, hoping
+  to handle everything one might do with Docutils.
+
+
+API Developers
+--------------
+
+This section contains links which are primarily interesting for
+developers who use the Docutils API from within their own
+applications.
+
+* Nabu_, written by Martin Blais, is a publishing system which
+  extracts information from reStructuredText documents and stores it
+  in a database.  Python knowledge is required to write extractor
+  functions (see `Writing an Extractor`_) and to retrieve the data
+  from the database again.
+
+* There is a `pickle writer`_, written by Martin Blais.
+
+
+Core Developers
+---------------
+
+Links primarily interesting for developers who work with the Docutils
+code base.
+
+* PySource_, by Tony Ibbs, is an experimental Python source Reader.
+  There is some related code in David Goodger's sandbox
+  (pysource_reader_) and a `Python Source Reader`_ document.
+
+
+.. _Docutils: http://docutils.sourceforge.net/
+.. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
+.. _FAQ entry about Blogs: http://docutils.sf.net/FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
+.. _OpenDocument writer: http://thread.gmane.org/gmane.text.docutils.devel/3388
+.. _xml2rst: http://www.merten-home.de/FreeSoftware/xml2rst/index.html
+.. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html
+.. _ht2html: http://ht2html.sourceforge.net/
+.. _htmlnav: http://docutils.sf.net/sandbox/gschwant/htmlnav/
+.. _xhtml2rest: http://docutils.sf.net/sandbox/fwiemann/xhtml2rest/
+.. _rst2chm: http://www.rutherfurd.net/software/rst2chm/
+.. _rest2web: http://www.voidspace.org.uk/python/rest2web/
+.. _Docutils Sandbox: http://docutils.sf.net/sandbox/README.html
+.. _ZReST: http://docutils.sf.net/sandbox/richard/ZReST/
+.. _PySource: http://docutils.sf.net/sandbox/tibs/pysource/
+.. _pysource_reader: http://docutils.sf.net/sandbox/davidg/pysource_reader/
+.. _Python Source Reader: http://docutils.sf.net/docs/dev/pysource.html
+.. _PythonPoint: http://docutils.sf.net/sandbox/richard/pythonpoint/
+.. _Manpage Writer: http://docutils.sf.net/sandbox/grubert/man/
+.. _ReportLabs/PDF Writer: http://docutils.sf.net/sandbox/dreamcatcher/rlpdf/
+.. _DocBook Writer: http://docutils.sf.net/sandbox/oliverr/docbook/
+.. _DocFactory: http://docutils.sf.net/sandbox/gschwant/docfactory/doc/
+.. _OpenOffice.org Writer: http://docutils.sf.net/sandbox/pobrien/OpenOffice/
+.. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/
+.. _preprocessing module: http://docutils.sf.net/sandbox/cben/rolehack/
+.. _Makefile: http://docutils.sf.net/sandbox/cben/make/
+.. _Nabu: http://furius.ca/nabu/
+.. _Writing an Extractor: http://furius.ca/nabu/doc/nabu-extractor.html
+.. _pickle writer: http://docutils.sf.net/sandbox/blais/pickle_writer/
diff --git a/docs/user/mailing-lists.txt b/docs/user/mailing-lists.txt
new file mode 100644
index 000000000..8137e29e7
--- /dev/null
+++ b/docs/user/mailing-lists.txt
@@ -0,0 +1,111 @@
+=========================
+ Docutils_ Mailing Lists
+=========================
+
+:Author: Felix Wiemann
+:Contact: Felix.Wiemann@ososo.de
+:Revision: $Revision$
+:Date: $Date$
+:Copyright: This document has been placed in the public domain.
+
+
+All discussion about Docutils takes place on mailing lists.
+
+There are four different lists with traffic related to Docutils.  If
+unsure, use the **Docutils-users** mailing list:
+
+
+Docutils-users
+--------------
+
+The Docutils-users mailing list is a place to discuss any issues
+related to the usage of Docutils and reStructuredText.  (Please be
+sure to check the FAQ_ first.)
+
+There are three possibilities to **read and post** messages on the
+mailing lists; use the one you feel most comfortable with.
+
+* Using an `email subscription`__.  This is the traditional way; you
+  will receive all messages sent to the mailing list via email.
+
+  __ http://lists.sourceforge.net/lists/listinfo/docutils-users
+
+* Using Gmane's `web interface`__.  To post a message, click "post" or
+  "followup" in the drop-down menu on the right.
+
+  __ http://news.gmane.org/gmane.text.docutils.user
+
+* If you prefer using a newsreader, you can also use Gmane's `NNTP
+  interface`__ (gmane.text.docutils.user on news.gmane.org).
+
+  __ nntp://news.gmane.org/gmane.text.docutils.user.
+
+**If you do not wish to subscribe,** you can also just send an email
+message to Docutils-users@lists.sourceforge.net.  Please note in your
+message that you are not subscribed (to make sure that you receive
+copies [CCs] of any replies).
+
+The first time you post a message without being subscribed (also when
+posting via Gmane), you will receive an automatic response with the
+subject "Your message to Docutils-users awaits moderator approval";
+this is done to prevent spam to the mailing lists.  Your message will
+usually be approved within a few hours.  To avoid duplicates, please
+do not resend your message using a different email address.  After
+your first message has been approved, your email address will be added
+to the whitelist and future messages will be posted to the mailing
+list without moderation.
+
+
+Doc-SIG
+-------
+
+The "Python Documentation Special Interest Group" (Doc-SIG) mailing
+list is occasionally used to discuss the usage of Docutils for Python
+documentation.
+
+This mailing list can be accessed via `email subscription`__, web__ or
+news__ (gmane.comp.python.documentation) as well.  You must be
+subscribed in order to post messages to this mailing list.
+
+__ http://mail.python.org/mailman/listinfo/doc-sig
+__ http://news.gmane.org/gmane.comp.python.documentation
+__ nntp://news.gmane.org/gmane.comp.python.documentation
+
+
+Docutils-develop
+----------------
+
+Discussions about developing and extending Docutils take place on the
+Docutils-develop mailing list.
+
+You can access this list via `email subscription`__, web__ or news__
+(gmane.text.docutils.devel); the posting address is
+Docutils-develop@lists.sourceforge.net.
+
+__ http://lists.sourceforge.net/lists/listinfo/docutils-develop
+__ http://news.gmane.org/gmane.text.docutils.devel
+__ nntp://news.gmane.org/gmane.text.docutils.devel
+
+
+Docutils-checkins
+-----------------
+
+All check-ins to the `Subversion repository`_ cause a "check-in email"
+to the Docutils-checkins list.  In order to stay informed about
+current development, developers are advised to monitor this mailing
+list.
+
+This mailing list is for reading only; please direct any discussion
+about the check-ins to Docutils-develop.  (For your convenience, the
+Reply-To header of all check-in emails points to Docutils-develop.)
+
+This mailing list is accessible via `email subscription`__, web__ or
+news__ (gmane.text.docutils.cvs) as well.
+
+__ http://lists.sourceforge.net/lists/listinfo/docutils-checkins
+__ http://news.gmane.org/gmane.text.docutils.cvs
+__ nntp://news.gmane.org/gmane.text.docutils.cvs
+
+.. _Subversion repository: http://docutils.sf.net/docs/dev/repository.html
+.. _Docutils: http://docutils.sourceforge.net/
+.. _FAQ: http://docutils.sourceforge.net/FAQ.html
diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt
new file mode 100644
index 000000000..dfea5bcb7
--- /dev/null
+++ b/docs/user/rst/cheatsheet.txt
@@ -0,0 +1,125 @@
+=====================================================
+ 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]
+container         Generic block-level container element [0.3.10]
+table             Create a titled table [0.3.1]
+list-table        Create a table from a uniform two-level bullet list [0.3.8]
+csv-table         Create a table from CSV data (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
+date              Generates today's date; for substitution defs
+class             Set a "class" attribute on the next element
+role              Create a custom interpreted text role [0.3.2]
+default-role      Set the default interpreted text role [0.3.10]
+title             Set the metadata document title [0.3.10]
+================  ============================================================
+
+Interpreted Text Role Quick Reference
+=====================================
+See <http://docutils.sf.net/docs/ref/rst/roles.html> for full info.
+
+================  ============================================================
+Role Name         Description
+================  ============================================================
+emphasis          Equivalent to *emphasis*
+literal           Equivalent to ``literal`` but processes backslash escapes
+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..7a0abd033
--- /dev/null
+++ b/docs/user/rst/demo.txt
@@ -0,0 +1,552 @@
+.. This is a comment. Note how any initial comments are moved by
+   transforms to after the document title, subtitle, and docinfo.
+
+================================
+ reStructuredText Demonstration
+================================
+
+.. Above is the document title, and below is the subtitle.
+   They are transformed from section titles after parsing.
+
+--------------------------------
+ Examples of Syntax Constructs
+--------------------------------
+
+.. bibliographic fields (which also require a transform):
+
+:Author: David Goodger
+:Address: 123 Example Street
+          Example, EX  Canada
+          A1B 2C3
+:Contact: 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.
+
+|*** Expect 6 errors (including this one). ***|
+
+There should be six messages in the following, auto-generated
+section, "Docutils System Messages":
+
+.. section should be added by Docutils automatically
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..604cfe6bc
--- /dev/null
+++ b/docs/user/rst/quickref.html
@@ -0,0 +1,1352 @@
+<!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="#hyperlink-targets">Hyperlink Targets</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">Hyperlink Targets</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">Hyperlink Targets</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">Hyperlink Targets</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 rowspan="2">
+        <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>External hyperlinks, like
+          <a href="http://www.python.org/">Python</a>.
+        </table>
+    <tr valign="top">
+      <td>
+        <table width="100%">
+          <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.  You can force usage of the call-out form by
+      using the
+      "<a href="../../ref/rst/directives.html#target-notes">target-notes</a>"
+      directive.
+
+    <p>reStructuredText also provides for <b>embedded URIs</b> (<a
+      href="../../ref/rst/restructuredtext.html#embedded-uris">details</a>),
+      a convenience at the expense of readability.  A hyperlink
+      reference may directly embed a target URI inline, within angle
+      brackets.  The following is exactly equivalent to the example above:
+
+    <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 rowspan="2">
+        <samp>External&nbsp;hyperlinks,&nbsp;like&nbsp;`Python
+<br>&lt;http://www.python.org/&gt;`_.</samp>
+      <td>External hyperlinks, like
+          <a href="http://www.python.org/">Python</a>.
+    </table>
+
+    <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 rowspan="2"><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.
+        </table>
+    <tr valign="top">
+      <td>
+        <table width="100%">
+          <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..735dcf512
--- /dev/null
+++ b/docs/user/rst/quickstart.txt
@@ -0,0 +1,387 @@
+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.
+
+.. [#] If that relative link doesn't work, try the master document:
+   http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.
+
+.. _reStructuredText Markup Specification:
+   ../../ref/rst/restructuredtext.html
+.. _Docutils-users: ../mailing-lists.html#docutils-users
+.. _Docutils project web site: http://docutils.sourceforge.net/
diff --git a/docs/user/slide-shows.txt b/docs/user/slide-shows.txt
new file mode 100644
index 000000000..6732f4f44
--- /dev/null
+++ b/docs/user/slide-shows.txt
@@ -0,0 +1,1004 @@
+.. include:: <s5defs.txt>
+
+=================================
+ Easy Slide Shows With reST & S5
+=================================
+
+:Authors: David Goodger & Chris Liechti
+:Date:    $Date$
+
+.. This document has been placed in the public domain.
+
+.. container:: handout
+
+   How to create quick, good-looking presentation slide shows with
+   Docutils_/reStructuredText_ and S5_.
+
+   This document serves both as a user manual and as a usage example
+   of the s5_html.py writer and the rst2s5.py front end.
+
+   To view this document as a slide show see
+   http://docutils.sf.net/docs/user/slide-shows.s5.html (or `your
+   local copy <slide-shows.s5.html>`__).
+
+.. contents::
+   :class: handout
+
+.. class:: tiny
+
+* S5 themes are designed for full-screen display areas with a 4:3
+  aspect ratio.  If the slide text doesn't fit in your browser window,
+  try decreasing the text size.
+
+* Use the space bar to advance, Page Up/Down & arrow keys to navigate.
+
+* Best viewed in Firefox_, Safari, and Konqueror.  Click the "|mode|"
+  button to switch between presentation & handout/outline modes.  Hit
+  the "C" key to display the navigation controls, or mouse over the
+  lower right-hand corner.
+
+* Functionality is limited in Opera.  Switch to full-screen mode (F11
+  key) to activate Opera Show.
+
+* S5 works in Internet Explorer, but it may look ugly.
+
+.. container:: handout
+
+   The first slide of a presentation consists of all visible text up
+   to the first section title.  The document title is also added to
+   the footer of all slides.
+
+   The "footer" directive is used to specify part of the slide footer
+   text.  It is currently limited to one short line (one paragraph).
+
+   There is no support for the "header" directive in the themes
+   included with Docutils.
+
+.. _Docutils: http://docutils.sourceforge.net/
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _S5: http://meyerweb.com/eric/tools/s5/
+.. _Firefox: http://www.mozilla.com/firefox/
+.. |bullet| unicode:: U+02022
+.. |mode| unicode:: U+00D8 .. capital o with stroke
+
+.. footer:: Location |bullet| Date
+
+
+Introduction
+============
+
+.. class:: handout
+
+   ``rst2s5.py`` is a Docutils_ front end that outputs HTML for use
+   with S5_, a "Simple Standards-based Slide Show System" by Eric
+   Meyer.
+
+.. topic:: Installation
+   :class: handout
+
+   Prerequisites: Python and the Docutils_ package have to be
+   installed.  See the `Docutils README`__ file for installation
+   instructions.
+
+   __ http://docutils.sourceforge.net/README.html
+
+* reStructuredText
+
+  .. class:: handout
+
+  Uses normal reStructuredText as input.
+
+* One section per slide
+
+  .. class:: handout
+
+  Each first-level section is converted into a single slide.
+
+* XHTML output
+
+  .. container:: handout
+
+     Presentations can be viewed using most modern graphical web
+     browsers.  The browser must support CSS, JavaScript, and XHTML.
+     S5 even works with IE!
+
+     S5 was designed to add the functionality of the `Opera Show`_
+     standard (without Opera Show's limitations) to non-Opera
+     browsers.  Unfortunately, most of S5's CSS and JavaScript
+     extensions don't function in the Opera browser.
+
+  .. _Opera Show: http://www.opera.com/support/tutorials/operashow/
+
+* Themes
+
+  .. class:: handout
+
+  A variety of themes are available.  See `Example Themes`_, below.
+
+* ``rst2s5.py``
+
+  .. class:: handout
+
+  The front-end tool to generate S5 slide shows.
+
+.. topic:: Keyboard Controls
+   :class: handout
+
+   The following apply in any supporting browser besides Opera, which
+   uses the default Opera Show controls instead.
+
+   .. list-table::
+      :header-rows: 1
+
+      * - Action
+        - Key(s)
+      * - Go to the next slide
+        - * [Space bar]
+          * [Return]
+          * [Enter]
+          * [Right arrow]
+          * [Down arrow]
+          * [Page down]
+          * Click the left mouse button outside of the control area,
+            Flash object, or movie
+      * - Go to the previous slide
+        - * [Left arrow]
+          * [Up arrow]
+          * [Page up]
+      * - Go to the title (first) slide
+        - [Home]
+      * - Go to the last slide
+        - [End]
+      * - Jump directly to a slide
+        - Type the slide number, then hit [Return] or [Enter]
+      * - Skip forward *n* slides
+        - Type the number of slides to skip, then hit any "go to next"
+          key (except [Return] or [Enter])
+      * - Skip backward *n* slides
+        - Type the number of slides to skip, then hit any "go to
+          previous" key
+      * - Switch between slideshow and outline view
+        - * [T]
+          * Click the |mode| button
+      * - Show/hide slide controls
+        - * [C]
+          * Move the mouse pointer over the control area
+
+   Further details of the S5 user interface can be found at `Eric
+   Meyer's S5 page`__.
+
+   __ S5_
+
+
+Features (1)
+============
+
+.. container:: handout
+
+   The S5/HTML Writer supports all the standard Docutils HTML
+   features.  S5 has been released to the Public Domain.
+
+S5-specific features:
+
+.. class:: incremental
+
+* The document title is duplicated on each slide in the S5 footer.
+
+* The ``footer`` directive may be used to define additional text in
+  the S5 footer.
+
+  .. container:: handout
+
+     But it is limited to one line of text.
+
+     This is useful for information such as the date of the
+     presentation and/or the location.  The field in the footer is
+     left blank if no ``footer`` directive is used.
+
+     Example::
+
+         .. footer:: Location - Date
+
+     There is also a progress indicator (slide counter) in the footer
+     that can be enabled.  It's disabled by default.
+
+* Incremental display.
+
+  .. class:: handout
+
+  An "incremental" class can be assigned to lists and other elements
+  to get one-item-at-a-time behavior (like this list).  Incremental
+  display does not work in the Opera browser.
+
+* Text auto-scaling.
+
+  .. class:: handout
+
+  The text size adjusts relative to the size of your browser window
+  automatically.  You may need to reload the document after resizing
+  the window.  The browser and platform affect the font used; be sure
+  to test the slide show on the presentation system.
+
+
+Features (2): Handouts
+======================
+
+.. container:: handout
+
+   The contents of any element with a "class" attribute value of
+   "handout" are hidden in the slide presentation, and are only
+   visible when the presentation is printed, or viewed in outline
+   mode.  "Handout"-class elements can appear anywhere in the text, as
+   often as needed.
+
+   This means that the slides and extra handout material can be
+   combined in one document.  The handout can be printed directly from
+   the browser, and it will contain more than just silly framed
+   slides.  This can be used to provide more detailed information, or
+   for speaker's notes.
+
+.. class:: incremental
+
+* Use the "class" directive::
+
+      .. class:: handout
+
+  .. container:: handout
+
+     The ``.. class:: handout`` directive can be used to tag
+     individual paragraphs and other elements.  The "class" directive
+     applies to the first element immediately following::
+
+         .. class:: handout
+
+         This paragraph will get a
+         ``class="handout"`` attribute.
+
+         This paragraph will not be affected.
+
+     It also applies to multiple elements in the directive content::
+
+         .. class:: handout
+
+            These paragraphs are the content
+            of the "class" directive.  And as such...
+
+            Both paragraphs will *individually* receive
+            ``class="handout"`` attributes.
+
+* Use the "container" directive::
+
+      .. container:: handout
+
+  .. container:: handout
+
+     Arbitrary handout blocks can be created using the ``container``
+     directive.  The content is treated as one.
+
+* Use the "class" option of directives that support it::
+
+      .. topic:: Extra Material For Handouts
+         :class: handout
+
+.. container:: handout
+
+   The following directives support "class" options:
+
+   * all admonition directives ("admonition", "note", "hint", etc.)
+   * "image" & "figure"
+   * "topic"
+   * "sidebar"
+   * "line-block"
+   * "parsed-literal"
+   * "rubric"
+   * "compound"
+   * "table", "csv-table", & "list-table"
+   * "target-notes" (more about that below)
+   * "role" (pre-defined; more below)
+
+   Handout contents are also visible on the screen if the S5 view mode
+   is toggled from "slide show" to "outline" mode.
+
+
+Caveats
+=======
+
+.. class:: incremental
+
+1. Some Docutils features are not supported by some themes.
+
+   .. container:: handout
+
+      For example, header rendering is not supported by the themes
+      supplied with Docutils.
+
+      The "header" directive is used to set header text.  S5
+      automatically inserts section/slide titles into the "header"
+      area of a slide.  If both Docutils headers and S5 headers (slide
+      titles) exist simultaneously, they interfere with each other.
+
+2. Care must be taken with the "contents" directive.
+
+   .. container:: handout
+
+      The ``--no-toc-backlinks`` option is the default for the S5/HTML
+      writer (``toc_backlinks=0`` setting).  Other values for this
+      setting will change the CSS class of headings such that they
+      won't show up correctly in the slide show.
+
+      Use the ``:class: handout`` option on the "contents" directive
+      to limit the table of contents to the handout/outline mode
+      only::
+
+          .. contents::
+             :class: handout
+
+
+.. class:: incremental
+
+3. Subsections ...
+------------------
+
+... may be used, sparingly.
+
+.. container:: handout
+
+   Only first-level sections become slides.  Not many levels of
+   subsections can fit on a slide.
+
+   Subsections (of any level) work normally in handouts though.  Add
+   "``.. class:: handout``" before a subsection (or sub-subsection, or
+   ...), and the entire subsection will only appear in the handout.
+
+
+Generating a Slide Show (1)
+===========================
+
+.. class:: incremental
+
+1. Open a console (terminal, command shell) and go to the folder
+   containing your file, ``slides.txt``.
+
+2. Run the command::
+
+       rst2s5.py slides.txt slides.html
+
+3. Specify an S5 theme with the ``--theme`` option.
+
+   .. class:: handout
+
+   Docutils will copy the S5 theme files into a ``ui/<theme>`` folder
+   beside the output HTML file.  A slide show can also link to an
+   existing theme using the ``--theme-url`` option.
+
+
+Generating a Slide Show (2)
+===========================
+
+.. class:: incremental
+
+4. Include a copy of any linked stylesheet.
+
+   .. class:: handout
+
+   The default Docutils stylesheet, ``html4css1.css``, will normally
+   be embedded in the output HTML.  If you choose to link to a
+   stylesheet instead of embedding, you must include a copy (suggested
+   location: in the ``ui/`` directory).
+
+5. Open ``slides.html`` in a web browser.
+
+6. Expand the browser window to full-screen mode, and speak.
+
+   .. class:: handout
+
+   The `Web Developer`__ extension for Firefox is very useful.  With
+   it, you can resize your browser window to the exact dimensions of
+   the projector you'll be using, so you can test beforehand.  There
+   are many other useful features as well.
+
+   __ http://chrispederick.com/work/webdeveloper/
+
+7. Profit!
+
+
+Examples (1)
+============
+
+.. sidebar:: Hint
+
+   Admonitions, tables, sidebars, and other elements can be used in
+   on-screen presentations in handouts.  Images too!
+
+   .. image:: images/happy_monkey.png
+       :alt: sample image
+
+=====  =====  ======
+  A      B    A or B
+=====  =====  ======
+False  False  False
+True   False  True
+False  True   True
+True   True   True
+=====  =====  ======
+
+
+Examples (2): Incremental Text
+==============================
+
+.. class:: incremental
+
+   Paragraphs can be displayed one at a time...
+
+   .. container::
+
+      ... or a bunch at a time.
+
+      This second paragraph is displayed together with the previous
+      one by grouping them with the "container" directive.
+
+`We can also display` `one` `word` `at` `a` `time,`
+`or a phrase` `at a time,`
+`or even` `o`\ `n`\ `e` `l`\ `e`\ `t`\ `t`\ `e`\ `r` `at a time!`
+
+`(But the markup ain't pretty.)`
+
+
+Examples (3): Incr. Graphics
+============================
+
+Let's play... Rock, Scissors, Paper
+
+.. container:: animation
+
+   .. image:: images/rsp-empty.png
+      :class: hidden slide-display
+
+   .. class:: incremental hidden slide-display
+
+      .. image:: images/rsp-objects.png
+      .. image:: images/rsp-cuts.png
+      .. image:: images/rsp-covers.png
+      .. image:: images/rsp-breaks.png
+
+   .. image:: images/rsp-all.png
+      :class: incremental
+
+
+Themes
+======
+
+.. class:: incremental
+
+* Several themes are available, and they're easy to adapt.
+
+  .. container:: handout
+
+     Themes from the `S5 tutorial`__ can be used.  These themes are in
+     the public domain and may be redistributed freely.
+
+     __ http://meyerweb.com/eric/tools/s5/s5blank.zip
+
+     Sites with other S5 themes:
+
+     * http://meyerweb.com/eric/tools/s5/themes/
+     * http://mozilla.wikicities.com/wiki/Firefox_S5:Designs
+     * http://lachy.id.au/dev/mozilla/firefox/s5/
+
+     S5 is becoming more popular every day.  Do a web search for "S5
+     theme" and you're bound to find plenty of choices.
+
+* "``--theme``" option.
+
+  .. container:: handout
+
+     The theme can be specified with the "``--theme``" command-line
+     option.
+
+     Example::
+
+         rst2s5 --theme big-black slides.txt slides.html
+
+     The default theme is "default".
+
+* "``theme``" setting.
+
+  .. class:: handout
+
+  You can set the theme with the "``theme``" configuration file
+  setting.
+
+* Copied to ``./ui/<theme>/``.
+
+  .. class:: handout
+
+  Themes are copied into a ``ui/<theme>`` folder inside the folder
+  containing the presentation.
+
+* Link with "``--theme-url``" option.
+
+  .. class:: handout
+
+  Link to a theme on the same or another web site, using the
+  "``--theme-url``" option or "``theme_url``" configuration file
+  setting.
+
+
+Example Themes
+==============
+
+.. class:: handout
+
+   The default theme, "default", is a simplified version of S5's
+   default theme.  It accommodates up to 13 lines of text.
+
+.. class:: center
+
+   "default"
+
+   .. image:: images/default.png
+      :align: center
+
+
+Example Themes: Small Text
+==========================
+
+.. class:: handout
+
+   The "small-white" and "small-black" themes are simplifications of
+   the default theme (**small** black text on a **white** background,
+   and **small** black text on a **white** background, respectively).
+   They each accommodate up to 15 lines of text.
+
+.. list-table::
+   :class: borderless
+
+   * - "small-white"
+
+       .. image:: images/small-white.png
+
+     - "small-black"
+
+       .. image:: images/small-black.png
+
+
+Example Themes: Large Text
+==========================
+
+.. class:: handout
+
+   The "big-white" and "big-black" themes feature very large, bold
+   text, with no footers.  Only five short lines fit in a slide.
+
+.. list-table::
+   :class: borderless
+
+   * - "big-white"
+
+       .. image:: images/big-white.png
+
+     - "big-black"
+
+       .. image:: images/big-black.png
+
+
+Example Themes: Medium Text
+===========================
+
+.. class:: handout
+
+   The "medium-white" and "medium-black" themes feature medium-sized
+   text.  Up to 8 lines of text are accommodated.
+
+.. list-table::
+   :class: borderless
+
+   * - "medium-white"
+
+       .. image:: images/medium-white.png
+
+     - "medium-black"
+
+       .. image:: images/medium-black.png
+
+
+S5 Theme Files
+==============
+
+An S5 theme consists of a directory containing several files --
+stylesheets, JavaScript, and graphics:
+
+.. image:: images/s5-files.png
+   :align: center
+
+.. container:: handout
+
+   The generated HTML contains the entire slide show text.  It also
+   contains links to the following files:
+
+   * slides.css simply contains import links to:
+
+     - s5-core.css: Default styles critical to the proper functioning
+       of the slide show; don't touch this!
+
+     - framing.css: Sets the basic layout of slide components (header,
+       footer, controls, etc.  This file is the often edited.
+
+     - pretty.css: Presentation styles that give the slide show a
+       unique look and feel.  This is the file that you're most likely
+       to edit for a custom theme.  You can make a whole new theme
+       just by editing this file, and not touching the others.
+
+   * outline.css: Styles for outline mode.
+
+   * print.css: Styles for printing; hides most layout elements, and
+     may display others.
+
+   * opera.css: Styles necessary for the proper functioning of S5 in
+     Opera Show.
+
+   * slides.js: the JavaScript that drives the dynamic side of the
+     slide show (actions and navigation controls).  It automatically
+     IDs the slides when the document loads, builds the navigation
+     menu, handles the hiding and showing of slides, and so on.  The
+     code also manages the fallback to Opera Show if you're using
+     the Opera web browser.
+
+     Two files are included to support PNG transparency (alpha
+     channels) in Internet Explorer:
+
+     - iepngfix.htc
+     - blank.gif
+
+
+Making a Custom Theme
+=====================
+
+.. class:: incremental
+
+1. Run "``rst2s5.py --theme <base-theme> <doc>.txt <doc>.html``".
+
+   .. class:: handout
+
+   This initializes the ``ui`` directory with the base theme files.
+
+2. Copy ``ui/<base-theme>`` to ``ui/<new-theme>``.
+
+3. Edit the styles.
+
+   .. class:: handout
+
+   Start with ``pretty.css``; edit ``framing.css`` if you need to make
+   layout changes.
+
+4. Run "``rst2s5.py --theme <new-theme> <doc>.txt <doc>.html``".
+
+   .. class:: handout
+
+   Open your ``<doc>.html`` in a browser to test the new theme.
+
+5. Rinse & repeat.
+
+   .. class:: handout
+
+   Repeat from step 3 until you're satisfied.
+
+.. TODO: What to do next:
+
+   * add a ``__base__`` file
+   * create a personal reusable theme (plugin)
+   * submit the new theme to Docutils
+
+  ``docutils/writers/s5_html/themes/<theme>``
+
+.. container:: handout
+
+   Resources:
+
+   * W3C's `Learning CSS <http://www.w3.org/Style/CSS/learning>`__
+
+   * `Creating An S5 Theme <http://home.cogeco.ca/~ve3ll/s5themes.htm>`__
+
+   * A short tutorial on how to create themes (in German):
+     `Eigenes Theme erstellen <http://yatil.de/s5/dokumentation/9/>`__
+
+
+Classes: Incremental (1)
+========================
+
+.. class:: handout
+
+   Several "class" attribute values have built-in support in the
+   themes supplied with Docutils.
+
+.. class:: incremental
+
+   As described earlier,
+
+   * ``.. class:: incremental``
+
+   * ``.. container:: incremental``
+
+   * ::
+
+         .. sidebar:: title
+            :class: incremental
+
+
+Classes: Incremental (2)
+========================
+
+The "incremental" interpreted text role is also supported:
+
+.. class:: incremental
+
+   ::
+
+       :incremental:`This will appear first,` `and
+       this will appear second.`:incremental:
+
+   Requires "``.. include:: <s5defs.txt>``".
+
+.. container:: handout
+
+   As you can see, this markup is not very convenient.
+
+.. class:: incremental
+
+   | But ``s5defs.txt`` includes this useful definition:
+   | "``.. default-role:: incremental``".  So:
+
+   ::
+
+       `This` `is` `all` `we` `need`
+
+`This` `is` `all` `we` `need` `to mark up incremental text.`
+
+
+Classes: Incremental (3)
+========================
+
+.. class:: small
+
+::
+
+    .. container:: animation
+
+       .. image:: images/empty.png
+          :class: hidden slide-display
+
+       .. class:: incremental hidden slide-display
+
+          .. image:: images/1.png
+          .. image:: images/2.png
+
+       .. image:: images/3.png
+          :class: incremental
+
+.. container:: handout
+
+   This is how the example works.
+
+   The animation effects are caused by placing successive images at
+   the same location, laying each image over the last.  For best
+   results, all images should be the same size, and the positions of
+   image elements should be consistent.  Use image transparency (alpha
+   channels) to get overlay effects.
+
+   Absolute positioning is used, which means that the images take up
+   no space in the flow.  If you want text to follow the images, you
+   have to specify the total size of the container via a style.
+   Otherwise, the images and any following text will overlap.
+
+   These class values do the work:
+
+   animation
+       This wraps the container with styles that position the images
+       absolutely, overlaying them over each other.  Only useful on a
+       container.
+
+   hidden
+       Unless overridden (by "slide-display", for example), these
+       elements will not be displayed.  Only the last image will be
+       displayed in handout mode, when print, or when processed to
+       ordinary HTML, because it does *not* carry a "hidden" class.
+
+   slide-display
+       In conjunction with "hidden", these elements will only appear
+       on the slide, preventing clutter in the handout.
+
+   incremental
+       The second and subsequent images will appear one at a time.
+       The first image will already be present when the slide is
+       displayed, because it does *not* carry an "incremental" class.
+
+
+Classes: Text Size
+==================
+
+.. class:: incremental
+
+   * :tiny:`tiny` (class & role name: "tiny", e.g. "``:tiny:`text```")
+   * :small:`small` ("small")
+   * normal (unstyled)
+   * :big:`big` ("big")
+   * :huge:`huge` ("huge")
+
+   Requires "``.. include:: <s5defs.txt>``".
+
+
+Classes: Alignment
+==================
+
+.. class:: incremental
+
+   .. class:: left
+
+   Left (class name: "left")
+
+   .. class:: center
+
+   Center ("center" & "centre")
+
+   .. class:: right
+
+   Right ("right")
+
+.. class:: handout
+
+   These classes apply to block-level elements only.  They cannot be
+   used for inline text (i.e., they're not interpreted text roles).
+
+.. class:: incremental
+
+   Example::
+
+       .. class:: center
+
+       Text to be centered.
+
+
+Classes: Text Colours
+=====================
+
+:black:`black` [black], :gray:`gray`, :silver:`silver`, :white:`white`
+[white], :maroon:`maroon`, :red:`red`, :magenta:`magenta`,
+:fuchsia:`fuchsia`, :pink:`pink`, :orange:`orange`, :yellow:`yellow`,
+:lime:`lime`, :green:`green`, :olive:`olive`, :teal:`teal`,
+:cyan:`cyan`, :aqua:`aqua`, :blue:`blue`, :navy:`navy`,
+:purple:`purple`
+
+The class names and role names are the same as the colour names.  For
+example, "``:orange:`text```" produces ":orange:`text`".
+
+.. class:: incremental
+
+Requires "``.. include:: <s5defs.txt>``".
+
+
+Classes: Borderless Tables
+==========================
+
+.. class:: handout
+
+   Here's an ordinary, unstyled table:
+
+.. class:: incremental
+
+   =========  =======
+   Sometimes  borders
+   ---------  -------
+   are        useful.
+   =========  =======
+
+   And after applying "``.. class:: borderless``":
+
+   .. class:: borderless
+
+   =======  ==========  =======
+   But      sometimes,  borders
+   -------  ----------  -------
+   are      **not**     wanted.
+   =======  ==========  =======
+
+
+Classes: Print-Only
+===================
+
+.. class:: handout
+
+   Elements with ``class="print"`` attributes display their contents
+   when printed, overriding ``class="hidden"``.
+
+.. class:: incremental
+
+   Example: the "target-notes" directive::
+
+       .. topic:: Links
+          :class: hidden print
+
+          .. target-notes::
+             :class: hidden print
+
+.. container:: handout
+
+   One good example, used in this document, is the "target-notes"
+   directive.  For each external target (hyperlink) in the text, this
+   directive generates a footnote containing the visible URL as
+   content.  Footnote references are placed after each hyperlink
+   reference.
+
+   The "topic" directive is given a "class" attribute with values
+   "hidden" and "print", so the entire topic will only be displayed
+   when printed.  The "target-notes" directive also assigns a "class"
+   attributes with values "hidden" and "print" to each of the footnote
+   references it inserts throughout the text; they will only show up
+   when printed.
+
+.. class:: incremental
+
+   Other uses may require "``.. include:: <s5defs.txt>``".
+
+
+Useful Extensions For Firefox
+=============================
+
+* `Autohide`__
+
+  .. class:: handout
+
+  Automatically hides toolbars in full-screen mode.
+
+  __ http://www.krickelkrackel.de/autohide/autohide.htm
+
+* `Web Developer`__
+
+  .. class:: handout
+
+  Adds a context submenu and a toolbar with a lot of useful
+  functionality, including the viewing and live editing of
+  stylesheets, and sizing the browser window.
+
+  __ http://chrispederick.com/work/webdeveloper/
+
+
+To Do
+=====
+
+.. class:: incremental
+
+   * Multi-display support:
+
+     - speaker's notes on the laptop screen
+     - slides on the projector
+     - two views stay in sync
+     - presentation controlled from either display
+
+   * Add timeout to incremental style.
+
+     .. class:: handout
+
+     I.e., incremental-specific style should go away (revert to
+     normal) after a certain interval.
+
+   These will require some serious JavaScript-fu!
+
+
+That's All, Folks!
+==================
+
+.. class:: huge
+
+   Further information:
+   http://docutils.sf.net
+
+   Docutils users' mailing list:
+   docutils-users@lists.sf.net
+
+   `Any questions?`
+
+
+.. topic:: Links
+   :class: hidden print
+
+   .. target-notes:: :class: hidden print
diff --git a/docs/user/tools.txt b/docs/user/tools.txt
new file mode 100644
index 000000000..20f5a3b2f
--- /dev/null
+++ b/docs/user/tools.txt
@@ -0,0 +1,389 @@
+==========================
+ Docutils Front-End Tools
+==========================
+
+:Author: David Goodger
+:Contact: goodger@python.org
+: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 rstpep2html.py_.)  See
+rst2html.py_ for concrete examples.  Each tool has a "``--help``"
+option which lists the `command-line options`_ and arguments it
+supports.  Processing can also be customized with `configuration
+files`_.
+
+The two arguments, "source" and "destination", are optional.  If only
+one argument (source) is specified, the standard output (stdout) is
+used for the destination.  If no arguments are specified, the standard
+input (stdin) is used for the source 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.
+
+.. _Docutils-users: mailing-lists.html#docutils-users
+
+
+-----------
+ The Tools
+-----------
+
+HTML-Generating Tools
+=====================
+
+buildhtml.py
+------------
+
+:Readers: Standalone, PEP
+:Parser: reStructuredText
+:Writers: HTML, PEP/HTML
+
+Use ``buildhtml.py`` to generate .html from all the .txt files
+(including PEPs) in each <directory> given, and their subdirectories
+too.  (Use the ``--local`` option to skip subdirectories.)
+
+Usage::
+
+    buildhtml.py [options] [<directory> ...]
+
+After unpacking the Docutils package, the following shell commands
+will generate HTML for all included documentation::
+
+    cd docutils/tools
+    buildhtml.py ..
+
+For official releases, the directory may be called "docutils-X.Y",
+where "X.Y" is the release version.  Alternatively::
+
+    cd docutils
+    tools/buildhtml.py --config=tools/docutils.conf
+
+The current directory (and all subdirectories) is chosen by default if
+no directory is named.  Some files may generate system messages
+(docs/user/rst/demo.txt contains intentional errors); use the
+``--quiet`` option to suppress all warnings.  The ``--config`` option
+ensures that the correct settings are in place (a ``docutils.conf``
+`configuration file`_ in the current directory is picked up
+automatically).  Command-line options may be used to override config
+file settings or replace them altogether.
+
+
+rst2html.py
+-----------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: HTML
+
+The ``rst2html.py`` front end reads standalone reStructuredText source
+files and produces HTML 4 (XHTML 1) output compatible with modern
+browsers that support cascading stylesheets (CSS).  A stylesheet is
+required for proper rendering; a simple but complete stylesheet is
+installed and used by default (see Stylesheets_ below).
+
+For example, to process a reStructuredText file "``test.txt``" into
+HTML::
+
+    rst2html.py test.txt test.html
+
+Now open the "``test.html``" file in your favorite browser to see the
+results.  To get a footer with a link to the source file, date & time
+of processing, and links to the Docutils project, add some options::
+
+    rst2html.py -stg test.txt test.html
+
+
+Stylesheets
+```````````
+
+``rst2html.py`` inserts into the generated HTML a cascading stylesheet
+(or a link to a stylesheet, when passing the "``--link-stylesheet``"
+option).  A stylesheet is required for proper rendering.  The default
+stylesheet (``docutils/writers/html4css1/html4css1.css``, located in
+the installation directory) is provided for basic use.  To use a
+different stylesheet, you must specify the stylesheet's location with
+a "``--stylesheet``" (for a URL) or "``--stylesheet-path``" (for a
+local file) command-line option, or with `configuration file`_
+settings (e.g. ``./docutils.conf`` or ``~/.docutils``).  To experiment
+with styles, please see the `guide to writing HTML (CSS) stylesheets
+for Docutils`__.
+
+__ ../howto/html-stylesheets.html
+
+
+rstpep2html.py
+--------------
+
+:Reader: PEP
+:Parser: reStructuredText
+:Writer: PEP/HTML
+
+``rstpep2html.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 the "``pep.css``" stylesheet (both in the
+``docutils/writers/pep_html/`` directory), but these can be overridden
+by command-line options or configuration files.
+
+For example, to process a PEP into HTML::
+
+    cd <path-to-docutils>/docs/peps
+    rstpep2html.py pep-0287.txt pep-0287.html
+
+
+rst2s5.py
+---------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: S5/HTML
+
+The ``rst2s5.py`` front end reads standalone reStructuredText source
+files and produces (X)HTML output compatible with S5_, the "Simple
+Standards-based Slide Show System" by Eric Meyer.  A theme is required
+for proper rendering; several are distributed with Docutils and others
+are available; see Themes_ below.
+
+For example, to process a reStructuredText file "``slides.txt``" into
+S5/HTML::
+
+    rst2s5.py slides.txt slides.html
+
+Now open the "``slides.html``" file in your favorite browser, switch
+to full-screen mode, and enjoy the results.
+
+.. _S5: http://meyerweb.com/eric/tools/s5/
+
+
+Themes
+``````
+
+Each S5 theme consists of a directory containing several files:
+stylesheets, JavaScript, and graphics.  These are copied into a
+``ui/<theme>`` directory beside the generated HTML.  A theme is chosen
+using the "``--theme``" option (for themes that come with Docutils) or
+the "``--theme-url``" option (for themes anywhere).  For example, the
+"medium-black" theme can be specified as follows::
+
+    rst2s5.py --theme medium-black slides.txt slides.html
+
+The theme will be copied to the ``ui/medium-black`` directory.
+
+Several themes are included with Docutils:
+
+``default``
+    This is a simplified version of S5's default theme.
+
+    :Main content: black serif text on a white background
+    :Text capacity: about 13 lines
+    :Headers: light blue, bold sans-serif text on a dark blue
+              background; titles are limited to one line
+    :Footers: small, gray, bold sans-serif text on a dark blue
+              background
+
+``small-white``
+    (Small text on a white background.)
+
+    :Main content: black serif text on a white background
+    :Text capacity: about 15 lines
+    :Headers: black, bold sans-serif text on a white background;
+              titles wrap
+    :Footers: small, dark gray, bold sans-serif text on a white
+              background
+
+``small-black``
+    :Main content: white serif text on a black background
+    :Text capacity: about 15 lines
+    :Headers: white, bold sans-serif text on a black background;
+              titles wrap
+    :Footers: small, light gray, bold sans-serif text on a black
+              background
+
+``medium-white``
+    :Main content: black serif text on a white background
+    :Text capacity: about 9 lines
+    :Headers: black, bold sans-serif text on a white background;
+              titles wrap
+    :Footers: small, dark gray, bold sans-serif text on a white
+              background
+
+``medium-black``
+    :Main content: white serif text on a black background
+    :Text capacity: about 9 lines
+    :Headers: white, bold sans-serif text on a black background;
+              titles wrap
+    :Footers: small, light gray, bold sans-serif text on a black
+              background
+
+``big-white``
+    :Main content: black, bold sans-serif text on a white background
+    :Text capacity: about 5 lines
+    :Headers: black, bold sans-serif text on a white background;
+              titles wrap
+    :Footers: not displayed
+
+``big-black``
+    :Main content: white, bold sans-serif text on a black background
+    :Text capacity: about 5 lines
+    :Headers: white, bold sans-serif text on a black background;
+              titles wrap
+    :Footers: not displayed
+
+If a theme directory contains a file named ``__base__``, the name of
+the theme's base theme will be read from it.  Files are accumulated
+from the named theme, any base themes, and the "default" theme (which
+is the implicit base of all themes).
+
+For details, please see `Easy Slide Shows With reStructuredText &
+S5 <slide-shows.html>`_.
+
+
+LaTeX-Generating Tools
+======================
+
+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`_.
+
+
+XML-Generating Tools
+====================
+
+rst2xml.py
+----------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: XML (Docutils native)
+
+The ``rst2xml.py`` front end produces Docutils-native XML output.
+This can be transformed with standard XML tools such as XSLT
+processors into arbitrary final forms.
+
+
+Testing/Debugging Tools
+=======================
+
+rst2pseudoxml.py
+----------------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: Pseudo-XML
+
+``rst2pseudoxml.py`` is used for debugging the Docutils "Reader to
+Transform to Writer" pipeline.  It produces a compact pretty-printed
+"pseudo-XML", where nesting is indicated by indentation (no end-tags).
+External attributes for all elements are output, and internal
+attributes for any leftover "pending" elements are also given.
+
+
+quicktest.py
+------------
+
+:Reader: N/A
+:Parser: reStructuredText
+:Writer: N/A
+
+The ``quicktest.py`` tool is used for testing the reStructuredText
+parser.  It does not use a Docutils Reader or Writer or the standard
+Docutils command-line options.  Rather, it does its own I/O and calls
+the parser directly.  No transforms are applied to the parsed
+document.  Various forms output are possible:
+
+- Pretty-printed pseudo-XML (default)
+- Test data (Python list of input and pseudo-XML output strings;
+  useful for creating new test cases)
+- Pretty-printed native XML
+- Raw native XML (with or without a stylesheet reference)
+
+
+
+---------------
+ Customization
+---------------
+
+Command-Line Options
+====================
+
+Each front-end tool supports command-line options for one-off
+customization.  For persistent customization, use `configuration
+files`_.  Command-line options take priority over configuration file
+settings.
+
+Use the "--help" option on each of the front ends to list the
+command-line options it supports.  Command-line options and their
+corresponding configuration file entry names are listed in the
+`Docutils Configuration Files`_ document.
+
+
+.. _configuration file:
+
+Configuration Files
+===================
+
+Configuration files are used for persistent customization; they can be
+set once and take effect every time you use a front-end tool.
+
+For details, see `Docutils Configuration Files`_.
+
+.. _Docutils Configuration Files: config.html
+.. _Generating LaTeX with Docutils: latex.html
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End: