diff options
Diffstat (limited to 'docutils/docs/user')
| -rw-r--r-- | docutils/docs/user/config.txt | 959 | ||||
| -rw-r--r-- | docutils/docs/user/latex.txt | 388 | ||||
| -rw-r--r-- | docutils/docs/user/rst/cheatsheet.txt | 121 | ||||
| -rw-r--r-- | docutils/docs/user/rst/demo.txt | 550 | ||||
| -rw-r--r-- | docutils/docs/user/rst/images/ball1.gif | bin | 4361 -> 0 bytes | |||
| -rw-r--r-- | docutils/docs/user/rst/images/biohazard.png | bin | 179 -> 0 bytes | |||
| -rw-r--r-- | docutils/docs/user/rst/images/title.png | bin | 1171 -> 0 bytes | |||
| -rw-r--r-- | docutils/docs/user/rst/quickref.html | 1319 | ||||
| -rw-r--r-- | docutils/docs/user/rst/quickstart.txt | 390 | ||||
| -rw-r--r-- | docutils/docs/user/tools.txt | 316 |
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 - "``†``". - 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 Binary files differdeleted file mode 100644 index 3e14441d9..000000000 --- a/docutils/docs/user/rst/images/ball1.gif +++ /dev/null diff --git a/docutils/docs/user/rst/images/biohazard.png b/docutils/docs/user/rst/images/biohazard.png Binary files differdeleted file mode 100644 index ae4629d8b..000000000 --- a/docutils/docs/user/rst/images/biohazard.png +++ /dev/null diff --git a/docutils/docs/user/rst/images/title.png b/docutils/docs/user/rst/images/title.png Binary files differdeleted file mode 100644 index cc6218efe..000000000 --- a/docutils/docs/user/rst/images/title.png +++ /dev/null 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 emphasis**</samp> - <td><strong>strong emphasis</strong> - <td>Normally rendered as boldface. - - <tr valign="top"> - <td nowrap><samp>`interpreted 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 literal``</samp> - <td><code>inline 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 - <samp>' " ( [ {</samp> or <samp><</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 <samp>' " . , : ; ! ? - ) ] } / \</samp> - or <samp>></samp>. - <li>If a start-string is immediately preceded by one of - <samp>' " ( [ {</samp> or <samp><</samp>, it must not be - immediately followed by the corresponding character from - <samp>' " ) ] }</samp> or <samp>></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* ``with`` "\"</samp> - <td><em>escape</em> <samp>with</samp> "" - <tr valign="top"><td> - <samp>\*escape* \``with`` "\\"</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* \`with` "\\""""</samp> - <td>*escape* `with` "\" - <tr valign="top"><td> - <samp> """\\*escape* \\`with` "\\\\""""</samp> - <td>*escape* `with` "\" - <tr valign="top"><td> - <samp> """\*escape* \`with` "\\""""</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 are underlined (or over-</samp> -<br><samp>and underlined) with a printing</samp> -<br><samp>nonalphanumeric 7-bit ASCII</samp> -<br><samp>character. Recommended choices</samp> -<br><samp>are "``= - ` : ' " ~ ^ _ * + # < >``".</samp> -<br><samp>The underline/overline must be at</samp> -<br><samp>least as long as the title text.</samp> -<br><samp></samp> -<br><samp>A lone top-level (sub)section</samp> -<br><samp>is lifted up to be the 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>= - ` : ' " ~ ^ _ * + # < ></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 is a paragraph.</samp> - -<p><samp>Paragraphs line up at their left</samp> -<br><samp>edges, and are normally separated</samp> -<br><samp>by blank 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 lists:</samp> - -<p><samp>- This is item 1</samp> -<br><samp>- This is item 2</samp> - -<p><samp>- Bullets are "-", "*" or "+".</samp> -<br><samp> Continuing text must be aligned</samp> -<br><samp> after the bullet and whitespace.</samp> - -<p><samp>Note that a blank line is required</samp> -<br><samp>before the first item and after the</samp> -<br><samp>last, but is optional between 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 lists:</samp> - -<p><samp>3. This is the first item</samp> -<br><samp>4. This is the second item</samp> -<br><samp>5. Enumerators are arabic numbers,</samp> -<br><samp> single letters, or roman numerals</samp> -<br><samp>6. List items should be sequentially</samp> -<br><samp> numbered, but need not start at 1</samp> -<br><samp> (although not all formatters will</samp> -<br><samp> honour the first index).</samp> -<br><samp>#. This item is 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 lists:</samp> -<br> -<br><samp>what</samp> -<br><samp> Definition lists associate a term with</samp> -<br><samp> a definition.</samp> -<br> -<br><samp>how</samp> -<br><samp> The term is a one-line phrase, and the</samp> -<br><samp> definition is one or more paragraphs or</samp> -<br><samp> body elements, indented relative to the</samp> -<br><samp> term. Blank lines are not allowed</samp> -<br><samp> between term and 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> Tony J. (Tibs) Ibbs,</samp> -<br><samp> David Goodger</samp> - -<p><samp> (and sundry other good-natured folks)</samp> - -<p><samp>:Version: 1.0 of 2001/08/08</samp> -<br><samp>:Dedication: To my 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 command-line option "a" -<br>-b file options can have arguments -<br> and long descriptions -<br>--long options can be long also -<br>--input=file long options can also have -<br> arguments -<br>/V DOS/VMS-style options 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 paragraph containing only two colons</samp> -<br><samp>indicates that the following indented</samp> -<br><samp>or quoted text is a literal block.</samp> -<br> -<br><samp>::</samp> -<br> -<br><samp> Whitespace, newlines, blank lines, and</samp> -<br><samp> all kinds of markup (like *this* or</samp> -<br><samp> \this) is preserved by literal blocks.</samp> -<br> -<br><samp> The paragraph containing only '::'</samp> -<br><samp> will be omitted from the result.</samp> -<br> -<br><samp>The ``::`` may be tacked onto the very</samp> -<br><samp>end of any paragraph. The ``::`` will be</samp> -<br><samp>omitted if it is preceded by whitespace.</samp> -<br><samp>The ``::`` will be converted to a single</samp> -<br><samp>colon if preceded by text, like this::</samp> -<br> -<br><samp> It's very convenient to use this form.</samp> -<br> -<br><samp>Literal blocks end when text returns to</samp> -<br><samp>the preceding paragraph's indentation.</samp> -<br><samp>This means that something like this</samp> -<br><samp>is possible::</samp> -<br> -<br><samp> We start here</samp> -<br><samp> and continue here</samp> -<br><samp> and end here.</samp> -<br> -<br><samp>Per-line quoting can also be used on</samp> -<br><samp>unindented literal blocks:</samp> -<br> -<br><samp>> Useful for quotes from email and</samp> -<br><samp>> for Haskell literate 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> - > Useful for quotes from email and - > 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>| Line blocks are useful for addresses,</samp> -<br><samp>| verse, and adornment-free lists.</samp> -<br><samp>|</samp> -<br><samp>| Each new line begins with a</samp> -<br><samp>| vertical bar ("|").</samp> -<br><samp>| Line breaks and initial indents</samp> -<br><samp>| are preserved.</samp> -<br><samp>| Continuation lines are wrapped</samp> -<br><samp> portions of long lines; they begin</samp> -<br><samp> with spaces in place of vertical 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 quotes are just:</samp> - -<p><samp> Indented paragraphs,</samp> - -<p><samp> and they may 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 blocks are interactive -<br>Python sessions. They begin with -<br>"``>>>``" and end with a blank line.</samp> - - <p><samp>>>> print "This is a doctest block." -<br>This is a doctest block.</samp> - - <td> - <p>Doctest blocks are interactive - Python sessions. They begin with - "<samp>>>></samp>" and end with a blank line. - - <p><samp>>>> print "This is a doctest block." -<br>This is a doctest 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>| Header 1 | Header 2 | Header 3 |</samp> -<br><samp>+============+============+===========+</samp> -<br><samp>| body row 1 | column 2 | column 3 |</samp> -<br><samp>+------------+------------+-----------+</samp> -<br><samp>| body row 2 | Cells may span columns.|</samp> -<br><samp>+------------+------------+-----------+</samp> -<br><samp>| body row 3 | Cells may | - Cells |</samp> -<br><samp>+------------+ span rows. | - contain |</samp> -<br><samp>| body row 4 | | - blocks. |</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>===== ===== ======</samp> -<br><samp> Inputs Output</samp> -<br><samp>------------ ------</samp> -<br><samp> A B A or B</samp> -<br><samp>===== ===== ======</samp> -<br><samp>False False False</samp> -<br><samp>True False True</samp> -<br><samp>False True True</samp> -<br><samp>True True True</samp> -<br><samp>===== ===== ======</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 transition marker is a horizontal line -<br>of 4 or more repeated punctuation -<br>characters.</samp> - - <p><samp>------------</samp> - - <p><samp>A transition should not begin or end a -<br>section or document, nor should two -<br>transitions be immediately 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 references, like [5]_.</samp> - <br><samp>Note that footnotes may get</samp> - <br><samp>rearranged, e.g., to the bottom of</samp> - <br><samp>the "page".</samp> - - <p><samp>.. [5] A numerical footnote. Note</samp> - <br><samp> there's no colon after the ``]``.</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 footnotes are</samp> - <br><samp>possible, like using [#]_ and [#]_.</samp> - <p><samp>.. [#] This is the first one.</samp> - <br><samp>.. [#] This is the second one.</samp> - - <p><samp>They may be assigned 'autonumber</samp> - <br><samp>labels' - for instance, - <br>[#fourth]_ and [#third]_.</samp> - - <p><samp>.. [#third] a.k.a. third_</samp> - <p><samp>.. [#fourth] a.k.a. 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 footnotes are also</samp> - <br><samp>possible, like this: [*]_ and [*]_.</samp> - <p><samp>.. [*] This is the first one.</samp> - <br><samp>.. [*] This is the second one.</samp> - - <td> - Auto-symbol footnotes are also - possible, like this: <sup><a href="#symbol1">*</a></sup> - and <sup><a href="#symbol2">†</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>[†]</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 references, like [CIT2002]_.</samp> - <br><samp>Note that citations may get</samp> - <br><samp>rearranged, e.g., to the bottom of</samp> - <br><samp>the "page".</samp> - - <p><samp>.. [CIT2002] A citation</samp> - <br><samp> (as often used in journals).</samp> - - <p><samp>Citation labels contain alphanumerics,</samp> - <br><samp>underlines, hyphens and fullstops.</samp> - <br><samp>Case is not significant.</samp> - - <p><samp>Given a citation like [this]_, one</samp> - <br><samp>can also refer to it like this_.</samp> - - <p><samp>.. [this] 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 hyperlinks, like Python_.</samp> - - <p><samp>.. _Python: 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 crossreferences, like example_.</samp> - - <p><samp>.. _example:</samp> - - <p><samp>This is an example crossreference 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_ is `my favourite -<br>programming language`__.</samp> - - <p><samp>.. _Python: http://www.python.org/</samp> - - <p><samp>__ 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 are targets, too</samp> - <br><samp>=======================</samp> - <br><samp>Implict references, like `Titles are</samp> - <br><samp>targets, 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 instance:</samp> - - <p><samp>.. image:: 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 |biohazard| symbol must be -used on containers used to -dispose of medical waste.</samp> - - <p><samp> -.. |biohazard| image:: 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>.. This text will not be shown</samp> - <br><samp> (but, for instance, in HTML might be</samp> - <br><samp> rendered as an HTML comment)</samp> - - <td> - <!-- This text will not be shown --> - <!-- (but, for instance in HTML might be --> - <!-- rendered as an HTML comment) --> - - <tr valign="top"> - <td> - <samp>An empty "comment" does not</samp> - <br><samp>"consume" following blocks.</samp> - <p><samp>..</samp> - <p><samp> So this block is not "lost",</samp> - <br><samp> despite its 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: |
