summaryrefslogtreecommitdiff
path: root/docutils/docs/user
diff options
context:
space:
mode:
authorwiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>2005-08-17 13:59:12 +0000
committerwiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>2005-08-17 13:59:12 +0000
commita4bc0d09f3d1f633a5780976d1f913e083c9564a (patch)
tree1777475e88463b08438f0719be97cc087554eadd /docutils/docs/user
parent60c69f8cf97125135948a3d35b7698ee80921137 (diff)
parent2818db9a234cc37008c5f2bb0e821f9b1fa92de2 (diff)
downloaddocutils-0.3.9.tar.gz
re-added docutils-0.3.9 tag one level deeper (without web/ and sandboxes/)docutils-0.3.9
git-svn-id: http://svn.code.sf.net/p/docutils/code/tags/docutils-0.3.9@3815 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
Diffstat (limited to 'docutils/docs/user')
-rw-r--r--docutils/docs/user/config.txt959
-rw-r--r--docutils/docs/user/latex.txt388
-rw-r--r--docutils/docs/user/rst/cheatsheet.txt121
-rw-r--r--docutils/docs/user/rst/demo.txt550
-rw-r--r--docutils/docs/user/rst/images/ball1.gifbin4361 -> 0 bytes
-rw-r--r--docutils/docs/user/rst/images/biohazard.pngbin179 -> 0 bytes
-rw-r--r--docutils/docs/user/rst/images/title.pngbin1171 -> 0 bytes
-rw-r--r--docutils/docs/user/rst/quickref.html1319
-rw-r--r--docutils/docs/user/rst/quickstart.txt390
-rw-r--r--docutils/docs/user/tools.txt316
10 files changed, 0 insertions, 4043 deletions
diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
deleted file mode 100644
index 1b52511b4..000000000
--- a/docutils/docs/user/config.txt
+++ /dev/null
@@ -1,959 +0,0 @@
-==============================
- 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
- "``&#8224;``".
- backslashreplace
- (Python 2.3+) Replace with backslashed escape sequences, such
- as "``\u2020``".
-
- Acceptable values are the same as for the "error" parameter of
- Python's ``encode`` string method; other values may be defined in
- applications or in future versions of Python.
-
- Default: "strict". Options: ``--output-encoding-error-handler,
- --output-encoding, -o``.
-
-_`record_dependencies`
-
- Path to a file to which Docutils writes a list of files the input
- file(s) depends on [#dependencies]_, e.g. due to file
- inclusion. [#pwd]_ The format is one filename per line. This
- option is particularly useful in conjunction with programs like
- ``make``.
-
- Set to ``-`` in order to write dependencies to stdout.
-
- Default: None. Option: ``--record-dependencies``.
-
-_`report_level`
- Verbosity threshold at or above which system messages are
- reported.
-
- Default: warning (2). Options: ``--report, -r, --verbose, -v,
- --quiet, -q``.
-
-_`sectnum_xform`
- Enable or disable the section numbering transform
- (docutils.transforms.parts.SectNum).
-
- Default: enabled (1). Options: ``--no-section-numbering``.
-
-_`source_link`
- Include a "View document source" link in the document footer. URL
- will be relative to the destination.
-
- Default: don't (None). Options: ``--source-link, -s,
- --no-source-link``.
-
-_`source_url`
- An explicit URL for a "View document source" link, used verbatim.
-
- Default: compute if source_link (None). Options: ``--source-url,
- --no-source-link``.
-
-_`strict_visitor`
- When processing a document tree with the Visitor pattern, raise an
- error if a writer does not support a node type listed as optional.
- For transitional development use.
-
- Default: disabled (None). Option: ``--strict-visitor`` (hidden,
- for development use only).
-
-_`toc_backlinks`
- Enable backlinks from section titles to table of contents entries
- ("entry"), to the top of the TOC ("top"), or disable ("none").
-
- Default: "entry". Options: ``--toc-entry-backlinks,
- --toc-top-backlinks, --no-toc-backlinks``.
-
-_`traceback`
- Enable Python tracebacks when halt-level system messages and other
- exceptions occur. Useful for debugging, and essential for issue
- reports. Exceptions are allowed to propagate, instead of being
- caught and reported (in a user-friendly way) by Docutils.
-
- Default: disabled (None) unless Docutils is run programmatically
- using the `Publisher Interface`_. Options: ``--traceback,
- --no-traceback``.
-
- .. _Publisher Interface: ../api/publisher.html
-
-_`warning_stream`
- Path to a file for the output of system messages (warnings)
- [#pwd]_.
-
- Default: stderr (None). Options: ``--warnings``.
-
-
-[parsers]
----------
-
-Docutils currently supports only one parser, for reStructuredText.
-
-
-[restructuredtext parser]
-`````````````````````````
-
-_`file_insertion_enabled`
- Enable or disable directives that insert the contents of external
- files, such as the "include_" & "raw_". A "warning" system
- message (including the directive text) is inserted instead. (See
- also raw_enabled_ for another security-relevant setting.)
-
- Default: enabled (1). Options: ``--file-insertion-enabled,
- --no-file-insertion``.
-
- .. _include: ../ref/rst/directives.html#include
- .. _raw: ../ref/rst/directives.html#raw
-
-_`pep_references`
- Recognize and link to standalone PEP references (like "PEP 258").
-
- Default: disabled (None); enabled (1) in PEP Reader. Options:
- ``--pep-references``.
-
-_`pep_base_url`
- Base URL for PEP references.
-
- Default: "http://www.python.org/peps/". Option:
- ``--pep-base-url``.
-
-_`raw_enabled`
- Enable or disable the "raw_" directive. A "warning" system
- message (including the directive text) is inserted instead. (See
- also file_insertion_enabled_ for another security-relevant
- setting.)
-
- Default: enabled (1). Options: ``--raw-enabled, --no-raw``.
-
-_`rfc_references`
- Recognize and link to standalone RFC references (like "RFC 822").
-
- Default: disabled (None); enabled (1) in PEP Reader. Options:
- ``--rfc-references``.
-
-_`rfc_base_url`
- Base URL for RFC references.
-
- Default: "http://www.faqs.org/rfcs/". Option: ``--rfc-base-url``.
-
-_`tab_width`
- Number of spaces for hard tab expansion.
-
- Default: 8. Options: ``--tab-width``.
-
-_`trim_footnote_reference_space`
- Remove spaces before footnote references.
-
- Default: don't (None); may be overriden by a writer-specific
- footnote_references__ default though. Options:
- ``--trim-footnote-reference-space,
- --leave-footnote-reference-space``.
-
-__ `footnote_references [latex2e writer]`_
-
-
-[readers]
----------
-
-
-[standalone reader]
-```````````````````
-
-_`docinfo_xform`
- Enable or disable the bibliographic field list transform
- (docutils.transforms.frontmatter.DocInfo).
-
- Default: enabled (1). Options: ``--no-doc-info``.
-
-_`doctitle_xform`
- Enable or disable the promotion of a lone top-level section title
- to document title (and subsequent section title to document
- subtitle promotion; docutils.transforms.frontmatter.DocTitle).
-
- Default: enabled (1). Options: ``--no-doc-title``.
-
-_`sectsubtitle_xform`
-
- Enable or disable the promotion of the title of a lone subsection
- to a subtitle (docutils.transforms.frontmatter.SectSubTitle).
-
- Default: disabled (0). Options: ``--section-subtitles,
- --no-section-subtitles``.
-
-
-[pep reader]
-````````````
-
-The `pep_references`_ and `rfc_references`_ options
-(`[restructuredtext parser]`_) are set on by default.
-
-
-[python reader]
-```````````````
-
-Under construction.
-
-
-[writers]
----------
-
-[docutils_xml writer]
-`````````````````````
-
-_`doctype_declaration`
- Generate XML with a DOCTYPE declaration.
-
- Default: do (1). Options: ``--no-doctype``.
-
-_`indents`
- Generate XML with indents and newlines.
-
- Default: don't (None). Options: ``--indents``.
-
-_`newlines`
- Generate XML with newlines before and after tags.
-
- Default: don't (None). Options: ``--newlines``.
-
-.. _xml_declaration [docutils_xml writer]:
-
-xml_declaration
- Generate XML with an XML declaration. Also defined for the
- `HTML Writer`__.
-
- .. Caution:: The XML declaration carries text encoding
- information, without which standard tools may be unable to read
- the generated XML.
-
- Default: do (1). Options: ``--no-xml-declaration``.
-
- __ `xml_declaration [html4css1 writer]`_
-
-
-[html4css1 writer]
-``````````````````
-
-.. _attribution [html4css1 writer]:
-
-attribution
- Format for block quote attributions: one of "dash" (em-dash
- prefix), "parentheses"/"parens", or "none". Also defined for the
- `LaTeX Writer`__.
-
- Default: "dash". Options: ``--attribution``.
-
- __ `attribution [latex2e writer]`_
-
-_`cloak_email_addresses`
- Scramble email addresses to confuse harvesters. In the visible
- text of an email address, the "@" will be replaced by "at", and
- all periods (".") will be replaced by "dot", with spaces added.
- In the reference URI, the address will be replaced by %-escapes.
- For example, "abc@example.org" will be output as::
-
- <a class="reference"
- href="mailto:%61%62%63%40%65%78%61%6D%70%6C%65%2E%6F%72%67">
- abc at example dot org</a>
-
- Default: don't cloak (None). Option: ``--cloak-email-addresses``.
-
-_`compact_lists`
- Remove extra vertical whitespace between items of bullet lists and
- enumerated lists, when list items are "simple" (i.e., all items
- each contain one paragraph and/or one "simple" sublist only).
-
- Default: enabled (1). Options: ``--compact-lists,
- --no-compact-lists``.
-
-_`embed_stylesheet`
- Embed the stylesheet in the output HTML file. The stylesheet file
- must be accessible during processing.
-
- Default: link, don't embed (None). Options: ``--embed-stylesheet,
- --link-stylesheet``.
-
-_`field_name_limit`
- The maximum width (in characters) for one-column field names.
- Longer field names will span an entire row of the table used to
- render the field list. 0 indicates "no limit". See also
- option_limit_.
-
- Default: 14 characters. Option: ``--field-name-limit``.
-
-.. _footnote_references [html4css1 writer]:
-
-footnote_references
- Format for footnote references, one of "superscript" or
- "brackets". Also defined for the `LaTeX Writer`__.
-
- Overrides [#override]_ trim_footnote_reference_space_, if
- applicable. [#footnote_space]_
-
- Default: "brackets". Option: ``--footnote-references``.
-
- __ `footnote_references [latex2e writer]`_
-
-_`initial_header_level`
- The initial level for header elements. This does not affect the
- document title & subtitle; see doctitle_xform_.
-
- Default: 1 (for "<h1>"). Option: ``--initial-header-level``.
-
-.. _stylesheet [html4css1 writer]:
-
-_`option_limit`
- The maximum width (in characters) for options in option lists.
- Longer options will span an entire row of the table used to render
- the option list. 0 indicates "no limit". See also
- field_name_limit_.
-
- Default: 14 characters. Option: ``--option-limit``.
-
-stylesheet
- CSS stylesheet URL, used verbatim. Overrides stylesheet_path
- [#override]_.
-
- Default: "default.css". Options: ``--stylesheet``.
-
- (Setting also defined for the `LaTeX Writer`__.)
-
- __ `stylesheet [latex2e writer]`_
-
-.. _stylesheet_path [html4css1 writer]:
-
-stylesheet_path
- Path to CSS stylesheet [#pwd]_. Overrides "stylesheet" URL
- setting (``--stylesheet``) [#override]_. Path is adjusted
- relative to the output HTML file. Also defined for the `LaTeX
- Writer`__.
-
- Default: None. Options: ``--stylesheet-path``.
-
- __ `stylesheet_path [latex2e writer]`_
-
-.. _xml_declaration [html4css1 writer]:
-
-xml_declaration
- Generate XML with an XML declaration. Also defined for the
- `Docutils XML Writer`__.
-
- .. Caution:: The XML declaration carries text encoding
- information, without which standard tools may be unable to read
- the generated XML.
-
- Default: do (1). Options: ``--no-xml-declaration``.
-
- __ `xml_declaration [docutils_xml writer]`_
-
-
-[pep_html writer]
-.................
-
-The PEP/HTML Writer derives from the standard HTML Writer, and shares
-all settings defined in the `[html4css1 writer]`_ section. The
-"[html4css1 writer]" section is processed before "[pep_html writer]".
-
-_`no_random`
- Do not use a random banner image. Mainly used to get predictable
- results when testing.
-
- Default: random enabled (None). Options: ``--no-random``
- (hidden).
-
-_`pep_home`
- Home URL prefix for PEPs.
-
- Default: current directory ("."). Options: ``--pep-home``.
-
-_`template`
- Path to PEP template file [#pwd]_.
-
- Default: "pep-html-template" (in current directory). Options:
- ``--template``.
-
-_`python_home`
- Python's home URL.
-
- Default: parent directory (".."). Options: ``--python-home``.
-
-
-[latex2e writer]
-````````````````
-
-_`use_latex_toc`
- To get pagenumbers in the table of contents the table of contents
- must be generated by latex. Usually latex must be run twice to get
- numbers correct.
-
- *Note:* LaTeX will number the sections, which might be a bug in
- this case.
-
- Default: off. Option: ``--use-latex-toc``.
-
-.. XXX Missing: use_latex_docinfo
-
-_`use_latex_footnotes`
- Use LaTeX-footnotes not a figure simulation. This might give no
- Hyperrefs on /to footnotes, but should be able to handle an
- unlimited number of footnotes.
-
- Default: off. Option: ``--use-latex-footnotes``.
-
-_`hyperlink_color`
- Color of any hyperlinks embedded in text. Use "0" to disable
- coloring of links.
-
- Default: "blue". Option: ``--hyperlink-color``.
-
-_`documentclass`
- Specify latex documentclass, *but* beaware that books have chapters
- articles not.
-
- Default: "article". Option: ``--documentclass``.
-
-_`documentoptions`
- Specify document options. Multiple options can be given, separated by
- commas.
-
- Default: "10pt,a4paper". Option: ``--documentoptions``.
-
-.. _stylesheet [latex2e writer]:
-
-stylesheet
- Specify a stylesheet file. Overrides stylesheet_path
- [#override]_. The file will be ``\input`` by latex in the
- document header. Also defined for the `HTML Writer`__.
-
- Default: no stylesheet (""). Option: ``--stylesheet``.
-
- __ `stylesheet [html4css1 writer]`_
-
-.. _stylesheet_path [latex2e writer]:
-
-stylesheet_path
- Path to stylesheet [#pwd]_. Overrides "stylesheet" setting
- (``--stylesheet``) [#override]_.
-
- Please note that you will have to run ``latex`` from the directory
- containing the output file; otherwise the stylesheet reference
- will be invalid.
-
- This setting is also defined for the `HTML Writer`__.
-
- Default: None. Option: ``--stylesheet-path``.
-
- __ `stylesheet_path [html4css1 writer]`_
-
-.. XXX Missing: embed_stylesheet
-
-.. _footnote_references [latex2e writer]:
-
-footnote_references
- Format for footnote references: one of "superscript" or
- "brackets". Also defined for the `HTML Writer`__.
-
- Overrides [#override]_ trim_footnote_reference_space_, if
- applicable. [#footnote_space]_
-
- Default: "superscript". Option: ``--footnote-references``.
-
- __ `footnote_references [html4css1 writer]`_
-
-.. _attribution [latex2e writer]:
-
-attribution
- Format for block quote attributions, the same as for the
- html-writer: one of "dash" (em-dash prefix),
- "parentheses"/"parens" or "none". Also defined for the `HTML
- Writer`__.
-
- Default: "dash". Option: ``--attribution``.
-
- __ `attribution [html4css1 writer]`_
-
-_`compound_enumerators`
- Enable or disable compound enumerators for nested enumerated lists
- (e.g. "1.2.a.ii").
-
- Default: disabled (None). Options: ``--compound-enumerators``,
- ``--no-compound-enumerators``.
-
-_`section_prefix_for_enumerators`
- Enable or disable section ("." subsection ...) prefixes for
- compound enumerators. This has no effect unless
- `compound_enumerators`_ are enabled.
-
- Default: disabled (None). Options:
- ``--section-prefix-for-enumerators``,
- ``--no-section-prefix-for-enumerators``.
-
-_`section_enumerator_separator`
- The separator between section number prefix and enumerator for
- compound enumerated lists (see `compound_enumerators`_).
-
- Generally it isn't recommended to use both sub-sections and nested
- enumerated lists with compound enumerators. This setting avoids
- ambiguity in the situation where a section "1" has a list item
- enumerated "1.1", and subsection "1.1" has list item "1". With a
- separator of ".", these both would translate into a final compound
- enumerator of "1.1.1". With a separator of "-", we get the
- unambiguous "1-1.1" and "1.1-1".
-
- Default: "-". Option: ``--section-enumerator-separator``.
-
-_`table_style`
- Specify the drawing of separation lines.
-
- - "standard" lines around and between cells.
- - "booktabs" a line above and below the table and one after the
- head.
- - "nolines".
-
- Default: "standard". Option: ``--table-style``.
-
-
-[pseudoxml writer]
-``````````````````
-
-No settings are defined for this Writer.
-
-
-[applications]
---------------
-
-[buildhtml application]
-```````````````````````
-
-_`prune`
- List of directories not to process. To specify multiple
- directories in configuration files, use colon-separated paths; on
- the command line, the option may be used more than once.
-
- Default: none ([]). Options: ``--prune``.
-
-_`recurse`
- Recursively scan subdirectories, or ignore subdirectories.
-
- Default: recurse (1). Options: ``--recurse, --local``.
-
-_`silent`
- Work silently (no progress messages). Independent of
- "report_level".
-
- Default: show progress (None). Options: ``--silent``.
-
-
-[docfactory application]
-````````````````````````
-
-(To be completed.)
-
-
-Other Settings
-==============
-
-These settings are only effective as command-line options, positional
-arguments, or for internal use; setting them in configuration files
-has no effect.
-
-_`config`
- Path to a configuration file to read (if it exists) [#pwd]_.
- Settings may override defaults and earlier settings. The config
- file is processed immediately. Multiple ``--config`` options may
- be specified; each will be processed in turn.
-
- Filesystem path settings contained within the config file will be
- interpreted relative to the config file's location (*not* relative
- to the current working directory).
-
- Default: None. Options: ``--config``.
-
-_`_directories`
- (``buildhtml.py`` front end.) List of paths to source
- directories, set from positional arguments.
-
- Default: current working directory (None). No command-line
- options.
-
-_`_disable_config`
- Prevent standard configuration files from being read. For
- internal use only.
-
- Default: config files enabled (None). No command-line options.
-
-_`_destination`
- Path to output destination, set from positional arguments.
-
- Default: stdout (None). No command-line options.
-
-_`_source`
- Path to input source, set from positional arguments.
-
- Default: stdin (None). No command-line options.
-
-
-.. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html
-
-.. [#pwd] Path relative to the working directory of the process at
- launch.
-
-.. [#override] The overridden setting will automatically be set to
- ``None`` for command-line options and config file settings. Client
- programs which specify defaults that override other settings must
- do the overriding explicitly, by assigning ``None`` to the other
- settings.
-
-.. [#dependencies] Some notes on the dependency recorder:
-
- * Images are only added to the dependency list if the
- reStructuredText parser extracted image dimensions from the file.
-
- * Stylesheets are only added if they are embedded.
-
- * For practical reasons, the output of the LaTeX writer is
- considered merely an *intermediate* processing stage. The
- dependency recorder records all files the *rendered* file
- (e.g. in PDF or DVI format) depends on. Thus, images and
- stylesheets are both unconditionally recorded as dependencies
- when using the LaTeX writer.
-
-.. [#footnote_space] The footnote space is trimmed if the reference
- style is "superscript", and it is left if the reference style is
- "brackets".
-
- The overriding only happens if the parser supports the
- trim_footnote_reference_space option.
-
-
-------------------------------
-Old-Format Configuration Files
-------------------------------
-
-Formerly, Docutils configuration files contained a single "[options]"
-section only. This was found to be inflexible, and in August 2003
-Docutils adopted the current component-based configuration file
-sections as described above. Docutils will still recognize the old
-"[options]" section, but complains with a deprecation warning.
-
-To convert existing config files, the easiest way is to change the
-section title: change "[options]" to "[general]". Most settings
-haven't changed. The only ones to watch out for are these:
-
-===================== =====================================
-Old-Format Setting New Section & Setting
-===================== =====================================
-pep_stylesheet [pep_html writer] stylesheet
-pep_stylesheet_path [pep_html writer] stylesheet_path
-pep_template [pep_html writer] template
-===================== =====================================
diff --git a/docutils/docs/user/latex.txt b/docutils/docs/user/latex.txt
deleted file mode 100644
index d66586bc7..000000000
--- a/docutils/docs/user/latex.txt
+++ /dev/null
@@ -1,388 +0,0 @@
-================================
- Generating LaTeX with Docutils
-================================
-
-:Author: Engelbert Gruber
-:Contact: grubert@users.sourceforge.net
-:Revision: $Revision$
-:Date: $Date$
-:Copyright: This document has been placed in the public domain.
-
-.. contents::
-
-
-Introduction
-============
-
-Producing LaTeX code from reST input could be done in at least two ways:
-
-a. Transform the internal markup into corresponding LaTeX markup e.g.
- a section title would be written as ```\section{this section ...}``.
-b. Using LaTeX as a typesetting system to produce desired paperwork
- without caring about loosing document structure information.
-
-The former might be preferable, but limits to LaTeXs capabilities, so
-in reality it is a mix. The reality is that LaTeX has a titlepage with
-title, author and date, by default only title is used. Author and date
-are shown in the docutils docinfo table and set to blank for LaTeX.
-To get author and date set by LaTeX specify option "use-LaTeX-docinfo".
-
-Options
-=======
-
-Configuration can be done in two ways (again):
-
-1. Options to the docutils tool: e.g. language selection.
-2. Options to LaTeX via the stylesheet file.
-
-The generated LaTeX documents should be kept processable by a standard
-LaTeX installation (if such a thing exists), therefore the document
-contains default settings. To allow *overwriting defaults* the stylesheet
-is included at last.
-
-Run ``rst2latex.py --help`` to see the command-line options, or have look in
-config documentytion.
-
-
-===================== ================================================
-Configuration Issue Description
-===================== ================================================
-papersize Default: a4paper. Paper geometry can be changed
- using ``\geometry{xxx}`` entries.
-
- Some possibilities:
-
- * a4paper, b3paper, letterpaper, executivepaper,
- legalpaper
- * landscape, portrait, twoside.
-
- and a ton of other option setting margins.
-
- An example::
-
- \geometry{a5paper,landscape}
---------------------- ------------------------------------------------
-paragraph indent By default LaTeX indents the forst line in a
- paragraph. The following lines set indentation
- to zero but add a vertical space between
- paragraphs.::
-
- \setlength{\parindent}{0pt}
- \setlength{\parskip}{6pt plus 2pt minus 1pt}
---------------------- ------------------------------------------------
-admonitionwidth The width for admonitions.
- Default: 0.9*textwidth, this can be changed
- e.g.::
-
- \setlength{\admonitionwidth}{0.7\textwidth}
---------------------- ------------------------------------------------
-docinfowidth The width for the docinfo table.
- Default: 0.9*textwidth, changed to e.g.::
-
- \setlength{\docinfowidth}{0.7\textwidth}
---------------------- ------------------------------------------------
-rubric style The header contains the definition of a new
- LaTeX command rubric. Inserting::
-
- \renewcommand{\rubric}[1]{\subsection*{
- ~\hfill {\color{red} #1} \hfill ~}}
-
- sets rubric to subsection style in red.
-
- Default: subsection style italic.
---------------------- ------------------------------------------------
-line spacing Is done with package *setspace*, which gives
- singlespace, onehalfspace and doublespace
- commands. To get documentwide double spacing,
- add this to your stylesheet ::
-
- \usepackage{setspace}
- \doublespacing
-
- Another way ::
-
- \linespread{1.55}
-
- And yet another, add ``doublesp`` to the
- documentoptions and e.g. ::
-
- \setstretch{1.7}
-
- for bigger linespacing.
---------------------- ------------------------------------------------
-font selection see below
-===================== ================================================
-
-
-Font selection
---------------
-
-When generating pdf-files from LaTeX, use the pdflatex command, the files
-are a lot smaller if postscript fonts are used. This *was* fixed by putting
-``\usepackage{times}`` into the stylesheet.
-
-It is said that the typewriter font in computer modern font, the default
-LaTeX font package, is too heavy compared to the others. There is a package
-or some commands too fix this, which i currently cannot find.
-
-Some people diagnose a similar unbalance for the postscript fonts, the
-package to fix this is ``\usepackage{pslatex}``.
-pslatex in contrast to the standard LaTeX fonts has a bold typewriter font.
-
-As ``times`` does not use the appropriate mathematical fonts and ``pslatex``
-does not work with T1 encodings one should use::
-
- \usepackage{mathptmx}
- \usepackage[scaled=.90]{helvet}
- \usepackage{courier}
-
-*font encoding* can be selected with option "font-encoding". Default
-uses package "ae" for old style font encoding use "OT1".
-
-Hyphenation
------------
-
-The amount of hyphenation is influenced by ``\hyphenpenalty``, setting it to
-10000 almost prevents hyphenation. As this produces lines with more spcea
-between words one should increase LaTeX's ``\tolerance`` for this.
-
-E.g. try ::
-
- \hyphenpenalty=5000
- \tolerance=1000
-
-Unicode
--------
-
-The generated LaTeX documents are in latin1 encoding per default, if unicode
-characters are required one must set ``--output-encoding=utf-8`` install
-`LaTeX unicode`_ support and add::
-
- \usepackage{ucs}
- \usepackage[utf8]{inputenc}
-
-to the stylesheet. If LaTeX issues a Warning about unloaded/known characters
-adding ::
-
- \PreloadUnicodePage{n}
-
-where *n* is the unicode pagenumber, might help.
-
-.. _LaTeX unicode: http://www.unruh.de/DniQ/latex/unicode/
-
-Table of figures
-----------------
-
-A table of figures can be generated by a command directly to LaTeX::
-
- .. raw:: LaTeX
-
- \listoffigures
-
-LaTeX also has a command ``\listoftables``.
-
-Section numbering
------------------
-
-If section numbering and LaTeX table of contents is used LaTeX and
-docutils will number sections. To switch off displaying of LaTeX's
-numbers one has to add following lines to the stylesheet ::
-
- % no section number display
- \makeatletter
- \def\@seccntformat#1{}
- \makeatother
- % no numbers in toc
- \renewcommand{\numberline}[1]{}
-
-
-Number pages by chapter
------------------------
-
-This can be accomplished with ::
-
- \usepackage{chappg}
-
-From the documentation
-
- Basic operation of the package is to redefine ``\thepage`` to be
- ``\thechapter-\arabic{page}``, and to cause the page number to be reset
- (to 1) at the start of each chapter. So the pages of chapter 3 will
- be numbered 3-1, 3-2, ..., and the pages of appendix B will be
- numbered B-1, B-2, ...
-
-See documentation for details and other possibilities.
-
-Images
-------
-
-Images are included in LaTeX by the graphicx package. The supported
-image formats depend on the used driver (dvi, dvips, pdftex, ...).
-
-pdf-image inclusion in pdf files fails, specify ``--graphicx-option=pdftex``
-or ``--graphicx-option=auto``.
-
-
-Commands directly to LaTeX
-==========================
-
-By means of the reST-raw directive one can give commands directly to
-LaTeX, e.g. forcing a page break::
-
- .. raw:: LaTeX
-
- \newpage
-
-
-Or setting formulas in LaTeX::
-
- .. raw:: LaTeX
-
- $$x^3 + 3x^2a + 3xa^2 + a^3,$$
-
-
-Or making a colorbox: If someone wants to get a red background for a textblock,
-she/he can put \definecolor{bg}{rgb}{.9,0,0} into style.tex and in
-reStructuredText do something like this::
-
- |begincolorbox|
- Nobody expects the spanish inquisition.
- |endcolorbox|
-
- .. |begincolorbox| raw:: LaTeX
-
- \\begin{center}
- \\colorbox{bg}{
- \\parbox{0.985\\linewidth}{
-
- .. |endcolorbox| raw:: LaTeX
-
- }}
- \\end{center}
-
-
-Custom title page
------------------
-
-Currently maketitle only shows the title and subtitle, date and author are shown
-in the docinfo table.
-
-To change the titlepage layout, e.g. see fancyhdr, one must redefine the
-maketitle command in the stylesheet::
-
- \renewcommand{\maketitle}{
- \begin{titlepage}
- \begin{center}
- \textsf{TITLE \@title} \\
- Date: \today
- \end{center}
- \end{titlepage}
- }
-
-``\@title`` contains the title.
-
-Problems
-========
-
-Open to be fixed or open to discussion.
-
-footnotes and citations
------------------------
-
-Initially both were implemented using figures, because hyperlinking back
-and forth seemed to be impossible. Later images were put into figures.
-
-This results in footnotes images and figures possibly being mixed at page
-foot.
-
-* Use LaTeX footnotes and citations for printing or more complex layout.
-* Footnotes and citations done with figures might excell in hyperlink
- support.
-
-If ``use-latex-citations`` is used a bibliography is inserted right at
-the end of the document. *This should be customizable*.
-
-Tables
-------
-
-:Tablewidth: reST-documents line length is assumed to be 80 characters. The
- tablewidth is set relative to this value. If someone produces
- documents with line length of 132 this will fail.
-
- Table width is tried to fit in page even if it is wider than
- the assumed linewidth, still assumed linewidth is a hook.
-
-* In tools.txt the option tables right column, there should be some more spacing
- between the description and the next paragraph "Default:".
-
- Paragraph separation in tables is hairy.
- see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab
-
- - The strut solution did not work.
- - setting extrarowheight added ad top of row not between paragraphs in
- a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.
- - baselineskip/stretch does not help.
-* Should there be two hlines after table head and on table end ?
-* Table: multicol cells are always {l}.
-* The contents of a rowspan cell do not influence table height.
- (Maybe if we put a tabular inside ?)
-* Table heads and footer for longtable (firstpage lastpage ..).
-* Table cells with multirow and multicolumn
-* literal-blocks in table cells:
-
- - If verbatim or flushleft is used one gets vertical space above and below.
- - This is bad for the topmost paragraph in a cell, therefore the writer
- uses raggedright.
- - Ragged right fails on followup paragraphs as the vertical space would be
- missing.
-
-Notes
-~~~~~
-
-* table-style booktabs: booktabs.sty 1.00 does not work with longtable.
-
-Miscellaneous
--------------
-
-* Selection of LaTeX fontsize configurable.
-* Assumed reST linelength for table width setting configurable.
-* literal-block indentation configurable.
-* recongize LaTeX and replace by ``\LaTeX``.
-* Support embed-stylesheet.
-* Sidebar handling.
-* Maybe add end of line after term in definition list. see
- http://roundup.sf.net/doc-0.5/features.pdf
-* Pdfbookmark level 4 (and greater) does not work (might be settable but OTOH).
-* center subsection{Abstract} gives a LaTeX error here.
- ``! LaTeX Error: Something's wrong--perhaps a missing \item.``
- Committed a HACK: centering by hfill.
-* Document errors are also too silent.
-* Use optionlist for docinfo, the table does only work for single page.
-* Consider peter funk's hooks for TeXpert:
-
- * Define his own document preamble (including the choice to
- choose his own documentclass. That would make the ``--documentclass``
- option superfluous). I suggest to call this option ``--preamble``
- * Use two additional hooks to put additional stuff just behind the
- ``\begin{document}`` and just before the ``\end{document}`` macros.
- Typical uses would be ``\tableofcontents``, ``\listoffigures`` and
- ``\appendix``, ``\makeindex``, ``\makeglossary`` and some such
- for larger documents.
-
-* The indentional problematic error in docs/user/rst/demo.txt is not
- referring anywhere.
-* Footnotes are not all on the same page (as in
- docs/user/rst/demo.txt) and do not link back and forth.
-* No link to system errors.
-* Hyperlinks are not hyphenated; this leads to bad spacing. See
- docs/user/rst/demo.txt 2.14 directives.
-* Meta keywords into pdf ?
-* Pagestyle headings does not work, when sections are starred.
-* For additional docinfo items: the field_body is inserted as text, i.e. no
- markup is done.
-* Multiple author entries in docinfo (same thing as in html).
-* keep literal-blocks together on a page, avoid pagebreaks.
-
- failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before
- the block.
-
diff --git a/docutils/docs/user/rst/cheatsheet.txt b/docutils/docs/user/rst/cheatsheet.txt
deleted file mode 100644
index 03eddf814..000000000
--- a/docutils/docs/user/rst/cheatsheet.txt
+++ /dev/null
@@ -1,121 +0,0 @@
-=====================================================
- The reStructuredText_ Cheat Sheet: Syntax Reminders
-=====================================================
-:Info: See <http://docutils.sf.net/rst.html> for introductory docs.
-:Author: David Goodger <goodger@python.org>
-:Date: $Date$
-:Revision: $Revision$
-:Description: This is a "docinfo block", or bibliographic field list
-
-Section Structure
-=================
-Section titles are underlined or overlined & underlined.
-
-Body Elements
-=============
-Grid table:
-
-+--------------------------------+-----------------------------------+
-| Paragraphs are flush-left, | Literal block, preceded by "::":: |
-| separated by blank lines. | |
-| | Indented |
-| Block quotes are indented. | |
-+--------------------------------+ or:: |
-| >>> print 'Doctest block' | |
-| Doctest block | > Quoted |
-+--------------------------------+-----------------------------------+
-| | Line blocks preserve line breaks & indents. [new in 0.3.6] |
-| | Useful for addresses, verse, and adornment-free lists; long |
-| lines can be wrapped with continuation lines. |
-+--------------------------------------------------------------------+
-
-Simple tables:
-
-================ ============================================================
-List Type Examples
-================ ============================================================
-Bullet list * items begin with "-", "+", or "*"
-Enumerated list 1. items use any variation of "1.", "A)", and "(i)"
- #. also auto-enumerated
-Definition list Term is flush-left : optional classifier
- Definition is indented, no blank line between
-Field list :field name: field body
-Option list -o at least 2 spaces between option & description
-================ ============================================================
-
-================ ============================================================
-Explicit Markup Examples (visible in the `text source <cheatsheet.txt>`_)
-================ ============================================================
-Footnote .. [1] Manually numbered or [#] auto-numbered
- (even [#labelled]) or [*] auto-symbol
-Citation .. [CIT2002] A citation.
-Hyperlink Target .. _reStructuredText: http://docutils.sf.net/rst.html
- .. _indirect target: reStructuredText_
- .. _internal target:
-Anonymous Target __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html
-Directive ("::") .. image:: images/biohazard.png
-Substitution Def .. |substitution| replace:: like an inline directive
-Comment .. is anything else
-================ ============================================================
-
-Inline Markup
-=============
-*emphasis*; **strong emphasis**; `interpreted text`; `interpreted text
-with role`:emphasis:; ``inline literal text``; standalone hyperlink,
-http://docutils.sourceforge.net; named reference, reStructuredText_;
-`anonymous reference`__; footnote reference, [1]_; citation reference,
-[CIT2002]_; |substitution|; _`inline internal target`.
-
-Directive Quick Reference
-=========================
-See <http://docutils.sf.net/docs/ref/rst/directives.html> for full info.
-
-================ ============================================================
-Directive Name Description (Docutils version added to, in [brackets])
-================ ============================================================
-attention Specific admonition; also "caution", "danger",
- "error", "hint", "important", "note", "tip", "warning"
-admonition Generic titled admonition: ``.. admonition:: By The Way``
-image ``.. image:: picture.png``; many options possible
-figure Like "image", but with optional caption and legend
-topic ``.. topic:: Title``; like a mini section
-sidebar ``.. sidebar:: Title``; like a mini parallel document
-parsed-literal A literal block with parsed inline markup
-rubric ``.. rubric:: Informal Heading``
-epigraph Block quote with class="epigraph"
-highlights Block quote with class="highlights"
-pull-quote Block quote with class="pull-quote"
-compound Compound paragraphs [0.3.6]
-table Create a titled table [0.3.1]
-list-table Create a table from a uniform two-level bullet list [0.3.8]
-csv-table Create a table from CSV data (requires Python 2.3+) [0.3.4]
-contents Generate a table of contents
-sectnum Automatically number sections, subsections, etc.
-header, footer Create document decorations [0.3.8]
-target-notes Create an explicit footnote for each external target
-meta HTML-specific metadata
-include Read an external reST file as if it were inline
-raw Non-reST data passed untouched to the Writer
-replace Replacement text for substitution definitions
-unicode Unicode character code conversion for substitution defs
-class Set a "class" attribute on the next element
-role Create a custom interpreted text role [0.3.2]
-================ ============================================================
-
-Interpreted Text Role Quick Reference
-=====================================
-See <http://docutils.sf.net/docs/ref/rst/roles.html> for full info.
-
-================ ============================================================
-Role Name Description
-================ ============================================================
-emphasis Equivalent to *emphasis*
-literal Equivalent to ``literal`` but processes backslash escapes
-PEP Reference to a numbered Python Enhancement Proposal
-RFC Reference to a numbered Internet Request For Comments
-raw For non-reST data; cannot be used directly (see docs) [0.3.6]
-strong Equivalent to **strong**
-sub Subscript
-sup Superscript
-title Title reference (book, etc.); standard default role
-================ ============================================================
diff --git a/docutils/docs/user/rst/demo.txt b/docutils/docs/user/rst/demo.txt
deleted file mode 100644
index 7e57b6bad..000000000
--- a/docutils/docs/user/rst/demo.txt
+++ /dev/null
@@ -1,550 +0,0 @@
-.. This is a comment. Note how any initial comments are moved by
- transforms to after the document title, subtitle, and docinfo.
-
-================================
- reStructuredText Demonstration
-================================
-
-.. Above is the document title, and below is the subtitle.
- They are transformed from section titles after parsing.
-
---------------------------------
- Examples of Syntax Constructs
---------------------------------
-
-.. bibliographic fields (which also require a transform):
-
-:Author: David Goodger
-:Address: 123 Example Street
- Example, EX Canada
- A1B 2C3
-:Contact: goodger@users.sourceforge.net
-:Authors: Me; Myself; I
-:organization: humankind
-:date: $Date$
-:status: This is a "work in progress"
-:revision: $Revision$
-:version: 1
-:copyright: This document has been placed in the public domain. You
- may do with it as you wish. You may copy, modify,
- redistribute, reattribute, sell, buy, rent, lease,
- destroy, or improve it, quote it at length, excerpt,
- incorporate, collate, fold, staple, or mutilate it, or do
- anything else to it that your or anyone else's heart
- desires.
-:field name: This is a generic bibliographic field.
-:field name 2:
- Generic bibliographic fields may contain multiple body elements.
-
- Like this.
-
-:Dedication:
-
- For Docutils users & co-developers.
-
-:abstract:
-
- This document is a demonstration of the reStructuredText markup
- language, containing examples of all basic reStructuredText
- constructs and many advanced constructs.
-
-.. meta::
- :keywords: reStructuredText, demonstration, demo, parser
- :description lang=en: A demonstration of the reStructuredText
- markup language, containing examples of all basic
- constructs and many advanced constructs.
-
-.. contents:: Table of Contents
-.. section-numbering::
-
-
-Structural Elements
-===================
-
-Section Title
--------------
-
-That's it, the text just above this line.
-
-Transitions
------------
-
-Here's a transition:
-
----------
-
-It divides the section.
-
-Body Elements
-=============
-
-Paragraphs
-----------
-
-A paragraph.
-
-Inline Markup
-`````````````
-
-Paragraphs contain text and may contain inline markup: *emphasis*,
-**strong emphasis**, ``inline literals``, standalone hyperlinks
-(http://www.python.org), external hyperlinks (Python_), internal
-cross-references (example_), external hyperlinks with embedded URIs
-(`Python web site <http://www.python.org>`__), footnote references
-(manually numbered [1]_, anonymous auto-numbered [#]_, labeled
-auto-numbered [#label]_, or symbolic [*]_), citation references
-([CIT2002]_), substitution references (|example|), and _`inline
-hyperlink targets` (see Targets_ below for a reference back to here).
-Character-level inline markup is also possible (although exceedingly
-ugly!) in *re*\ ``Structured``\ *Text*. Problems are indicated by
-|problematic| text (generated by processing errors; this one is
-intentional).
-
-The default role for interpreted text is `Title Reference`. Here are
-some explicit interpreted text roles: a PEP reference (:PEP:`287`); an
-RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`;
-and explicit roles for :emphasis:`standard` :strong:`inline`
-:literal:`markup`.
-
-.. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
-
-Let's test wrapping and whitespace significance in inline literals:
-``This is an example of --inline-literal --text, --including some--
-strangely--hyphenated-words. Adjust-the-width-of-your-browser-window
-to see how the text is wrapped. -- ---- -------- Now note the
-spacing between the words of this sentence (words
-should be grouped in pairs).``
-
-If the ``--pep-references`` option was supplied, there should be a
-live link to PEP 258 here.
-
-Bullet Lists
-------------
-
-- A bullet list
-
- + Nested bullet list.
- + Nested item 2.
-
-- Item 2.
-
- Paragraph 2 of item 2.
-
- * Nested bullet list.
- * Nested item 2.
-
- - Third level.
- - Item 2.
-
- * Nested item 3.
-
-Enumerated Lists
-----------------
-
-1. Arabic numerals.
-
- a) lower alpha)
-
- (i) (lower roman)
-
- A. upper alpha.
-
- I) upper roman)
-
-2. Lists that don't start at 1:
-
- 3. Three
-
- 4. Four
-
- C. C
-
- D. D
-
- iii. iii
-
- iv. iv
-
-#. List items may also be auto-enumerated.
-
-Definition Lists
-----------------
-
-Term
- Definition
-Term : classifier
- Definition paragraph 1.
-
- Definition paragraph 2.
-Term
- Definition
-
-Field Lists
------------
-
-:what: Field lists map field names to field bodies, like database
- records. They are often part of an extension syntax. They are
- an unambiguous variant of RFC 2822 fields.
-
-:how arg1 arg2:
-
- The field marker is a colon, the field name, and a colon.
-
- The field body may contain one or more body elements, indented
- relative to the field marker.
-
-Option Lists
-------------
-
-For listing command-line options:
-
--a command-line option "a"
--b file options can have arguments
- and long descriptions
---long options can be long also
---input=file long options can also have
- arguments
-
---very-long-option
- The description can also start on the next line.
-
- The description may contain multiple body elements,
- regardless of where it starts.
-
--x, -y, -z Multiple options are an "option group".
--v, --verbose Commonly-seen: short & long options.
--1 file, --one=file, --two file
- Multiple options with arguments.
-/V DOS/VMS-style options too
-
-There must be at least two spaces between the option and the
-description.
-
-Literal Blocks
---------------
-
-Literal blocks are indicated with a double-colon ("::") at the end of
-the preceding paragraph (over there ``-->``). They can be indented::
-
- if literal_block:
- text = 'is left as-is'
- spaces_and_linebreaks = 'are preserved'
- markup_processing = None
-
-Or they can be quoted without indentation::
-
->> Great idea!
->
-> Why didn't I think of that?
-
-Line Blocks
------------
-
-| This is a line block. It ends with a blank line.
-| Each new line begins with a vertical bar ("|").
-| Line breaks and initial indents are preserved.
-| Continuation lines are wrapped portions of long lines;
- they begin with a space in place of the vertical bar.
-| The left edge of a continuation line need not be aligned with
- the left edge of the text above it.
-
-| This is a second line block.
-|
-| Blank lines are permitted internally, but they must begin with a "|".
-
-Take it away, Eric the Orchestra Leader!
-
- | A one, two, a one two three four
- |
- | Half a bee, philosophically,
- | must, *ipso facto*, half not be.
- | But half the bee has got to be,
- | *vis a vis* its entity. D'you see?
- |
- | But can a bee be said to be
- | or not to be an entire bee,
- | when half the bee is not a bee,
- | due to some ancient injury?
- |
- | Singing...
-
-Block Quotes
-------------
-
-Block quotes consist of indented body elements:
-
- My theory by A. Elk. Brackets Miss, brackets. This theory goes
- as follows and begins now. All brontosauruses are thin at one
- end, much much thicker in the middle and then thin again at the
- far end. That is my theory, it is mine, and belongs to me and I
- own it, and what it is too.
-
- -- Anne Elk (Miss)
-
-Doctest Blocks
---------------
-
->>> print 'Python-specific usage examples; begun with ">>>"'
-Python-specific usage examples; begun with ">>>"
->>> print '(cut and pasted from interactive Python sessions)'
-(cut and pasted from interactive Python sessions)
-
-Tables
-------
-
-Here's a grid table followed by a simple table:
-
-+------------------------+------------+----------+----------+
-| Header row, column 1 | Header 2 | Header 3 | Header 4 |
-| (header rows optional) | | | |
-+========================+============+==========+==========+
-| body row 1, column 1 | column 2 | column 3 | column 4 |
-+------------------------+------------+----------+----------+
-| body row 2 | Cells may span columns. |
-+------------------------+------------+---------------------+
-| body row 3 | Cells may | - Table cells |
-+------------------------+ span rows. | - contain |
-| body row 4 | | - body elements. |
-+------------------------+------------+----------+----------+
-| body row 5 | Cells may also be | |
-| | empty: ``-->`` | |
-+------------------------+-----------------------+----------+
-
-===== ===== ======
- Inputs Output
------------- ------
- A B A or B
-===== ===== ======
-False False False
-True False True
-False True True
-True True True
-===== ===== ======
-
-Footnotes
----------
-
-.. [1] A footnote contains body elements, consistently indented by at
- least 3 spaces.
-
- This is the footnote's second paragraph.
-
-.. [#label] Footnotes may be numbered, either manually (as in [1]_) or
- automatically using a "#"-prefixed label. This footnote has a
- label so it can be referred to from multiple places, both as a
- footnote reference ([#label]_) and as a hyperlink reference
- (label_).
-
-.. [#] This footnote is numbered automatically and anonymously using a
- label of "#" only.
-
-.. [*] Footnotes may also use symbols, specified with a "*" label.
- Here's a reference to the next footnote: [*]_.
-
-.. [*] This footnote shows the next symbol in the sequence.
-
-.. [4] Here's an unreferenced footnote, with a reference to a
- nonexistent footnote: [5]_.
-
-Citations
----------
-
-.. [CIT2002] Citations are text-labeled footnotes. They may be
- rendered separately and differently from footnotes.
-
-Here's a reference to the above, [CIT2002]_, and a [nonexistent]_
-citation.
-
-Targets
--------
-
-.. _example:
-
-This paragraph is pointed to by the explicit "example" target. A
-reference can be found under `Inline Markup`_, above. `Inline
-hyperlink targets`_ are also possible.
-
-Section headers are implicit targets, referred to by name. See
-Targets_, which is a subsection of `Body Elements`_.
-
-Explicit external targets are interpolated into references such as
-"Python_".
-
-.. _Python: http://www.python.org/
-
-Targets may be indirect and anonymous. Thus `this phrase`__ may also
-refer to the Targets_ section.
-
-__ Targets_
-
-Here's a `hyperlink reference without a target`_, which generates an
-error.
-
-Duplicate Target Names
-``````````````````````
-
-Duplicate names in section headers or other implicit targets will
-generate "info" (level-1) system messages. Duplicate names in
-explicit targets will generate "warning" (level-2) system messages.
-
-Duplicate Target Names
-``````````````````````
-
-Since there are two "Duplicate Target Names" section headers, we
-cannot uniquely refer to either of them by name. If we try to (like
-this: `Duplicate Target Names`_), an error is generated.
-
-Directives
-----------
-
-.. contents:: :local:
-
-These are just a sample of the many reStructuredText Directives. For
-others, please see
-http://docutils.sourceforge.net/docs/ref/rst/directives.html.
-
-Document Parts
-``````````````
-
-An example of the "contents" directive can be seen above this section
-(a local, untitled table of contents_) and at the beginning of the
-document (a document-wide `table of contents`_).
-
-Images
-``````
-
-An image directive (also clickable -- a hyperlink reference):
-
-.. image:: images/title.png
- :target: directives_
-
-A figure directive:
-
-.. figure:: images/title.png
- :alt: reStructuredText, the markup syntax
-
- A figure is an image with a caption and/or a legend:
-
- +------------+-----------------------------------------------+
- | re | Revised, revisited, based on 're' module. |
- +------------+-----------------------------------------------+
- | Structured | Structure-enhanced text, structuredtext. |
- +------------+-----------------------------------------------+
- | Text | Well it is, isn't it? |
- +------------+-----------------------------------------------+
-
- This paragraph is also part of the legend.
-
-Admonitions
-```````````
-
-.. Attention:: Directives at large.
-
-.. Caution::
-
- Don't take any wooden nickels.
-
-.. DANGER:: Mad scientist at work!
-
-.. Error:: Does not compute.
-
-.. Hint:: It's bigger than a bread box.
-
-.. Important::
- - Wash behind your ears.
- - Clean up your room.
- - Call your mother.
- - Back up your data.
-
-.. Note:: This is a note.
-
-.. Tip:: 15% if the service is good.
-
-.. WARNING:: Strong prose may provoke extreme mental exertion.
- Reader discretion is strongly advised.
-
-.. admonition:: And, by the way...
-
- You can make up your own admonition too.
-
-Topics, Sidebars, and Rubrics
-`````````````````````````````
-
-.. sidebar:: Sidebar Title
- :subtitle: Optional Subtitle
-
- This is a sidebar. It is for text outside the flow of the main
- text.
-
- .. rubric:: This is a rubric inside a sidebar
-
- Sidebars often appears beside the main text with a border and
- background color.
-
-.. topic:: Topic Title
-
- This is a topic.
-
-.. rubric:: This is a rubric
-
-Target Footnotes
-````````````````
-
-.. target-notes::
-
-Replacement Text
-````````````````
-
-I recommend you try |Python|_.
-
-.. |Python| replace:: Python, *the* best language around
-
-Compound Paragraph
-``````````````````
-
-.. compound::
-
- This paragraph contains a literal block::
-
- Connecting... OK
- Transmitting data... OK
- Disconnecting... OK
-
- and thus consists of a simple paragraph, a literal block, and
- another simple paragraph. Nonetheless it is semantically *one*
- paragraph.
-
-This construct is called a *compound paragraph* and can be produced
-with the "compound" directive.
-
-Substitution Definitions
-------------------------
-
-An inline image (|example|) example:
-
-.. |EXAMPLE| image:: images/biohazard.png
-
-(Substitution definitions are not visible in the HTML source.)
-
-Comments
---------
-
-Here's one:
-
-.. Comments begin with two dots and a space. Anything may
- follow, except for the syntax of footnotes, hyperlink
- targets, directives, or substitution definitions.
-
- Double-dashes -- "--" -- must be escaped somehow in HTML output.
-
-(View the HTML source to see the comment.)
-
-Error Handling
-==============
-
-Any errors caught during processing will generate system messages.
-
-There should be five messages in the following, auto-generated
-section, "Docutils System Messages":
-
-.. section should be added by Docutils automatically
diff --git a/docutils/docs/user/rst/images/ball1.gif b/docutils/docs/user/rst/images/ball1.gif
deleted file mode 100644
index 3e14441d9..000000000
--- a/docutils/docs/user/rst/images/ball1.gif
+++ /dev/null
Binary files differ
diff --git a/docutils/docs/user/rst/images/biohazard.png b/docutils/docs/user/rst/images/biohazard.png
deleted file mode 100644
index ae4629d8b..000000000
--- a/docutils/docs/user/rst/images/biohazard.png
+++ /dev/null
Binary files differ
diff --git a/docutils/docs/user/rst/images/title.png b/docutils/docs/user/rst/images/title.png
deleted file mode 100644
index cc6218efe..000000000
--- a/docutils/docs/user/rst/images/title.png
+++ /dev/null
Binary files differ
diff --git a/docutils/docs/user/rst/quickref.html b/docutils/docs/user/rst/quickref.html
deleted file mode 100644
index e391763c2..000000000
--- a/docutils/docs/user/rst/quickref.html
+++ /dev/null
@@ -1,1319 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/html4/loose.dtd">
-
-<html>
- <head>
- <title>Quick reStructuredText</title>
- <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
-
- <style type="text/css"><!--
- a.backref { text-decoration: none ; color: black }
- div.line-block { display: block }
- div.line-block div.line-block { margin-left: 1.5em }
- --></style>
-
- </head>
-
- <body>
- <h1>Quick <i>re</i><font size="+4"><tt>Structured</tt></font><i>Text</i></h1>
-
- <!-- Caveat: if you're reading the HTML for the examples, -->
- <!-- beware that it was hand-generated, not by Docutils/ReST. -->
-
- <p align="right"><em><a href="http://docutils.sourceforge.net/docs/user/rst/quickref.html"
- >http://docutils.sourceforge.net/docs/user/rst/quickref.html</a></em>
- <br><em>Being a cheat-sheet for reStructuredText</em>
- <br><em>Updated $Date$</em>
-
- <blockquote>
- <p>Copyright: This document has been placed in the public domain.
- </blockquote>
-
-
- <p>The full details of the markup may be found on the
- <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>
- page. This document is just intended as a reminder.
-
- <p>Links that look like "(<a href="#details">details</a>)" point
- into the HTML version of the full <a
- href="../../ref/rst/restructuredtext.html">reStructuredText
- specification</a> document. These are relative links; if they
- don't work, please use the <a
- href="http://docutils.sourceforge.net/docs/user/rst/quickref.html"
- >master "Quick reStructuredText"</a> document.
-
- <h2><a name="contents">Contents</a></h2>
-
- <ul>
- <li><a href="#inline-markup">Inline Markup</a></li>
- <li><a href="#escaping">Escaping with Backslashes</a></li>
- <li><a href="#section-structure">Section Structure</a></li>
- <li><a href="#paragraphs">Paragraphs</a></li>
- <li><a href="#bullet-lists">Bullet Lists</a></li>
- <li><a href="#enumerated-lists">Enumerated Lists</a></li>
- <li><a href="#definition-lists">Definition Lists</a></li>
- <li><a href="#field-lists">Field Lists</a></li>
- <li><a href="#option-lists">Option Lists</a></li>
- <li><a href="#literal-blocks">Literal Blocks</a></li>
- <li><a href="#line-blocks">Line Blocks</a></li>
- <li><a href="#block-quotes">Block Quotes</a></li>
- <li><a href="#doctest-blocks">Doctest Blocks</a></li>
- <li><a href="#tables">Tables</a></li>
- <li><a href="#transitions">Transitions</a></li>
- <li><a href="#explicit-markup">Explicit Markup</a>
- <ul>
- <li><a href="#footnotes">Footnotes</a></li>
- <li><a href="#citations">Citations</a></li>
- <li><a href="#hyperlink-targets">Hyperlink Targets</a>
- <ul>
- <li><a href="#external-hyperlink-targets">External Hyperlink Targets</a></li>
- <li><a href="#internal-hyperlink-targets">Internal Hyperlink Targets</a></li>
- <li><a href="#indirect-hyperlink-targets">Indirect Hyperlink Targets</a></li>
- <li><a href="#implicit-hyperlink-targets">Implicit Hyperlink Targets</a></li>
- </ul></li>
- <li><a href="#directives">Directives</a></li>
- <li><a href="#substitution-references-and-definitions">Substitution References and Definitions</a></li>
- <li><a href="#comments">Comments</a></li>
- </ul></li>
- <li><a href="#getting-help">Getting Help</a></li>
- </ul>
-
- <h2><a href="#contents" name="inline-markup" class="backref"
- >Inline Markup</a></h2>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#inline-markup">details</a>)
-
- <p>Inline markup allows words and phrases within text to have
- character styles (like italics and boldface) and functionality
- (like hyperlinks).
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th>Plain text
- <th>Typical result
- <th>Notes
- </thead>
- <tbody>
- <tr valign="top">
- <td nowrap><samp>*emphasis*</samp>
- <td><em>emphasis</em>
- <td>Normally rendered as italics.
-
- <tr valign="top">
- <td nowrap><samp>**strong&nbsp;emphasis**</samp>
- <td><strong>strong emphasis</strong>
- <td>Normally rendered as boldface.
-
- <tr valign="top">
- <td nowrap><samp>`interpreted&nbsp;text`</samp>
- <td>(see note at right)
- <td>The rendering and <em>meaning</em> of interpreted text is
- domain- or application-dependent. It can be used for things
- like index entries or explicit descriptive markup (like program
- identifiers).
-
- <tr valign="top">
- <td nowrap><samp>``inline&nbsp;literal``</samp>
- <td><code>inline&nbsp;literal</code>
- <td>Normally rendered as monospaced text. Spaces should be
- preserved, but line breaks will not be.
-
- <tr valign="top">
- <td nowrap><samp>reference_</samp>
- <td><a href="#hyperlink-targets">reference</a>
- <td>A simple, one-word hyperlink reference. See <a
- href="#hyperlinks" >Hyperlinks</a>.
-
- <tr valign="top">
- <td nowrap><samp>`phrase reference`_</samp>
- <td><a href="#hyperlink-targets">phrase reference</a>
- <td>A hyperlink reference with spaces or punctuation needs to be
- quoted with backquotes. See <a
- href="#hyperlink-targets">Hyperlinks</a>.
-
- <tr valign="top">
- <td nowrap><samp>anonymous__</samp>
- <td><a href="#hyperlink-targets">anonymous</a>
- <td>With two underscores instead of one, both simple and phrase
- references may be anonymous (the reference text is not repeated
- at the target). See <a
- href="#hyperlink-targets">Hyperlinks</a>.
-
- <tr valign="top">
- <td nowrap><samp>_`inline internal target`</samp>
- <td><a name="inline-internal-target">inline internal target</a>
- <td>A crossreference target within text.
- See <a href="#hyperlink-targets">Hyperlinks</a>.
-
- <tr valign="top">
- <td nowrap><samp>|substitution reference|</samp>
- <td>(see note at right)
- <td>The result is substituted in from the <a
- href="#substitution-references-and-definitions">substitution
- definition</a>. It could be text, an image, a hyperlink, or a
- combination of these and others.
-
- <tr valign="top">
- <td nowrap><samp>footnote reference [1]_</samp>
- <td>footnote reference <sup><a href="#footnotes">1</a></sup>
- <td>See <a href="#footnotes">Footnotes</a>.
-
- <tr valign="top">
- <td nowrap><samp>citation reference [CIT2002]_</samp>
- <td>citation reference <a href="#citations">[CIT2002]</a>
- <td>See <a href="#citations">Citations</a>.
-
- <tr valign="top">
- <td nowrap><samp>http://docutils.sf.net/</samp>
- <td><a href="http://docutils.sf.net/">http://docutils.sf.net/</a>
- <td>A standalone hyperlink.
-
- </table>
-
- <p>Asterisk, backquote, vertical bar, and underscore are inline
- delimiter characters. Asterisk, backquote, and vertical bar act
- like quote marks; matching characters surround the marked-up word
- or phrase, whitespace or other quoting is required outside them,
- and there can't be whitespace just inside them. If you want to use
- inline delimiter characters literally, <a href="#escaping">escape
- (with backslash)</a> or quote them (with double backquotes; i.e.
- use inline literals).
-
- <p>In detail, the reStructuredText specification says that in
- inline markup, the following rules apply to start-strings and
- end-strings (inline markup delimiters):
-
- <ol>
- <li>The start-string must start a text block or be
- immediately preceded by whitespace or any of&nbsp;
- <samp>' " ( [ {</samp> or&nbsp;<samp>&lt;</samp>.
- <li>The start-string must be immediately followed by non-whitespace.
- <li>The end-string must be immediately preceded by non-whitespace.
- <li>The end-string must end a text block (end of document or
- followed by a blank line) or be immediately followed by whitespace
- or any of&nbsp;<samp>' " . , : ; ! ? - ) ] } / \</samp>
- or&nbsp;<samp>&gt;</samp>.
- <li>If a start-string is immediately preceded by one of&nbsp;
- <samp>' " ( [ {</samp> or&nbsp;<samp>&lt;</samp>, it must not be
- immediately followed by the corresponding character from&nbsp;
- <samp>' " ) ] }</samp> or&nbsp;<samp>&gt;</samp>.
- <li>An end-string must be separated by at least one
- character from the start-string.
- <li>An <a href="#escaping">unescaped</a> backslash preceding a
- start-string or end-string will disable markup recognition, except
- for the end-string of inline literals.
- </ol>
-
- <p>Also remember that inline markup may not be nested (well,
- except that inline literals can contain any of the other inline
- markup delimiter characters, but that doesn't count because
- nothing is processed).
-
- <h2><a href="#contents" name="escaping" class="backref"
- >Escaping with Backslashes</a></h2>
-
- <p>(<a
- href="../../ref/rst/restructuredtext.html#escaping-mechanism">details</a>)
-
- <p>reStructuredText uses backslashes ("\") to override the special
- meaning given to markup characters and get the literal characters
- themselves. To get a literal backslash, use an escaped backslash
- ("\\"). For example:
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Raw reStructuredText
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top"><td>
- <samp>*escape*&nbsp;``with``&nbsp;"\"</samp>
- <td><em>escape</em> <samp>with</samp> ""
- <tr valign="top"><td>
- <samp>\*escape*&nbsp;\``with``&nbsp;"\\"</samp>
- <td>*escape* ``with`` "\"
- </table>
-
- <p>In Python strings it will, of course, be necessary
- to escape any backslash characters so that they actually
- <em>reach</em> reStructuredText.
- The simplest way to do this is to use raw strings:
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Python string
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top"><td>
- <samp>r"""\*escape*&nbsp;\`with`&nbsp;"\\""""</samp>
- <td>*escape* `with` "\"
- <tr valign="top"><td>
- <samp>&nbsp;"""\\*escape*&nbsp;\\`with`&nbsp;"\\\\""""</samp>
- <td>*escape* `with` "\"
- <tr valign="top"><td>
- <samp>&nbsp;"""\*escape*&nbsp;\`with`&nbsp;"\\""""</samp>
- <td><em>escape</em> with ""
- </table>
-
- <h2><a href="#contents" name="section-structure" class="backref"
- >Section Structure</a></h2>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#sections">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td>
-<samp>=====</samp>
-<br><samp>Title</samp>
-<br><samp>=====</samp>
-<br><samp>Subtitle</samp>
-<br><samp>--------</samp>
-<br><samp>Titles&nbsp;are&nbsp;underlined&nbsp;(or&nbsp;over-</samp>
-<br><samp>and&nbsp;underlined)&nbsp;with&nbsp;a&nbsp;printing</samp>
-<br><samp>nonalphanumeric&nbsp;7-bit&nbsp;ASCII</samp>
-<br><samp>character.&nbsp;Recommended&nbsp;choices</samp>
-<br><samp>are&nbsp;"``=&nbsp;-&nbsp;`&nbsp;:&nbsp;'&nbsp;"&nbsp;~&nbsp;^&nbsp;_&nbsp;*&nbsp;+&nbsp;#&nbsp;&lt;&nbsp;&gt;``".</samp>
-<br><samp>The&nbsp;underline/overline&nbsp;must&nbsp;be&nbsp;at</samp>
-<br><samp>least&nbsp;as&nbsp;long&nbsp;as&nbsp;the&nbsp;title&nbsp;text.</samp>
-<br><samp></samp>
-<br><samp>A&nbsp;lone&nbsp;top-level&nbsp;(sub)section</samp>
-<br><samp>is&nbsp;lifted&nbsp;up&nbsp;to&nbsp;be&nbsp;the&nbsp;document's</samp>
-<br><samp>(sub)title.</samp>
-
- <td>
- <font size="+2"><strong>Title</strong></font>
- <p><font size="+1"><strong>Subtitle</strong></font>
- <p>Titles are underlined (or over-
- and underlined) with a printing
- nonalphanumeric 7-bit ASCII
- character. Recommended choices
- are "<samp>= - ` : ' " ~ ^ _ * + # &lt; &gt;</samp>".
- The underline/overline must be at
- least as long as the title text.
- <p>A lone top-level (sub)section is
- lifted up to be the document's
- (sub)title.
- </table>
-
- <h2><a href="#contents" name="paragraphs" class="backref"
- >Paragraphs</a></h2>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#paragraphs">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td>
-<p><samp>This&nbsp;is&nbsp;a&nbsp;paragraph.</samp>
-
-<p><samp>Paragraphs&nbsp;line&nbsp;up&nbsp;at&nbsp;their&nbsp;left</samp>
-<br><samp>edges,&nbsp;and&nbsp;are&nbsp;normally&nbsp;separated</samp>
-<br><samp>by&nbsp;blank&nbsp;lines.</samp>
-
- <td>
- <p>This is a paragraph.
-
- <p>Paragraphs line up at their left edges, and are normally
- separated by blank lines.
-
- </table>
-
- <h2><a href="#contents" name="bullet-lists" class="backref"
- >Bullet Lists</a></h2>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#bullet-lists">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td>
-<samp>Bullet&nbsp;lists:</samp>
-
-<p><samp>-&nbsp;This&nbsp;is&nbsp;item&nbsp;1</samp>
-<br><samp>-&nbsp;This&nbsp;is&nbsp;item&nbsp;2</samp>
-
-<p><samp>-&nbsp;Bullets&nbsp;are&nbsp;"-",&nbsp;"*"&nbsp;or&nbsp;"+".</samp>
-<br><samp>&nbsp;&nbsp;Continuing&nbsp;text&nbsp;must&nbsp;be&nbsp;aligned</samp>
-<br><samp>&nbsp;&nbsp;after&nbsp;the&nbsp;bullet&nbsp;and&nbsp;whitespace.</samp>
-
-<p><samp>Note&nbsp;that&nbsp;a&nbsp;blank&nbsp;line&nbsp;is&nbsp;required</samp>
-<br><samp>before&nbsp;the&nbsp;first&nbsp;item&nbsp;and&nbsp;after&nbsp;the</samp>
-<br><samp>last,&nbsp;but&nbsp;is&nbsp;optional&nbsp;between&nbsp;items.</samp>
- <td>Bullet lists:
- <ul>
- <li>This is item 1
- <li>This is item 2
- <li>Bullets are "-", "*" or "+".
- Continuing text must be aligned
- after the bullet and whitespace.
- </ul>
- <p>Note that a blank line is required before the first
- item and after the last, but is optional between items.
- </table>
-
- <h2><a href="#contents" name="enumerated-lists" class="backref"
- >Enumerated Lists</a></h2>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#enumerated-lists">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td>
-<samp>Enumerated&nbsp;lists:</samp>
-
-<p><samp>3.&nbsp;This&nbsp;is&nbsp;the&nbsp;first&nbsp;item</samp>
-<br><samp>4.&nbsp;This&nbsp;is&nbsp;the&nbsp;second&nbsp;item</samp>
-<br><samp>5.&nbsp;Enumerators&nbsp;are&nbsp;arabic&nbsp;numbers,</samp>
-<br><samp>&nbsp;&nbsp;&nbsp;single&nbsp;letters,&nbsp;or&nbsp;roman&nbsp;numerals</samp>
-<br><samp>6.&nbsp;List&nbsp;items&nbsp;should&nbsp;be&nbsp;sequentially</samp>
-<br><samp>&nbsp;&nbsp;&nbsp;numbered,&nbsp;but&nbsp;need&nbsp;not&nbsp;start&nbsp;at&nbsp;1</samp>
-<br><samp>&nbsp;&nbsp;&nbsp;(although&nbsp;not&nbsp;all&nbsp;formatters&nbsp;will</samp>
-<br><samp>&nbsp;&nbsp;&nbsp;honour&nbsp;the&nbsp;first&nbsp;index).</samp>
-<br><samp>#.&nbsp;This&nbsp;item&nbsp;is&nbsp;auto-enumerated</samp>
- <td>Enumerated lists:
- <ol type="1">
- <li value="3">This is the first item
- <li>This is the second item
- <li>Enumerators are arabic numbers, single letters,
- or roman numerals
- <li>List items should be sequentially numbered,
- but need not start at 1 (although not all
- formatters will honour the first index).
- <li>This item is auto-enumerated
- </ol>
- </table>
-
- <h2><a href="#contents" name="definition-lists" class="backref"
- >Definition Lists</a></h2>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#definition-lists">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td>
-<samp>Definition&nbsp;lists:</samp>
-<br>
-<br><samp>what</samp>
-<br><samp>&nbsp;&nbsp;Definition&nbsp;lists&nbsp;associate&nbsp;a&nbsp;term&nbsp;with</samp>
-<br><samp>&nbsp;&nbsp;a&nbsp;definition.</samp>
-<br>
-<br><samp>how</samp>
-<br><samp>&nbsp;&nbsp;The&nbsp;term&nbsp;is&nbsp;a&nbsp;one-line&nbsp;phrase,&nbsp;and&nbsp;the</samp>
-<br><samp>&nbsp;&nbsp;definition&nbsp;is&nbsp;one&nbsp;or&nbsp;more&nbsp;paragraphs&nbsp;or</samp>
-<br><samp>&nbsp;&nbsp;body&nbsp;elements,&nbsp;indented&nbsp;relative&nbsp;to&nbsp;the</samp>
-<br><samp>&nbsp;&nbsp;term.&nbsp;Blank&nbsp;lines&nbsp;are&nbsp;not&nbsp;allowed</samp>
-<br><samp>&nbsp;&nbsp;between&nbsp;term&nbsp;and&nbsp;definition.</samp>
- <td>Definition lists:
- <dl>
- <dt><strong>what</strong>
- <dd>Definition lists associate a term with
- a definition.
-
- <dt><strong>how</strong>
- <dd>The term is a one-line phrase, and the
- definition is one or more paragraphs or
- body elements, indented relative to the
- term. Blank lines are not allowed
- between term and definition.
- </dl>
- </table>
-
- <h2><a href="#contents" name="field-lists" class="backref"
- >Field Lists</a></h2>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#field-lists">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td>
-<samp>:Authors:</samp>
-<br><samp>&nbsp;&nbsp;&nbsp;&nbsp;Tony&nbsp;J.&nbsp;(Tibs)&nbsp;Ibbs,</samp>
-<br><samp>&nbsp;&nbsp;&nbsp;&nbsp;David&nbsp;Goodger</samp>
-
-<p><samp>&nbsp;&nbsp;&nbsp;&nbsp;(and&nbsp;sundry&nbsp;other&nbsp;good-natured&nbsp;folks)</samp>
-
-<p><samp>:Version:&nbsp;1.0&nbsp;of&nbsp;2001/08/08</samp>
-<br><samp>:Dedication:&nbsp;To&nbsp;my&nbsp;father.</samp>
- <td>
- <table>
- <tr valign="top">
- <td><strong>Authors:</strong>
- <td>Tony J. (Tibs) Ibbs,
- David Goodger
- <tr><td><td>(and sundry other good-natured folks)
- <tr><td><strong>Version:</strong><td>1.0 of 2001/08/08
- <tr><td><strong>Dedication:</strong><td>To my father.
- </table>
- </table>
-
- <p>Field lists are used as part of an extension syntax, such as
- options for <a href="#directives">directives</a>, or database-like
- records meant for further processing. Field lists may also be
- used as generic two-column table constructs in documents.
-
- <h2><a href="#contents" name="option-lists" class="backref"
- >Option Lists</a></h2>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#option-lists">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td>
- <p><samp>
--a&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;command-line&nbsp;option&nbsp;"a"
-<br>-b&nbsp;file&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;options&nbsp;can&nbsp;have&nbsp;arguments
-<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;and&nbsp;long&nbsp;descriptions
-<br>--long&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;options&nbsp;can&nbsp;be&nbsp;long&nbsp;also
-<br>--input=file&nbsp;&nbsp;long&nbsp;options&nbsp;can&nbsp;also&nbsp;have
-<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;arguments
-<br>/V&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;DOS/VMS-style&nbsp;options&nbsp;too
-</samp>
-
- <td>
- <table border="0" width="100%">
- <tbody valign="top">
- <tr>
- <td width="30%"><samp>-a</samp>
- <td>command-line option "a"
- <tr>
- <td><samp>-b <i>file</i></samp>
- <td>options can have arguments and long descriptions
- <tr>
- <td><samp>--long</samp>
- <td>options can be long also
- <tr>
- <td><samp>--input=<i>file</i></samp>
- <td>long options can also have arguments
- <tr>
- <td><samp>/V</samp>
- <td>DOS/VMS-style options too
- </table>
- </table>
-
- <p>There must be at least two spaces between the option and the
- description.
-
- <h2><a href="#contents" name="literal-blocks" class="backref"
- >Literal Blocks</a></h2>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#literal-blocks">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td>
-<samp>A&nbsp;paragraph&nbsp;containing&nbsp;only&nbsp;two&nbsp;colons</samp>
-<br><samp>indicates&nbsp;that&nbsp;the&nbsp;following&nbsp;indented</samp>
-<br><samp>or&nbsp;quoted&nbsp;text&nbsp;is&nbsp;a&nbsp;literal&nbsp;block.</samp>
-<br>
-<br><samp>::</samp>
-<br>
-<br><samp>&nbsp;&nbsp;Whitespace,&nbsp;newlines,&nbsp;blank&nbsp;lines,&nbsp;and</samp>
-<br><samp>&nbsp;&nbsp;all&nbsp;kinds&nbsp;of&nbsp;markup&nbsp;(like&nbsp;*this*&nbsp;or</samp>
-<br><samp>&nbsp;&nbsp;\this)&nbsp;is&nbsp;preserved&nbsp;by&nbsp;literal&nbsp;blocks.</samp>
-<br>
-<br><samp>&nbsp;&nbsp;The&nbsp;paragraph&nbsp;containing&nbsp;only&nbsp;'::'</samp>
-<br><samp>&nbsp;&nbsp;will&nbsp;be&nbsp;omitted&nbsp;from&nbsp;the&nbsp;result.</samp>
-<br>
-<br><samp>The&nbsp;``::``&nbsp;may&nbsp;be&nbsp;tacked&nbsp;onto&nbsp;the&nbsp;very</samp>
-<br><samp>end&nbsp;of&nbsp;any&nbsp;paragraph.&nbsp;The&nbsp;``::``&nbsp;will&nbsp;be</samp>
-<br><samp>omitted&nbsp;if&nbsp;it&nbsp;is&nbsp;preceded&nbsp;by&nbsp;whitespace.</samp>
-<br><samp>The&nbsp;``::``&nbsp;will&nbsp;be&nbsp;converted&nbsp;to&nbsp;a&nbsp;single</samp>
-<br><samp>colon&nbsp;if&nbsp;preceded&nbsp;by&nbsp;text,&nbsp;like&nbsp;this::</samp>
-<br>
-<br><samp>&nbsp;&nbsp;It's&nbsp;very&nbsp;convenient&nbsp;to&nbsp;use&nbsp;this&nbsp;form.</samp>
-<br>
-<br><samp>Literal&nbsp;blocks&nbsp;end&nbsp;when&nbsp;text&nbsp;returns&nbsp;to</samp>
-<br><samp>the&nbsp;preceding&nbsp;paragraph's&nbsp;indentation.</samp>
-<br><samp>This&nbsp;means&nbsp;that&nbsp;something&nbsp;like&nbsp;this</samp>
-<br><samp>is&nbsp;possible::</samp>
-<br>
-<br><samp>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;We&nbsp;start&nbsp;here</samp>
-<br><samp>&nbsp;&nbsp;&nbsp;&nbsp;and&nbsp;continue&nbsp;here</samp>
-<br><samp>&nbsp;&nbsp;and&nbsp;end&nbsp;here.</samp>
-<br>
-<br><samp>Per-line&nbsp;quoting&nbsp;can&nbsp;also&nbsp;be&nbsp;used&nbsp;on</samp>
-<br><samp>unindented&nbsp;literal&nbsp;blocks:</samp>
-<br>
-<br><samp>&gt;&nbsp;Useful&nbsp;for&nbsp;quotes&nbsp;from&nbsp;email&nbsp;and</samp>
-<br><samp>&gt;&nbsp;for&nbsp;Haskell&nbsp;literate&nbsp;programming.</samp>
-
- <td>
- <p>A paragraph containing only two colons
-indicates that the following indented or quoted
-text is a literal block.
-
- <pre>
- Whitespace, newlines, blank lines, and
- all kinds of markup (like *this* or
- \this) is preserved by literal blocks.
-
- The paragraph containing only '::'
- will be omitted from the result.</pre>
-
- <p>The <samp>::</samp> may be tacked onto the very
-end of any paragraph. The <samp>::</samp> will be
-omitted if it is preceded by whitespace.
-The <samp>::</samp> will be converted to a single
-colon if preceded by text, like this:
-
- <pre>
- It's very convenient to use this form.</pre>
-
- <p>Literal blocks end when text returns to
-the preceding paragraph's indentation.
-This means that something like this is possible:
-
- <pre>
- We start here
- and continue here
- and end here.</pre>
-
- <p>Per-line quoting can also be used on
-unindented literal blocks:
-
- <pre>
- &gt; Useful for quotes from email and
- &gt; for Haskell literate programming.</pre>
- </table>
-
- <h2><a href="#contents" name="line-blocks" class="backref"
- >Line Blocks</a></h2>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#line-blocks">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td>
-<samp>|&nbsp;Line&nbsp;blocks&nbsp;are&nbsp;useful&nbsp;for&nbsp;addresses,</samp>
-<br><samp>|&nbsp;verse,&nbsp;and&nbsp;adornment-free&nbsp;lists.</samp>
-<br><samp>|</samp>
-<br><samp>|&nbsp;Each&nbsp;new&nbsp;line&nbsp;begins&nbsp;with&nbsp;a</samp>
-<br><samp>|&nbsp;vertical&nbsp;bar&nbsp;("|").</samp>
-<br><samp>|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Line&nbsp;breaks&nbsp;and&nbsp;initial&nbsp;indents</samp>
-<br><samp>|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;are&nbsp;preserved.</samp>
-<br><samp>|&nbsp;Continuation&nbsp;lines&nbsp;are&nbsp;wrapped</samp>
-<br><samp>&nbsp;&nbsp;portions&nbsp;of&nbsp;long&nbsp;lines;&nbsp;they&nbsp;begin</samp>
-<br><samp>&nbsp;&nbsp;with&nbsp;spaces&nbsp;in&nbsp;place&nbsp;of&nbsp;vertical&nbsp;bars.</samp>
-
- <td>
- <div class="line-block">
- <div class="line">Line blocks are useful for addresses,</div>
- <div class="line">verse, and adornment-free lists.</div>
- <div class="line"><br /></div>
- <div class="line">Each new line begins with a</div>
- <div class="line">vertical bar ("|").</div>
- <div class="line-block">
- <div class="line">Line breaks and initial indents</div>
- <div class="line">are preserved.</div>
- </div>
- <div class="line">Continuation lines are wrapped portions
- of long lines; they begin
- with spaces in place of vertical bars.</div>
- </div>
- </table>
-
- <h2><a href="#contents" name="block-quotes" class="backref"
- >Block Quotes</a></h2>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#block-quotes">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td>
-<samp>Block&nbsp;quotes&nbsp;are&nbsp;just:</samp>
-
-<p><samp>&nbsp;&nbsp;&nbsp;&nbsp;Indented&nbsp;paragraphs,</samp>
-
-<p><samp>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;and&nbsp;they&nbsp;may&nbsp;nest.</samp>
- <td>
- Block quotes are just:
- <blockquote>
- <p>Indented paragraphs,
- <blockquote>
- <p>and they may nest.
- </blockquote>
- </blockquote>
- </table>
-
- <h2><a href="#contents" name="doctest-blocks" class="backref"
- >Doctest Blocks</a></h2>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#doctest-blocks">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td>
- <p><samp>Doctest&nbsp;blocks&nbsp;are&nbsp;interactive
-<br>Python&nbsp;sessions.&nbsp;They&nbsp;begin&nbsp;with
-<br>"``&gt;&gt;&gt;``"&nbsp;and&nbsp;end&nbsp;with&nbsp;a&nbsp;blank&nbsp;line.</samp>
-
- <p><samp>&gt;&gt;&gt;&nbsp;print&nbsp;"This&nbsp;is&nbsp;a&nbsp;doctest&nbsp;block."
-<br>This&nbsp;is&nbsp;a&nbsp;doctest&nbsp;block.</samp>
-
- <td>
- <p>Doctest blocks are interactive
- Python sessions. They begin with
- "<samp>&gt;&gt;&gt;</samp>" and end with a blank line.
-
- <p><samp>&gt;&gt;&gt;&nbsp;print&nbsp;"This&nbsp;is&nbsp;a&nbsp;doctest&nbsp;block."
-<br>This&nbsp;is&nbsp;a&nbsp;doctest&nbsp;block.</samp>
- </table>
-
- <p>"The <a
- href="http://www.python.org/doc/current/lib/module-doctest.html">doctest</a>
- module searches a module's docstrings for text that looks like an
- interactive Python session, then executes all such sessions to
- verify they still work exactly as shown." (From the doctest docs.)
-
- <h2><a href="#contents" name="tables" class="backref"
- >Tables</a></h2>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#tables">details</a>)
-
- <p>There are two syntaxes for tables in reStructuredText. Grid
- tables are complete but cumbersome to create. Simple tables are
- easy to create but limited (no row spans, etc.).</p>
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td>
-<p><samp>Grid table:</samp></p>
-
-<p><samp>+------------+------------+-----------+</samp>
-<br><samp>|&nbsp;Header&nbsp;1&nbsp;&nbsp;&nbsp;|&nbsp;Header&nbsp;2&nbsp;&nbsp;&nbsp;|&nbsp;Header&nbsp;3&nbsp;&nbsp;|</samp>
-<br><samp>+============+============+===========+</samp>
-<br><samp>|&nbsp;body&nbsp;row&nbsp;1&nbsp;|&nbsp;column&nbsp;2&nbsp;&nbsp;&nbsp;|&nbsp;column&nbsp;3&nbsp;&nbsp;|</samp>
-<br><samp>+------------+------------+-----------+</samp>
-<br><samp>|&nbsp;body&nbsp;row&nbsp;2&nbsp;|&nbsp;Cells&nbsp;may&nbsp;span&nbsp;columns.|</samp>
-<br><samp>+------------+------------+-----------+</samp>
-<br><samp>|&nbsp;body&nbsp;row&nbsp;3&nbsp;|&nbsp;Cells&nbsp;may&nbsp;&nbsp;|&nbsp;-&nbsp;Cells&nbsp;&nbsp;&nbsp;|</samp>
-<br><samp>+------------+&nbsp;span&nbsp;rows.&nbsp;|&nbsp;-&nbsp;contain&nbsp;|</samp>
-<br><samp>|&nbsp;body&nbsp;row&nbsp;4&nbsp;|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;-&nbsp;blocks.&nbsp;|</samp>
-<br><samp>+------------+------------+-----------+</samp></p>
- <td>
- <p>Grid table:</p>
- <table border="1">
- <thead valign="bottom">
- <tr>
- <th>Header 1
- <th>Header 2
- <th>Header 3
- </tr>
- </thead>
- <tbody valign="top">
- <tr>
- <td>body row 1
- <td>column 2
- <td>column 3
- </tr>
- <tr>
- <td>body row 2
- <td colspan="2">Cells may span columns.
- </tr>
- <tr>
- <td>body row 3
- <td rowspan="2">Cells may<br>span rows.
- <td rowspan="2">
- <ul>
- <li>Cells
- <li>contain
- <li>blocks.
- </ul>
- </tr>
- <tr>
- <td>body row 4
- </tr>
- </table>
- <tr valign="top">
- <td>
-<p><samp>Simple table:</samp></p>
-
-<p><samp>=====&nbsp;&nbsp;=====&nbsp;&nbsp;======</samp>
-<br><samp>&nbsp;&nbsp;&nbsp;Inputs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Output</samp>
-<br><samp>------------&nbsp;&nbsp;------</samp>
-<br><samp>&nbsp;&nbsp;A&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;B&nbsp;&nbsp;&nbsp;&nbsp;A&nbsp;or&nbsp;B</samp>
-<br><samp>=====&nbsp;&nbsp;=====&nbsp;&nbsp;======</samp>
-<br><samp>False&nbsp;&nbsp;False&nbsp;&nbsp;False</samp>
-<br><samp>True&nbsp;&nbsp;&nbsp;False&nbsp;&nbsp;True</samp>
-<br><samp>False&nbsp;&nbsp;True&nbsp;&nbsp;&nbsp;True</samp>
-<br><samp>True&nbsp;&nbsp;&nbsp;True&nbsp;&nbsp;&nbsp;True</samp>
-<br><samp>=====&nbsp;&nbsp;=====&nbsp;&nbsp;======</samp></p>
-
- <td>
- <p>Simple table:</p>
- <table border="1">
- <colgroup>
- <col width="31%">
- <col width="31%">
- <col width="38%">
- </colgroup>
- <thead valign="bottom">
- <tr>
- <th colspan="2">Inputs
- <th>Output
- <tr>
- <th>A
- <th>B
- <th>A or B
- <tbody valign="top">
- <tr>
- <td>False
- <td>False
- <td>False
- <tr>
- <td>True
- <td>False
- <td>True
- <tr>
- <td>False
- <td>True
- <td>True
- <tr>
- <td>True
- <td>True
- <td>True
- </table>
-
- </table>
-
- <h2><a href="#contents" name="transitions" class="backref"
- >Transitions</a></h2>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#transitions">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td>
- <p><samp>
-A&nbsp;transition&nbsp;marker&nbsp;is&nbsp;a&nbsp;horizontal&nbsp;line
-<br>of&nbsp;4&nbsp;or&nbsp;more&nbsp;repeated&nbsp;punctuation
-<br>characters.</samp>
-
- <p><samp>------------</samp>
-
- <p><samp>A&nbsp;transition&nbsp;should&nbsp;not&nbsp;begin&nbsp;or&nbsp;end&nbsp;a
-<br>section&nbsp;or&nbsp;document,&nbsp;nor&nbsp;should&nbsp;two
-<br>transitions&nbsp;be&nbsp;immediately&nbsp;adjacent.</samp>
-
- <td>
- <p>A transition marker is a horizontal line
- of 4 or more repeated punctuation
- characters.</p>
-
- <hr>
-
- <p>A transition should not begin or end a
- section or document, nor should two
- transitions be immediately adjacent.
- </table>
-
- <p>Transitions are commonly seen in novels and short fiction, as a
- gap spanning one or more lines, marking text divisions or
- signaling changes in subject, time, point of view, or emphasis.
-
- <h2><a href="#contents" name="explicit-markup" class="backref"
- >Explicit Markup</a></h2>
-
- <p>Explicit markup blocks are used for constructs which float
- (footnotes), have no direct paper-document representation
- (hyperlink targets, comments), or require specialized processing
- (directives). They all begin with two periods and whitespace, the
- "explicit markup start".
-
- <h3><a href="#contents" name="footnotes" class="backref"
- >Footnotes</a></h3>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#footnotes">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
-
- <tr valign="top">
- <td>
- <samp>Footnote&nbsp;references,&nbsp;like&nbsp;[5]_.</samp>
- <br><samp>Note&nbsp;that&nbsp;footnotes&nbsp;may&nbsp;get</samp>
- <br><samp>rearranged,&nbsp;e.g.,&nbsp;to&nbsp;the&nbsp;bottom&nbsp;of</samp>
- <br><samp>the&nbsp;"page".</samp>
-
- <p><samp>..&nbsp;[5]&nbsp;A&nbsp;numerical&nbsp;footnote.&nbsp;Note</samp>
- <br><samp>&nbsp;&nbsp;&nbsp;there's&nbsp;no&nbsp;colon&nbsp;after&nbsp;the&nbsp;``]``.</samp>
-
- <td>
- Footnote references, like <sup><a href="#5">5</a></sup>.
- Note that footnotes may get rearranged, e.g., to the bottom of
- the "page".
-
- <p><table>
- <tr><td colspan="2"><hr>
- <!-- <tr><td colspan="2">Footnotes: -->
- <tr><td><a name="5"><strong>[5]</strong></a><td> A numerical footnote.
- Note there's no colon after the <samp>]</samp>.
- </table>
-
- <tr valign="top">
- <td>
- <samp>Autonumbered&nbsp;footnotes&nbsp;are</samp>
- <br><samp>possible,&nbsp;like&nbsp;using&nbsp;[#]_&nbsp;and&nbsp;[#]_.</samp>
- <p><samp>..&nbsp;[#]&nbsp;This&nbsp;is&nbsp;the&nbsp;first&nbsp;one.</samp>
- <br><samp>..&nbsp;[#]&nbsp;This&nbsp;is&nbsp;the&nbsp;second&nbsp;one.</samp>
-
- <p><samp>They&nbsp;may&nbsp;be&nbsp;assigned&nbsp;'autonumber</samp>
- <br><samp>labels'&nbsp;-&nbsp;for&nbsp;instance,
- <br>[#fourth]_&nbsp;and&nbsp;[#third]_.</samp>
-
- <p><samp>..&nbsp;[#third]&nbsp;a.k.a.&nbsp;third_</samp>
- <p><samp>..&nbsp;[#fourth]&nbsp;a.k.a.&nbsp;fourth_</samp>
- <td>
- Autonumbered footnotes are possible, like using <sup><a
- href="#auto1">1</a></sup> and <sup><a href="#auto2">2</a></sup>.
-
- <p>They may be assigned 'autonumber labels' - for instance,
- <sup><a href="#fourth">4</a></sup> and <sup><a
- href="#third">3</a></sup>.
-
- <p><table>
- <tr><td colspan="2"><hr>
- <!-- <tr><td colspan="2">Footnotes: -->
- <tr><td><a name="auto1"><strong>[1]</strong></a><td> This is the first one.
- <tr><td><a name="auto2"><strong>[2]</strong></a><td> This is the second one.
- <tr><td><a name="third"><strong>[3]</strong></a><td> a.k.a. <a href="#third">third</a>
- <tr><td><a name="fourth"><strong>[4]</strong></a><td> a.k.a. <a href="#fourth">fourth</a>
- </table>
-
- <tr valign="top">
- <td>
- <samp>Auto-symbol&nbsp;footnotes&nbsp;are&nbsp;also</samp>
- <br><samp>possible,&nbsp;like&nbsp;this:&nbsp;[*]_&nbsp;and&nbsp;[*]_.</samp>
- <p><samp>..&nbsp;[*]&nbsp;This&nbsp;is&nbsp;the&nbsp;first&nbsp;one.</samp>
- <br><samp>..&nbsp;[*]&nbsp;This&nbsp;is&nbsp;the&nbsp;second&nbsp;one.</samp>
-
- <td>
- Auto-symbol footnotes are also
- possible, like this: <sup><a href="#symbol1">*</a></sup>
- and <sup><a href="#symbol2">&dagger;</a></sup>.
-
- <p><table>
- <tr><td colspan="2"><hr>
- <!-- <tr><td colspan="2">Footnotes: -->
- <tr><td><a name="symbol1"><strong>[*]</strong></a><td> This is the first symbol footnote
- <tr><td><a name="symbol2"><strong>[&dagger;]</strong></a><td> This is the second one.
- </table>
-
- </table>
-
- <p>The numbering of auto-numbered footnotes is determined by the
- order of the footnotes, not of the references. For auto-numbered
- footnote references without autonumber labels
- ("<samp>[#]_</samp>"), the references and footnotes must be in the
- same relative order. Similarly for auto-symbol footnotes
- ("<samp>[*]_</samp>").
-
- <h3><a href="#contents" name="citations" class="backref"
- >Citations</a></h3>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#citations">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
-
- <tr valign="top">
- <td>
- <samp>Citation&nbsp;references,&nbsp;like&nbsp;[CIT2002]_.</samp>
- <br><samp>Note&nbsp;that&nbsp;citations&nbsp;may&nbsp;get</samp>
- <br><samp>rearranged,&nbsp;e.g.,&nbsp;to&nbsp;the&nbsp;bottom&nbsp;of</samp>
- <br><samp>the&nbsp;"page".</samp>
-
- <p><samp>..&nbsp;[CIT2002]&nbsp;A&nbsp;citation</samp>
- <br><samp>&nbsp;&nbsp;&nbsp;(as&nbsp;often&nbsp;used&nbsp;in&nbsp;journals).</samp>
-
- <p><samp>Citation&nbsp;labels&nbsp;contain&nbsp;alphanumerics,</samp>
- <br><samp>underlines,&nbsp;hyphens&nbsp;and&nbsp;fullstops.</samp>
- <br><samp>Case&nbsp;is&nbsp;not&nbsp;significant.</samp>
-
- <p><samp>Given&nbsp;a&nbsp;citation&nbsp;like&nbsp;[this]_,&nbsp;one</samp>
- <br><samp>can&nbsp;also&nbsp;refer&nbsp;to&nbsp;it&nbsp;like&nbsp;this_.</samp>
-
- <p><samp>..&nbsp;[this]&nbsp;here.</samp>
-
- <td>
- Citation references, like <a href="#cit2002">[CIT2002]</a>.
- Note that citations may get rearranged, e.g., to the bottom of
- the "page".
-
- <p>Citation labels contain alphanumerics, underlines, hyphens
- and fullstops. Case is not significant.
-
- <p>Given a citation like <a href="#this">[this]</a>, one
- can also refer to it like <a href="#this">this</a>.
-
- <p><table>
- <tr><td colspan="2"><hr>
- <!-- <tr><td colspan="2">Citations: -->
- <tr><td><a name="cit2002"><strong>[CIT2002]</strong></a><td> A citation
- (as often used in journals).
- <tr><td><a name="this"><strong>[this]</strong></a><td> here.
- </table>
-
- </table>
-
- <h3><a href="#contents" name="hyperlink-targets" class="backref"
- >Hyperlink Targets</a></h3>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#hyperlink-targets">details</a>)
-
- <h4><a href="#contents" name="external-hyperlink-targets" class="backref"
- >External Hyperlink Targets</a></h4>
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
-
- <tr valign="top">
- <td>
- <samp>External&nbsp;hyperlinks,&nbsp;like&nbsp;Python_.</samp>
-
- <p><samp>..&nbsp;_Python:&nbsp;http://www.python.org/</samp>
- <td>
- <table width="100%">
- <tr bgcolor="#99CCFF"><td><em>Fold-in form</em>
- <tr><td>Indirect hyperlinks, like
- <a href="http://www.python.org">Python</a>.
- <tr bgcolor="#99CCFF"><td><em>Call-out form</em>
- <tr><td>External hyperlinks, like
- <a href="#labPython"><i>Python</i></a>.
-
- <p><table>
- <tr><td colspan="2"><hr>
- <tr><td><a name="labPython"><i>Python:</i></a>
- <td> <a href="http://www.python.org/">http://www.python.org/</a>
- </table>
- </table>
- </table>
-
- <p>"<em>Fold-in</em>" is the representation typically used in HTML
- documents (think of the indirect hyperlink being "folded in" like
- ingredients into a cake), and "<em>call-out</em>" is more suitable for
- printed documents, where the link needs to be presented explicitly, for
- example as a footnote.
-
- <h4><a href="#contents" name="internal-hyperlink-targets" class="backref"
- >Internal Hyperlink Targets</a></h4>
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
-
- <tr valign="top">
- <td><samp>Internal&nbsp;crossreferences,&nbsp;like&nbsp;example_.</samp>
-
- <p><samp>..&nbsp;_example:</samp>
-
- <p><samp>This&nbsp;is&nbsp;an&nbsp;example&nbsp;crossreference&nbsp;target.</samp>
- <td>
- <table width="100%">
- <tr bgcolor="#99CCFF"><td><em>Fold-in form</em>
- <!-- Note that some browsers may not like an "a" tag that -->
- <!-- does not have any content, so we could arbitrarily -->
- <!-- use the first word as content - *or* just trust to -->
- <!-- luck! -->
- <tr><td>Internal crossreferences, like <a href="#example-foldin">example</a>
- <p><a name="example-foldin">This</a> is an example
- crossreference target.
- <tr><td bgcolor="#99CCFF"><em>Call-out form</em>
- <tr><td>Internal crossreferences, like <a href="#example-callout">example</a>
-
- <p><a name="example-callout"><i>example:</i></a>
- <br>This is an example crossreference target.
- </table>
-
- </table>
-
- <h4><a href="#contents" name="indirect-hyperlink-targets" class="backref"
- >Indirect Hyperlink Targets</a></h4>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#indirect-hyperlink-targets">details</a>)
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
-
- <tr valign="top">
- <td>
- <samp>Python_&nbsp;is&nbsp;`my&nbsp;favourite
-<br>programming&nbsp;language`__.</samp>
-
- <p><samp>..&nbsp;_Python:&nbsp;http://www.python.org/</samp>
-
- <p><samp>__&nbsp;Python_</samp>
-
- <td>
- <p><a href="http://www.python.org/">Python</a> is
- <a href="http://www.python.org/">my favourite
- programming language</a>.
-
- </table>
-
- <p>The second hyperlink target (the line beginning with
- "<samp>__</samp>") is both an indirect hyperlink target
- (<i>indirectly</i> pointing at the Python website via the
- "<samp>Python_</samp>" reference) and an <b>anonymous hyperlink
- target</b>. In the text, a double-underscore suffix is used to
- indicate an <b>anonymous hyperlink reference</b>. In an anonymous
- hyperlink target, the reference text is not repeated. This is
- useful for references with long text or throw-away references, but
- the target should be kept close to the reference to prevent them
- going out of sync.
-
- <h4><a href="#contents" name="implicit-hyperlink-targets" class="backref"
- >Implicit Hyperlink Targets</a></h4>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#implicit-hyperlink-targets">details</a>)
-
- <p>Section titles, footnotes, and citations automatically generate
- hyperlink targets (the title text or footnote/citation label is
- used as the hyperlink name).
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead><tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
-
- <tr valign="top">
- <td>
- <samp>Titles&nbsp;are&nbsp;targets,&nbsp;too</samp>
- <br><samp>=======================</samp>
- <br><samp>Implict&nbsp;references,&nbsp;like&nbsp;`Titles&nbsp;are</samp>
- <br><samp>targets,&nbsp;too`_.</samp>
- <td>
- <font size="+2"><strong><a name="title">Titles are targets, too</a></strong></font>
- <p>Implict references, like <a href="#title">Titles are
- targets, too</a>.
- </table>
-
- <h3><a href="#contents" name="directives" class="backref"
- >Directives</a></h3>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#directives">details</a>)
-
- <p>Directives are a general-purpose extension mechanism, a way of
- adding support for new constructs without adding new syntax. For
- a description of all standard directives, see <a
- href="../../ref/rst/directives.html" >reStructuredText
- Directives</a>.
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td><samp>For&nbsp;instance:</samp>
-
- <p><samp>..&nbsp;image::&nbsp;images/ball1.gif</samp>
-
- <td>
- For instance:
- <p><img src="images/ball1.gif" alt="ball1">
- </table>
-
- <h3><a href="#contents" name="substitution-references-and-definitions"
- class="backref" >Substitution References and Definitions</a></h3>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#substitution-definitions">details</a>)
-
- <p>Substitutions are like inline directives, allowing graphics and
- arbitrary constructs within text.
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td><samp>
-The&nbsp;|biohazard|&nbsp;symbol&nbsp;must&nbsp;be
-used&nbsp;on&nbsp;containers&nbsp;used&nbsp;to
-dispose&nbsp;of&nbsp;medical&nbsp;waste.</samp>
-
- <p><samp>
-..&nbsp;|biohazard|&nbsp;image::&nbsp;biohazard.png</samp>
-
- <td>
-
- <p>The <img src="images/biohazard.png" align="bottom" alt="biohazard"> symbol
- must be used on containers used to dispose of medical waste.
-
- </table>
-
- <h3><a href="#contents" name="comments" class="backref"
- >Comments</a></h3>
-
- <p>(<a href="../../ref/rst/restructuredtext.html#comments">details</a>)
-
- <p>Any text which begins with an explicit markup start but doesn't
- use the syntax of any of the constructs above, is a comment.
-
- <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3">
- <thead>
- <tr align="left" bgcolor="#99CCFF">
- <th width="50%">Plain text
- <th width="50%">Typical result
- </thead>
- <tbody>
- <tr valign="top">
- <td><samp>..&nbsp;This&nbsp;text&nbsp;will&nbsp;not&nbsp;be&nbsp;shown</samp>
- <br><samp>&nbsp;&nbsp;&nbsp;(but,&nbsp;for&nbsp;instance,&nbsp;in&nbsp;HTML&nbsp;might&nbsp;be</samp>
- <br><samp>&nbsp;&nbsp;&nbsp;rendered&nbsp;as&nbsp;an&nbsp;HTML&nbsp;comment)</samp>
-
- <td>&nbsp;
- <!-- This text will not be shown -->
- <!-- (but, for instance in HTML might be -->
- <!-- rendered as an HTML comment) -->
-
- <tr valign="top">
- <td>
- <samp>An&nbsp;empty&nbsp;"comment"&nbsp;does&nbsp;not</samp>
- <br><samp>"consume"&nbsp;following&nbsp;blocks.</samp>
- <p><samp>..</samp>
- <p><samp>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;So&nbsp;this&nbsp;block&nbsp;is&nbsp;not&nbsp;"lost",</samp>
- <br><samp>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;despite&nbsp;its&nbsp;indentation.</samp>
- <td>
- An empty "comment" does not
- "consume" following blocks.
- <blockquote>
- So this block is not "lost",
- despite its indentation.
- </blockquote>
- </table>
-
- <h2><a href="#contents" name="getting-help" class="backref"
- >Getting Help</a></h2>
-
- <p>Users who have questions or need assistance with Docutils or
- reStructuredText should <a
- href="mailto:docutils-users@lists.sourceforge.net" >post a
- message</a> to the <a
- href="http://lists.sourceforge.net/lists/listinfo/docutils-users"
- >Docutils-Users mailing list</a>. The <a
- href="http://docutils.sourceforge.net/" >Docutils project web
- site</a> has more information.
-
- <p><hr>
- <address>
- <p>Authors:
- <a href="http://www.tibsnjoan.co.uk/">Tibs</a>
- (<a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>)
- and David Goodger
- (<a href="mailto:goodger@python.org">goodger@python.org</a>)
- </address>
- <!-- Created: Fri Aug 03 09:11:57 GMT Daylight Time 2001 -->
- </body>
-</html>
diff --git a/docutils/docs/user/rst/quickstart.txt b/docutils/docs/user/rst/quickstart.txt
deleted file mode 100644
index bf6b21275..000000000
--- a/docutils/docs/user/rst/quickstart.txt
+++ /dev/null
@@ -1,390 +0,0 @@
-A ReStructuredText Primer
-=========================
-
-:Author: Richard Jones
-:Version: $Revision$
-:Copyright: This document has been placed in the public domain.
-
-.. contents::
-
-
-The text below contains links that look like "(quickref__)". These
-are relative links that point to the `Quick reStructuredText`_ user
-reference. If these links don't work, please refer to the `master
-quick reference`_ document.
-
-__
-.. _Quick reStructuredText: quickref.html
-.. _master quick reference:
- http://docutils.sourceforge.net/docs/user/rst/quickref.html
-
-
-Structure
----------
-
-From the outset, let me say that "Structured Text" is probably a bit
-of a misnomer. It's more like "Relaxed Text" that uses certain
-consistent patterns. These patterns are interpreted by a HTML
-converter to produce "Very Structured Text" that can be used by a web
-browser.
-
-The most basic pattern recognised is a **paragraph** (quickref__).
-That's a chunk of text that is separated by blank lines (one is
-enough). Paragraphs must have the same indentation -- that is, line
-up at their left edge. Paragraphs that start indented will result in
-indented quote paragraphs. For example::
-
- This is a paragraph. It's quite
- short.
-
- This paragraph will result in an indented block of
- text, typically used for quoting other text.
-
- This is another one.
-
-Results in:
-
- This is a paragraph. It's quite
- short.
-
- This paragraph will result in an indented block of
- text, typically used for quoting other text.
-
- This is another one.
-
-__ quickref.html#paragraphs
-
-Text styles
------------
-
-(quickref__)
-
-__ quickref.html#inline-markup
-
-Inside paragraphs and other bodies of text, you may additionally mark
-text for *italics* with "``*italics*``" or **bold** with
-"``**bold**``".
-
-If you want something to appear as a fixed-space literal, use
-"````double back-quotes````". Note that no further fiddling is done
-inside the double back-quotes -- so asterisks "``*``" etc. are left
-alone.
-
-If you find that you want to use one of the "special" characters in
-text, it will generally be OK -- reStructuredText is pretty smart.
-For example, this * asterisk is handled just fine. If you actually
-want text \*surrounded by asterisks* to **not** be italicised, then
-you need to indicate that the asterisk is not special. You do this by
-placing a backslash just before it, like so "``\*``" (quickref__), or
-by enclosing it in double back-quotes (inline literals), like this::
-
- ``\*``
-
-__ quickref.html#escaping
-
-Lists
------
-
-Lists of items come in three main flavours: **enumerated**,
-**bulleted** and **definitions**. In all list cases, you may have as
-many paragraphs, sublists, etc. as you want, as long as the left-hand
-side of the paragraph or whatever aligns with the first line of text
-in the list item.
-
-Lists must always start a new paragraph -- that is, they must appear
-after a blank line.
-
-**enumerated** lists (numbers, letters or roman numerals; quickref__)
- __ quickref.html#enumerated-lists
-
- Start a line off with a number or letter followed by a period ".",
- right bracket ")" or surrounded by brackets "( )" -- whatever you're
- comfortable with. All of the following forms are recognised::
-
- 1. numbers
-
- A. upper-case letters
- and it goes over many lines
-
- with two paragraphs and all!
-
- a. lower-case letters
-
- 3. with a sub-list starting at a different number
- 4. make sure the numbers are in the correct sequence though!
-
- I. upper-case roman numerals
-
- i. lower-case roman numerals
-
- (1) numbers again
-
- 1) and again
-
- Results in (note: the different enumerated list styles are not
- always supported by every web browser, so you may not get the full
- effect here):
-
- 1. numbers
-
- A. upper-case letters
- and it goes over many lines
-
- with two paragraphs and all!
-
- a. lower-case letters
-
- 3. with a sub-list starting at a different number
- 4. make sure the numbers are in the correct sequence though!
-
- I. upper-case roman numerals
-
- i. lower-case roman numerals
-
- (1) numbers again
-
- 1) and again
-
-**bulleted** lists (quickref__)
- __ quickref.html#bullet-lists
-
- Just like enumerated lists, start the line off with a bullet point
- character - either "-", "+" or "*"::
-
- * a bullet point using "*"
-
- - a sub-list using "-"
-
- + yet another sub-list
-
- - another item
-
- Results in:
-
- * a bullet point using "*"
-
- - a sub-list using "-"
-
- + yet another sub-list
-
- - another item
-
-**definition** lists (quickref__)
- __ quickref.html#definition-lists
-
- Unlike the other two, the definition lists consist of a term, and
- the definition of that term. The format of a definition list is::
-
- what
- Definition lists associate a term with a definition.
-
- *how*
- The term is a one-line phrase, and the definition is one or more
- paragraphs or body elements, indented relative to the term.
- Blank lines are not allowed between term and definition.
-
- Results in:
-
- what
- Definition lists associate a term with a definition.
-
- *how*
- The term is a one-line phrase, and the definition is one or more
- paragraphs or body elements, indented relative to the term.
- Blank lines are not allowed between term and definition.
-
-Preformatting (code samples)
-----------------------------
-(quickref__)
-
-__ quickref.html#literal-blocks
-
-To just include a chunk of preformatted, never-to-be-fiddled-with
-text, finish the prior paragraph with "``::``". The preformatted
-block is finished when the text falls back to the same indentation
-level as a paragraph prior to the preformatted block. For example::
-
- An example::
-
- Whitespace, newlines, blank lines, and all kinds of markup
- (like *this* or \this) is preserved by literal blocks.
- Lookie here, I've dropped an indentation level
- (but not far enough)
-
- no more example
-
-Results in:
-
- An example::
-
- Whitespace, newlines, blank lines, and all kinds of markup
- (like *this* or \this) is preserved by literal blocks.
- Lookie here, I've dropped an indentation level
- (but not far enough)
-
- no more example
-
-Note that if a paragraph consists only of "``::``", then it's removed
-from the output::
-
- ::
-
- This is preformatted text, and the
- last "::" paragraph is removed
-
-Results in:
-
-::
-
- This is preformatted text, and the
- last "::" paragraph is removed
-
-Sections
---------
-
-(quickref__)
-
-__ quickref.html#section-structure
-
-To break longer text up into sections, you use **section headers**.
-These are a single line of text (one or more words) with adornment: an
-underline alone, or an underline and an overline together, in dashes
-"``-----``", equals "``======``", tildes "``~~~~~~``" or any of the
-non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you
-feel comfortable with. An underline-only adornment is distinct from
-an overline-and-underline adornment using the same character. The
-underline/overline must be at least as long as the title text. Be
-consistent, since all sections marked with the same adornment style
-are deemed to be at the same level::
-
- Chapter 1 Title
- ===============
-
- Section 1.1 Title
- -----------------
-
- Subsection 1.1.1 Title
- ~~~~~~~~~~~~~~~~~~~~~~
-
- Section 1.2 Title
- -----------------
-
- Chapter 2 Title
- ===============
-
-This results in the following structure, illustrated by simplified
-pseudo-XML::
-
- <section>
- <title>
- Chapter 1 Title
- <section>
- <title>
- Section 1.1 Title
- <section>
- <title>
- Subsection 1.1.1 Title
- <section>
- <title>
- Section 1.2 Title
- <section>
- <title>
- Chapter 2 Title
-
-(Pseudo-XML uses indentation for nesting and has no end-tags. It's
-not possible to show actual processed output, as in the other
-examples, because sections cannot exist inside block quotes. For a
-concrete example, compare the section structure of this document's
-source text and processed output.)
-
-Note that section headers are available as link targets, just using
-their name. To link to the Lists_ heading, I write "``Lists_``". If
-the heading has a space in it like `text styles`_, we need to quote
-the heading "```text styles`_``".
-
-
-Document Title / Subtitle
-`````````````````````````
-
-The title of the whole document is distinct from section titles and
-may be formatted somewhat differently (e.g. the HTML writer by default
-shows it as a centered heading).
-
-To indicate the document title in reStructuredText, use a unique adornment
-style at the beginning of the document. To indicate the document subtitle,
-use another unique adornment style immediately after the document title. For
-example::
-
- ================
- Document Title
- ================
- ----------
- Subtitle
- ----------
-
- Section Title
- =============
-
- ...
-
-Note that "Document Title" and "Section Title" above both use equals
-signs, but are distict and unrelated styles. The text of
-overline-and-underlined titles (but not underlined-only) may be inset
-for aesthetics.
-
-
-Images
-------
-
-(quickref__)
-
-__ quickref.html#directives
-
-To include an image in your document, you use the the ``image`` directive__.
-For example::
-
- .. image:: images/biohazard.png
-
-results in:
-
-.. image:: images/biohazard.png
-
-The ``images/biohazard.png`` part indicates the filename of the image
-you wish to appear in the document. There's no restriction placed on
-the image (format, size etc). If the image is to appear in HTML and
-you wish to supply additional information, you may::
-
- .. image:: images/biohazard.png
- :height: 100
- :width: 200
- :scale: 50
- :alt: alternate text
-
-See the full `image directive documentation`__ for more info.
-
-__ ../../ref/rst/directives.html
-__ ../../ref/rst/directives.html#images
-
-
-What Next?
-----------
-
-This primer introduces the most common features of reStructuredText,
-but there are a lot more to explore. The `Quick reStructuredText`_
-user reference is a good place to go next. For complete details, the
-`reStructuredText Markup Specification`_ is the place to go [#]_.
-
-Users who have questions or need assistance with Docutils or
-reStructuredText should `post a message`_ to the `Docutils-Users
-mailing list`_. The `Docutils project web site`_ has more
-information.
-
-.. [#] If that relative link doesn't work, try the master document:
- http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.
-
-.. _reStructuredText Markup Specification:
- ../../ref/rst/restructuredtext.html
-.. _post a message: mailto:docutils-users@lists.sourceforge.net
-.. _Docutils-Users mailing list:
- http://lists.sourceforge.net/lists/listinfo/docutils-users
-.. _Docutils project web site: http://docutils.sourceforge.net/
diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt
deleted file mode 100644
index ab31e0917..000000000
--- a/docutils/docs/user/tools.txt
+++ /dev/null
@@ -1,316 +0,0 @@
-==========================
- Docutils Front-End Tools
-==========================
-
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:Revision: $Revision$
-:Date: $Date$
-:Copyright: This document has been placed in the public domain.
-
-.. contents::
-
-
-Introduction
-============
-
-Once the Docutils package is unpacked, you will discover a "``tools``"
-directory containing several front ends for common Docutils
-processing. Rather than a single all-purpose program, Docutils has
-many small front ends, each specialized for a specific "Reader" (which
-knows how to interpret a file in context), a "Parser" (which
-understands the syntax of the text), and a "Writer" (which knows how
-to generate a specific data format).
-
-Most front ends have common options and the same command-line usage
-pattern::
-
- toolname [options] [<source> [<destination]]
-
-(The exceptions are buildhtml.py_ and pep2html.py_.) See rst2html.py_
-for concrete examples. Each tool has a "``--help``" option which
-lists the `command-line options`_ and arguments it supports.
-Processing can also be customized with `configuration files`_.
-
-The two arguments, "source" and "destination", are optional. If only
-one argument (source) is specified, the standard output (stdout) is
-used for the destination. If no arguments are specified, the standard
-input (stdin) is used for the source as well.
-
-
-Getting Help
-------------
-
-First, try the "``--help``" option each front-end tool has.
-
-Users who have questions or need assistance with Docutils or
-reStructuredText should `post a message`_ to the `Docutils-Users
-mailing list`_. The `Docutils project web site`_ has more
-information.
-
-.. _post a message: mailto:docutils-users@lists.sourceforge.net
-.. _Docutils-Users mailing list:
- http://lists.sourceforge.net/lists/listinfo/docutils-users
-.. _Docutils project web site: http://docutils.sourceforge.net/
-
-
-The Tools
-=========
-
-buildhtml.py
-------------
-
-:Readers: Standalone, PEP
-:Parser: reStructuredText
-:Writers: HTML, PEP/HTML
-
-Use ``buildhtml.py`` to generate .html from all the .txt files
-(including PEPs) in each <directory> given, and their subdirectories
-too. (Use the ``--local`` option to skip subdirectories.)
-
-Usage::
-
- buildhtml.py [options] [<directory> ...]
-
-After unpacking the Docutils package, the following shell commands
-will generate HTML for all included documentation::
-
- cd docutils/tools
- buildhtml.py ..
-
-For official releases, the directory may be called "docutils-X.Y",
-where "X.Y" is the release version. Alternatively::
-
- cd docutils
- tools/buildhtml.py --config=tools/docutils.conf
-
-The current directory (and all subdirectories) is chosen by default if
-no directory is named. Some files may generate system messages
-(docs/user/rst/demo.txt contains intentional errors); use the
-``--quiet`` option to suppress all warnings. The ``--config`` option
-ensures that the correct stylesheets, templates, and settings are in
-place (a ``docutils.conf`` configuration file in the current directory
-is picked up automatically). Command-line options may be used to
-override config file settings or replace them altogether.
-
-
-rst2html.py
------------
-
-:Reader: Standalone
-:Parser: reStructuredText
-:Writer: HTML
-
-The ``rst2html.py`` front end reads standalone reStructuredText source
-files and produces HTML 4 (XHTML 1) output compatible with modern
-browsers. For example, to process a reStructuredText file
-"``test.txt``" into HTML::
-
- rst2html.py test.txt test.html
-
-Now open the "``test.html``" file in your favorite browser to see the
-results. To get a footer with a link to the source file, date & time
-of processing, and links to the Docutils projects, add some options::
-
- rst2html.py -stg test.txt test.html
-
-
-Stylesheets
-```````````
-
-``rst2html.py`` inserts into the generated HTML a link to a cascading
-stylesheet, defaulting to "``default.css``" (override with a
-"``--stylesheet``" or "``--stylesheet-path``" command-line option or
-with configuration file settings). The
-"``tools/stylesheets/default.css``" stylesheet is provided for basic
-use. To experiment with styles, rather than editing the default
-stylesheet (which will be updated as the project evolves), it is
-recommended to use an "``@import``" statement to create a "wrapper"
-stylesheet. For example, a "``my.css``" stylesheet could contain the
-following::
-
- @import url(default.css);
-
- h1, h2, h3, h4, h5, h6, p.topic-title {
- font-family: sans-serif }
-
-Generate HTML with the following command::
-
- rst2html.py -stg --stylesheet my.css test.txt test.html
-
-When viewed in a browser, the new "wrapper" stylesheet will change the
-typeface family of titles to "sans serif", typically Helvetica or
-Arial. Other styles will not be affected. Styles in wrapper
-stylesheets override styles in imported stylesheets, enabling
-incremental experimentation.
-
-
-pep.py
-------
-
-:Reader: PEP
-:Parser: reStructuredText
-:Writer: PEP/HTML
-
-``pep.py`` reads a new-style PEP (marked up with reStructuredText) and
-produces HTML. It requires a template file and a stylesheet. By
-default, it makes use of a "``pep-html-template``" file and a
-"``default.css``" stylesheet in the current directory, but these can
-be overridden by command-line options or configuration files. The
-"``tools/stylesheets/pep.css``" stylesheet is intended specifically
-for PEP use.
-
-The "``docutils.conf``" `configuration file`_ in the "``tools``"
-directory of Docutils contains a default setup for use in processing
-the PEP files (``docs/peps/pep-*.txt``) into HTML. It specifies a
-default template (``tools/pep-html-template``) and a default
-stylesheet (``tools/stylesheets/pep.css``). See Stylesheets_ above
-for more information.
-
-``pep.py`` can be run from the ``tools`` directory or from the
-``docs/peps/`` directory, by adjusting the settings. These two sets
-of commands are equivalent::
-
- cd <path-to-docutils>/tools
- # This will pick up the "docutils.conf" file automatically:
- pep.py ../docs/peps/pep-0287.txt ../docs/peps/pep-0287.html
-
- cd <path-to-docutils>/docs/peps
- # Must tell the tool where to find the config file:
- ../../tools/pep.py --config ../../tools/docutils.conf \
- pep-0287.txt pep-0287.html
-
-
-pep2html.py
------------
-
-:Reader: PEP
-:Parser: reStructuredText
-:Writer: PEP/HTML
-
-``pep2html.py`` is a modified version of the original script by
-Fredrik Lundh, with support for Docutils added. It reads the
-beginning of a PEP text file to determine the format (old-style
-indented or new-style reStructuredText) and processes accordingly.
-Since it does not use the Docutils front end mechanism (the common
-command-line options are not supported), it can only be configured
-using `configuration files`_. The template and stylesheet
-requirements of ``pep2html.py`` are the same as those of `pep.py`_
-above.
-
-Arguments to ``pep2html.py`` may be a list of PEP numbers or .txt
-files. If no arguments are given, all files of the form
-"``pep-*.txt``" are processed.
-
-
-rst2latex.py
-------------
-
-:Reader: Standalone
-:Parser: reStructuredText
-:Writer: LaTeX2e
-
-The ``rst2latex.py`` front end reads standalone reStructuredText
-source files and produces LaTeX2e output. For example, to process a
-reStructuredText file "``test.txt``" into LaTeX::
-
- rst2latex.py test.txt test.tex
-
-The output file "``test.tex``" should then be processed with ``latex``
-or ``pdflatex`` to get a typeset document.
-
-Some limitations and difference apply:
-
-- GIF, JPG and PNG images are not handled, when processed with
- ``latex``; use ``pdflatex`` instead.
-- Only the Latin-1 output encoding has been tested up to now (Latin-1
- has been made the default output encoding for LaTeX).
-- The optional stylesheet file allows the inclusion of special packages
- or overwriting default settings for LaTeX.
-- Not all constructs are possible, see `Generating LaTeX with Docutils`_.
-
-
-rst2xml.py
-----------
-
-:Reader: Standalone
-:Parser: reStructuredText
-:Writer: XML (Docutils native)
-
-The ``rst2xml.py`` front end produces Docutils-native XML output.
-This can be transformed with standard XML tools such as XSLT
-processors into arbitrary final forms.
-
-
-rst2pseudoxml.py
-----------------
-
-:Reader: Standalone
-:Parser: reStructuredText
-:Writer: Pseudo-XML
-
-``rst2pseudoxml.py`` is used for debugging the Docutils "Reader to
-Transform to Writer" pipeline. It produces a compact pretty-printed
-"pseudo-XML", where nesting is indicated by indentation (no end-tags).
-External attributes for all elements are output, and internal
-attributes for any leftover "pending" elements are also given.
-
-
-quicktest.py
-------------
-
-:Reader: N/A
-:Parser: reStructuredText
-:Writer: N/A
-
-The ``quicktest.py`` tool is used for testing the reStructuredText
-parser. It does not use a Docutils Reader or Writer or the standard
-Docutils command-line options. Rather, it does its own I/O and calls
-the parser directly. No transforms are applied to the parsed
-document. Various forms output are possible:
-
-- Pretty-printed pseudo-XML (default)
-- Test data (Python list of input and pseudo-XML output strings;
- useful for creating new test cases)
-- Pretty-printed native XML
-- Raw native XML (with or without a stylesheet reference)
-
-
-
-Customization
-=============
-
-Command-Line Options
---------------------
-
-Each front-end tool supports command-line options for one-off
-customization. For persistent customization, use `configuration
-files`_. Command-line options take priority over configuration file
-settings.
-
-Use the "--help" option on each of the front ends to list the
-command-line options it supports. Command-line options and their
-corresponding configuration file entry names are listed in the
-`Docutils Configuration Files`_ document.
-
-
-.. _configuration file:
-
-Configuration Files
--------------------
-
-Configuration files are used for persistent customization; they can be
-set once and take effect every time you use a front-end tool.
-
-For details, see `Docutils Configuration Files`_.
-
-.. _Docutils Configuration Files: config.html
-.. _Generating LaTeX with Docutils: latex.html
-
-..
- Local Variables:
- mode: indented-text
- indent-tabs-mode: nil
- sentence-end-double-space: t
- fill-column: 70
- End: