diff options
Diffstat (limited to 'docutils/docs/ref/rst')
| -rw-r--r-- | docutils/docs/ref/rst/definitions.txt | 180 | ||||
| -rw-r--r-- | docutils/docs/ref/rst/directives.txt | 1727 | ||||
| -rw-r--r-- | docutils/docs/ref/rst/introduction.txt | 314 | ||||
| -rw-r--r-- | docutils/docs/ref/rst/restructuredtext.txt | 2879 | ||||
| -rw-r--r-- | docutils/docs/ref/rst/roles.txt | 318 |
5 files changed, 0 insertions, 5418 deletions
diff --git a/docutils/docs/ref/rst/definitions.txt b/docutils/docs/ref/rst/definitions.txt deleted file mode 100644 index 78a2bf8da..000000000 --- a/docutils/docs/ref/rst/definitions.txt +++ /dev/null @@ -1,180 +0,0 @@ -============================================ - reStructuredText Standard Definition Files -============================================ -:Author: David Goodger -:Contact: goodger@python.org -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -This document describes standard definition files, such as sets of -substitution definitions and interpreted text roles, that can be -included in reStructuredText documents. The `"include" directive`__ -has a special syntax for these standard definition files, angle -brackets around the file name:: - - .. include:: <filename.txt> - -__ directives.html#include - -The individual data files are stored with the Docutils source code in -the "docutils" package, in the ``docutils/parsers/rst/include`` -directory. - - -Substitution Definitions -======================== - -Many of the standard definition files contain sets of `substitution -definitions`__, which can be used in documents via `substitution -references`__. For example, the copyright symbol is defined in -``isonum.txt`` as "copy":: - - .. include:: <isonum.txt> - - Copyright |copy| 2003 by John Q. Public, all rights reserved. - -__ restructuredtext.html#substitution-definitions -__ restructuredtext.html#substitution-references - -Individual substitution definitions can also be copied from definition -files and pasted into documents. This has two advantages: it removes -dependencies, and it saves processing of unused definitions. However, -multiple substitution definitions add clutter to the document. - -Substitution references require separation from the surrounding text -with whitespace or punctuation. To use a substitution without -intervening whitespace, you can use the disappearing-whitespace escape -sequence, backslash-space:: - - .. include:: isonum.txt - - Copyright |copy| 2003, BogusMegaCorp\ |trade|. - -Custom substitution definitions may use the `"unicode" directive`__. -Whitespace is ignored and removed, effectively sqeezing together the -text:: - - .. |copy| unicode:: U+000A9 .. COPYRIGHT SIGN - .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign - - Copyright |copy| 2003, |BogusMegaCorp (TM)|. - -__ directives.html#unicode - -In addition, the "ltrim", "rtrim", and "trim" options may be used with -the "unicode" directive to automatically trim spaces from the left, -right, or both sides (respectively) of substitution references:: - - .. |---| unicode:: U+02014 .. em dash - :trim: - - -Character Entity Sets ---------------------- - -The following files contain substitution definitions corresponding to -XML character entity sets, from the following standards: ISO 8879 & -ISO 9573-13 (combined), MathML, and XHTML1. They were generated by -the ``tools/dev/unicode2rstsubs.py`` program from the input file -unicode.xml__, which is maintained as part of the MathML 2 -Recommentation XML source. - -__ http://www.w3.org/2003/entities/xml/ - -=================== ================================================= -Entity Set File Description -=================== ================================================= -isoamsa.txt_ Added Mathematical Symbols: Arrows -isoamsb.txt_ Added Mathematical Symbols: Binary Operators -isoamsc.txt_ Added Mathematical Symbols: Delimiters -isoamsn.txt_ Added Mathematical Symbols: Negated Relations -isoamso.txt_ Added Mathematical Symbols: Ordinary -isoamsr.txt_ Added Mathematical Symbols: Relations -isobox.txt_ Box and Line Drawing -isocyr1.txt_ Russian Cyrillic -isocyr2.txt_ Non-Russian Cyrillic -isodia.txt_ Diacritical Marks -isogrk1.txt_ Greek Letters -isogrk2.txt_ Monotoniko Greek -isogrk3.txt_ Greek Symbols -isogrk4.txt_ [1]_ Alternative Greek Symbols -isolat1.txt_ Added Latin 1 -isolat2.txt_ Added Latin 2 -isomfrk.txt_ [1]_ Mathematical Fraktur -isomopf.txt_ [1]_ Mathematical Openface (Double-struck) -isomscr.txt_ [1]_ Mathematical Script -isonum.txt_ Numeric and Special Graphic -isopub.txt_ Publishing -isotech.txt_ General Technical -mmlalias.txt_ MathML aliases for entities from other sets -mmlextra.txt_ [1]_ Extra names added by MathML -xhtml1-lat1.txt_ XHTML Latin 1 -xhtml1-special.txt_ XHTML Special Characters -xhtml1-symbol.txt_ XHTML Mathematical, Greek and Symbolic Characters -=================== ================================================= - -.. [1] There are ``*-wide.txt`` variants for each of these character - entity set files, containing characters outside of the Unicode - basic multilingual plane or BMP (wide-Unicode; code points greater - than U+FFFF). Most pre-built Python distributions are "narrow" and - do not support wide-Unicode characters. Python *can* be built with - wide-Unicode support though; consult the Python build instructions - for details. - -For example, the copyright symbol is defined as the XML character -entity ``©``. The equivalent reStructuredText substitution -reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is -``|copy|``. - -.. _isoamsa.txt: ../../../docutils/parsers/rst/include/isoamsa.txt -.. _isoamsb.txt: ../../../docutils/parsers/rst/include/isoamsb.txt -.. _isoamsc.txt: ../../../docutils/parsers/rst/include/isoamsc.txt -.. _isoamsn.txt: ../../../docutils/parsers/rst/include/isoamsn.txt -.. _isoamso.txt: ../../../docutils/parsers/rst/include/isoamso.txt -.. _isoamsr.txt: ../../../docutils/parsers/rst/include/isoamsr.txt -.. _isobox.txt: ../../../docutils/parsers/rst/include/isobox.txt -.. _isocyr1.txt: ../../../docutils/parsers/rst/include/isocyr1.txt -.. _isocyr2.txt: ../../../docutils/parsers/rst/include/isocyr2.txt -.. _isodia.txt: ../../../docutils/parsers/rst/include/isodia.txt -.. _isogrk1.txt: ../../../docutils/parsers/rst/include/isogrk1.txt -.. _isogrk2.txt: ../../../docutils/parsers/rst/include/isogrk2.txt -.. _isogrk3.txt: ../../../docutils/parsers/rst/include/isogrk3.txt -.. _isogrk4.txt: ../../../docutils/parsers/rst/include/isogrk4.txt -.. _isolat1.txt: ../../../docutils/parsers/rst/include/isolat1.txt -.. _isolat2.txt: ../../../docutils/parsers/rst/include/isolat2.txt -.. _isomfrk.txt: ../../../docutils/parsers/rst/include/isomfrk.txt -.. _isomopf.txt: ../../../docutils/parsers/rst/include/isomopf.txt -.. _isomscr.txt: ../../../docutils/parsers/rst/include/isomscr.txt -.. _isonum.txt: ../../../docutils/parsers/rst/include/isonum.txt -.. _isopub.txt: ../../../docutils/parsers/rst/include/isopub.txt -.. _isotech.txt: ../../../docutils/parsers/rst/include/isotech.txt -.. _mmlalias.txt: ../../../docutils/parsers/rst/include/mmlalias.txt -.. _mmlextra.txt: ../../../docutils/parsers/rst/include/mmlextra.txt -.. _xhtml1-lat1.txt: ../../../docutils/parsers/rst/include/xhtml1-lat1.txt -.. _xhtml1-special.txt: ../../../docutils/parsers/rst/include/xhtml1-special.txt -.. _xhtml1-symbol.txt: ../../../docutils/parsers/rst/include/xhtml1-symbol.txt - - -S5/HTML Definitions -=================== - -The "s5defs.txt_" standard definition file contains interpreted text -roles (classes) and other definitions for documents destined to become -`S5/HTML slide shows`_. - -.. _s5defs.txt: ../../../docutils/parsers/rst/include/s5defs.txt -.. _S5/HTML slide shows: ../../user/slide-shows.html - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt deleted file mode 100644 index af88a3d4e..000000000 --- a/docutils/docs/ref/rst/directives.txt +++ /dev/null @@ -1,1727 +0,0 @@ -============================= - reStructuredText Directives -============================= -:Author: David Goodger -:Contact: goodger@python.org -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - -This document describes the directives implemented in the reference -reStructuredText parser. - -Directives have the following syntax:: - - +-------+-------------------------------+ - | ".. " | directive type "::" directive | - +-------+ block | - | | - +-------------------------------+ - -Directives begin with an explicit markup start (two periods and a -space), followed by the directive type and two colons (collectively, -the "directive marker"). The directive block begins immediately after -the directive marker, and includes all subsequent indented lines. The -directive block is divided into arguments, options (a field list), and -content (in that order), any of which may appear. See the Directives_ -section in the `reStructuredText Markup Specification`_ for syntax -details. - -Descriptions below list "doctree elements" (document tree element -names; XML DTD generic identifiers) corresponding to individual -directives. For details on the hierarchy of elements, please see `The -Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document -type definition. For directive implementation details, see `Creating -reStructuredText Directives`_. - -.. _Directives: restructuredtext.html#directives -.. _reStructuredText Markup Specification: restructuredtext.html -.. _The Docutils Document Tree: ../doctree.html -.. _Docutils Generic DTD: ../docutils.dtd -.. _Creating reStructuredText Directives: - ../../howto/rst-directives.html - - -------------- - Admonitions -------------- - -.. _attention: -.. _caution: -.. _danger: -.. _error: -.. _hint: -.. _important: -.. _note: -.. _tip: -.. _warning: - -Specific Admonitions -==================== - -:Directive Types: "attention", "caution", "danger", "error", "hint", - "important", "note", "tip", "warning", "admonition" -:Doctree Elements: attention, caution, danger, error, hint, important, - note, tip, warning, admonition, title -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as body elements. - -Admonitions are specially marked "topics" that can appear anywhere an -ordinary body element can. They contain arbitrary body elements. -Typically, an admonition is rendered as an offset block in a document, -sometimes outlined or shaded, with a title matching the admonition -type. For example:: - - .. DANGER:: - Beware killer rabbits! - -This directive might be rendered something like this:: - - +------------------------+ - | !DANGER! | - | | - | Beware killer rabbits! | - +------------------------+ - -The following admonition directives have been implemented: - -- attention -- caution -- danger -- error -- hint -- important -- note -- tip -- warning - -Any text immediately following the directive indicator (on the same -line and/or indented on following lines) is interpreted as a directive -block and is parsed for normal body elements. For example, the -following "note" admonition directive contains one paragraph and a -bullet list consisting of two list items:: - - .. note:: This is a note admonition. - This is the second line of the first paragraph. - - - The note contains all indented body elements - following. - - It includes this bullet list. - - -.. _admonition: - -Generic Admonition -================== - -:Directive Type: "admonition" -:Doctree Elements: admonition, title -:Directive Arguments: One, required (admonition title) -:Directive Options: Possible. -:Directive Content: Interpreted as body elements. - -This is a generic, titled admonition. The title may be anything the -author desires. - -The author-supplied title is also used as a "class" attribute value -after being converted into a valid identifier form (down-cased; -non-alphanumeric characters converted to single hyphens; "admonition-" -prefixed). For example, this admonition:: - - .. admonition:: And, by the way... - - You can make up your own admonition too. - -becomes the following document tree (pseudo-XML):: - - <document source="test data"> - <admonition class="admonition-and-by-the-way"> - <title> - And, by the way... - <paragraph> - You can make up your own admonition too. - -The following option is recognized: - -``class`` : text - Override the computed "class" attribute value. See the class_ - directive below. - - --------- - Images --------- - -There are two image directives: "image" and "figure". - - -Image -===== - -:Directive Type: "image" -:Doctree Element: image -:Directive Arguments: One, required (image URI). -:Directive Options: Possible. -:Directive Content: None. - -An "image" is a simple picture:: - - .. image:: picture.png - -The URI for the image source file is specified in the directive -argument. As with hyperlink targets, the image URI may begin on the -same line as the explicit markup start and target name, or it may -begin in an indented text block immediately following, with no -intervening blank lines. If there are multiple lines in the link -block, they are stripped of leading and trailing whitespace and joined -together. - -Optionally, the image link block may contain a flat field list, the -_`image options`. For example:: - - .. image:: picture.jpeg - :height: 100 - :width: 200 - :scale: 50 - :alt: alternate text - :align: right - -The following options are recognized: - -``alt`` : text - Alternate text: a short description of the image, displayed by - applications that cannot display images, or spoken by applications - for visually impaired users. - -``height`` : integer - The desired height of the image in pixels, used to reserve space - or scale the image vertically. When the "scale" option is also - specified, they are combined. For example, a height of 200 and a - scale of 50 is equivalent to a height of 100 with no scale. - - New in Docutils 0.3.10: It is also possible to specify a `length - value`_. - -``width`` : integer - The width of the image in pixels, used to reserve space or scale - the image horizontally. As with "height" above, when the "scale" - option is also specified, they are combined. - - New in Docutils 0.3.10: It is also possible to specify a length_ - or `percentage value`_ (which is relative to the current line - width). - - .. _length: - .. _length value: restructuredtext.html#length-units - .. _percentage value: restructuredtext.html#percentage-units - -``scale`` : integer - The uniform scaling factor of the image, a percentage (but no "%" - symbol is required or allowed). "100" means full-size, and is - equivalent to omitting a "scale" option. - - If no "height" or "width" options are specified, PIL [#PIL]_ may - be used to determine them, if PIL is installed and the image file - is available. - -``align`` : "top", "middle", "bottom", "left", "center", or "right" - The alignment of the image, equivalent to the HTML ``<img>`` tag's - "align" attribute. The values "top", "middle", and "bottom" - control an image's vertical alignment (relative to the text - baseline); they are only useful for inline images (substitutions). - The values "left", "center", and "right" control an image's - horizontal alignment, allowing the image to float and have the - text flow around it. The specific behavior depends upon the - browser or rendering software used. - -``target`` : text (URI or reference name) - Makes the image into a hyperlink reference ("clickable"). The - option argument may be a URI (relative or absolute), or a - reference name with underscore suffix (e.g. ``name_``). - -``class`` : text - Set a "class" attribute value on the image element. See the - class_ directive below. - - -Figure -====== - -:Directive Type: "figure" -:Doctree Elements: figure, image, caption, legend -:Directive Arguments: One, required (image URI). -:Directive Options: Possible. -:Directive Content: Interpreted as the figure caption and an optional - legend. - -A "figure" consists of image_ data (including `image options`_), an -optional caption (a single paragraph), and an optional legend -(arbitrary body elements):: - - .. figure:: picture.png - :scale: 50 - :alt: map to buried treasure - - This is the caption of the figure (a simple paragraph). - - The legend consists of all elements after the caption. In this - case, the legend consists of this paragraph and the following - table: - - +-----------------------+-----------------------+ - | Symbol | Meaning | - +=======================+=======================+ - | .. image:: tent.png | Campground | - +-----------------------+-----------------------+ - | .. image:: waves.png | Lake | - +-----------------------+-----------------------+ - | .. image:: peak.png | Mountain | - +-----------------------+-----------------------+ - -There must be blank lines before the caption paragraph and before the -legend. To specify a legend without a caption, use an empty comment -("..") in place of the caption. - -The "figure" directive supports all of the options of the "image" -directive (see `image options`_ above). In addition, the following -options are recognized: - -``figwidth`` : integer or "image" - The width of the figure in pixels, to limit the horizontal space - used. A special value of "image" is allowed, in which case the - included image's actual width is used (requires PIL [#PIL]_). If - the image file is not found or the required software is - unavailable, this option is ignored. - - Sets the "width" attribute of the "figure" doctree element. - - This option does not scale the included image; use the "width" - `image`_ option for that. :: - - +---------------------------+ - | figure | - | | - |<------ figwidth --------->| - | | - | +---------------------+ | - | | image | | - | | | | - | |<--- width --------->| | - | +---------------------+ | - | | - |The figure's caption should| - |wrap at this width. | - +---------------------------+ - -``figclass`` : text - Set a "class" attribute value on the figure element. See the - class_ directive below. - -``align`` : "left", "center", or "right" - The horizontal alignment of the figure, allowing the image to - float and have the text flow around it. The specific behavior - depends upon the browser or rendering software used. - -.. [#PIL] `Python Imaging Library`_. - -.. _Python Imaging Library: http://www.pythonware.com/products/pil/ - - ---------------- - Body Elements ---------------- - -Topic -===== - -:Directive Type: "topic" -:Doctree Element: topic -:Directive Arguments: 1, required (topic title). -:Directive Options: Possible. -:Directive Content: Interpreted as the topic body. - -A topic is like a block quote with a title, or a self-contained -section with no subsections. Use the "topic" directive to indicate a -self-contained idea that is separate from the flow of the document. -Topics may occur anywhere a section or transition may occur. Body -elements and topics may not contain nested topics. - -The directive's sole argument is interpreted as the topic title; the -next line must be blank. All subsequent lines make up the topic body, -interpreted as body elements. For example:: - - .. topic:: Topic Title - - Subsequent indented lines comprise - the body of the topic, and are - interpreted as body elements. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the topic element. See the - class_ directive below. - - -Sidebar -======= - -:Directive Type: "sidebar" -:Doctree Element: sidebar -:Directive Arguments: One, required (sidebar title). -:Directive Options: Possible. -:Directive Content: Interpreted as the sidebar body. - -Sidebars are like miniature, parallel documents that occur inside -other documents, providing related or reference material. A sidebar -is typically offset by a border and "floats" to the side of the page; -the document's main text may flow around it. Sidebars can also be -likened to super-footnotes; their content is outside of the flow of -the document's main text. - -Sidebars may occur anywhere a section or transition may occur. Body -elements (including sidebars) may not contain nested sidebars. - -The directive's sole argument is interpreted as the sidebar title, -which may be followed by a subtitle option (see below); the next line -must be blank. All subsequent lines make up the sidebar body, -interpreted as body elements. For example:: - - .. sidebar:: Sidebar Title - :subtitle: Optional Sidebar Subtitle - - Subsequent indented lines comprise - the body of the sidebar, and are - interpreted as body elements. - -The following options are recognized: - -``subtitle`` : text - The sidebar's subtitle. - -``class`` : text - Set a "class" attribute value on the sidebar element. See the - class_ directive below. - - -Line Block -========== - -.. admonition:: Deprecated - - The "line-block" directive is deprecated. Use the `line block - syntax`_ instead. - - .. _line block syntax: restructuredtext.html#line-blocks - -:Directive Type: "line-block" -:Doctree Element: line_block -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: Becomes the body of the line block. - -The "line-block" directive constructs an element where line breaks and -initial indentation is significant and inline markup is supported. It -is equivalent to a `parsed literal block`_ with different rendering: -typically in an ordinary serif typeface instead of a -typewriter/monospaced face, and not automatically indented. (Have the -line-block directive begin a block quote to get an indented line -block.) Line blocks are useful for address blocks and verse (poetry, -song lyrics), where the structure of lines is significant. For -example, here's a classic:: - - "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by - Ewan McTeagle (for Lassie O'Shea): - - .. line-block:: - - Lend us a couple of bob till Thursday. - I'm absolutely skint. - But I'm expecting a postal order and I can pay you back - as soon as it comes. - Love, Ewan. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the line_block element. See the - class_ directive below. - - -.. _parsed-literal: - -Parsed Literal Block -==================== - -:Directive Type: "parsed-literal" -:Doctree Element: literal_block -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: Becomes the body of the literal block. - -Unlike an ordinary literal block, the "parsed-literal" directive -constructs a literal block where the text is parsed for inline markup. -It is equivalent to a `line block`_ with different rendering: -typically in a typewriter/monospaced typeface, like an ordinary -literal block. Parsed literal blocks are useful for adding hyperlinks -to code examples. - -However, care must be taken with the text, because inline markup is -recognized and there is no protection from parsing. Backslash-escapes -may be necessary to prevent unintended parsing. And because the -markup characters are removed by the parser, care must also be taken -with vertical alignment. Parsed "ASCII art" is tricky, and extra -whitespace may be necessary. - -For example, all the element names in this content model are links:: - - .. parsed-literal:: - - ( (title_, subtitle_?)?, - decoration_?, - (docinfo_, transition_?)?, - `%structure.model;`_ ) - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the literal_block element. See - the class_ directive below. - - -Rubric -====== - -:Directive Type: "rubric" -:Doctree Element: rubric -:Directive Arguments: 1, required (rubric text). -:Directive Options: Possible. -:Directive Content: None. - -.. - - rubric n. 1. a title, heading, or the like, in a manuscript, - book, statute, etc., written or printed in red or otherwise - distinguished from the rest of the text. ... - - -- Random House Webster's College Dictionary, 1991 - -The "rubric" directive inserts a "rubric" element into the document -tree. A rubric is like an informal heading that doesn't correspond to -the document's structure. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the rubric element. See the - class_ directive below. - - -Epigraph -======== - -:Directive Type: "epigraph" -:Doctree Element: block_quote -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as the body of the block quote. - -An epigraph is an apposite (suitable, apt, or pertinent) short -inscription, often a quotation or poem, at the beginning of a document -or section. - -The "epigraph" directive produces an "epigraph"-class block quote. -For example, this input:: - - .. epigraph:: - - No matter where you go, there you are. - - -- Buckaroo Banzai - -becomes this document tree fragment:: - - <block_quote class="epigraph"> - <paragraph> - No matter where you go, there you are. - <attribution> - Buckaroo Banzai - - -Highlights -========== - -:Directive Type: "highlights" -:Doctree Element: block_quote -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as the body of the block quote. - -Highlights summarize the main points of a document or section, often -consisting of a list. - -The "highlights" directive produces a "highlights"-class block quote. -See Epigraph_ above for an analogous example. - - -Pull-Quote -========== - -:Directive Type: "pull-quote" -:Doctree Element: block_quote -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as the body of the block quote. - -A pull-quote is a small selection of text "pulled out and quoted", -typically in a larger typeface. Pull-quotes are used to attract -attention, especially in long articles. - -The "pull-quote" directive produces a "pull-quote"-class block quote. -See Epigraph_ above for an analogous example. - - -.. _compound: - -Compound Paragraph -================== - -:Directive Type: "compound" -:Doctree Element: compound -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: Interpreted as body elements. - -(New in Docutils 0.3.6) - -The "compound" directive is used to create a compound paragraph, which -is a single logical paragraph containing multiple physical body -elements such as simple paragraphs, literal blocks, tables, lists, -etc., instead of directly containing text and inline elements. For -example:: - - .. compound:: - - The 'rm' command is very dangerous. If you are logged - in as root and enter :: - - cd / - rm -rf * - - you will erase the entire contents of your file system. - -In the example above, a literal block is "embedded" within a sentence -that begins in one physical paragraph and ends in another. - -.. note:: - - The "compound" directive is *not* a generic block-level container - like HTML's ``<div>`` element. Do not use it only to group a - sequence of elements, or you may get unexpected results. - - If you need a generic block-level container, please use the - container_ directive, described below. - -Compound paragraphs are typically rendered as multiple distinct text -blocks, with the possibility of variations to emphasize their logical -unity: - -* If paragraphs are rendered with a first-line indent, only the first - physical paragraph of a compound paragraph should have that indent - -- second and further physical paragraphs should omit the indents; -* vertical spacing between physical elements may be reduced; -* and so on. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the compound element. See the - class_ directive below. - - -Container -========= - -:Directive Type: "container" -:Doctree Element: container -:Directive Arguments: One or more, optional (class names). -:Directive Options: None. -:Directive Content: Interpreted as body elements. - -(New in Docutils 0.3.10) - -The "container" directive surrounds its contents (arbitrary body -elements) with a generic block-level "container" element. Combined -with the optional "class_" attribute argument(s), this is an extension -mechanism for users & applications. For example:: - - .. container:: custom - - This paragraph might be rendered in a custom way. - -Parsing the above results in the following pseudo-XML:: - - <container classes="custom"> - <paragraph> - This paragraph might be rendered in a custom way. - -The "container" directive is the equivalent of HTML's ``<div>`` -element. It may be used to group a sequence of elements for user- or -application-specific purposes. - - --------- - Tables --------- - -Formal tables need more structure than the reStructuredText syntax -supplies. Tables may be given titles with the table_ directive. -Sometimes reStructuredText tables are inconvenient to write, or table -data in a standard format is readily available. The csv-table_ -directive supports CSV data. - - -Table -===== - -:Directive Type: "table" -:Doctree Element: table -:Directive Arguments: 1, optional (table title). -:Directive Options: Possible. -:Directive Content: A normal reStructuredText table. - -(New in Docutils 0.3.1) - -The "table" directive is used to create a titled table, to associate a -title with a table:: - - .. table:: Truth table for "not" - - ===== ===== - A not A - ===== ===== - False True - True False - ===== ===== - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the table element. See the - class_ directive below. - - -.. _csv-table: - -CSV Table -========= - -:Directive Type: "csv-table" -:Doctree Element: table -:Directive Arguments: 1, optional (table title). -:Directive Options: Possible. -:Directive Content: A CSV (comma-separated values) table. - -.. WARNING:: - - The "csv-table" directive's ":file:" and ":url:" options represent - a potential security holes. They can be disabled with the - "file_insertion_enabled_" runtime setting. - -.. Note:: - - The "csv-table" directive requires the ``csv.py`` module of the - Python standard library, which was added in Python 2.3. It will - not work with earlier versions of Python. Using the "csv-table" - directive in a document will make the document **incompatible** - with systems using Python 2.1 or 2.2. - -(New in Docutils 0.3.4) - -The "csv-table" directive is used to create a table from CSV -(comma-separated values) data. CSV is a common data format generated -by spreadsheet applications and commercial databases. The data may be -internal (an integral part of the document) or external (a separate -file). - -Example:: - - .. csv-table:: Frozen Delights! - :header: "Treat", "Quantity", "Description" - :widths: 15, 10, 30 - - "Albatross", 2.99, "On a stick!" - "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be - crunchy, now would it?" - "Gannet Ripple", 1.99, "On a stick!" - -Block markup and inline markup within cells is supported. Line ends -are recognized within cells. - -Working limitations: - -* Whitespace delimiters are supported only for external CSV files. - -* There is no support for checking that the number of columns in each - row is the same. However, this directive supports CSV generators - that do not insert "empty" entries at the end of short rows, by - automatically adding empty entries. - - .. Add "strict" option to verify input? - -The following options are recognized: - -``class`` : text - Set a "class" attribute value on the table element. See the - class_ directive below. - -``widths`` : integer [, integer...] - A comma- or space-separated list of relative column widths. The - default is equal-width columns (100%/#columns). - -``header-rows`` : integer - The number of rows of CSV data to use in the table header. - Defaults to 0. - -``stub-columns`` : integer - The number of table columns to use as stubs (row titles, on the - left). Defaults to 0. - -``header`` : CSV data - Supplemental data for the table header, added independently of and - before any ``header-rows`` from the main CSV data. Must use the - same CSV format as the main CSV data. - -``file`` : string (newlines removed) - The local filesystem path to a CSV data file. - -``url`` : string (whitespace removed) - An Internet URL reference to a CSV data file. - -``encoding`` : name of text encoding - The text encoding of the external CSV data (file or URL). - Defaults to the document's encoding (if specified). - -``delim`` : char | "tab" | "space" - A one-character string used to separate fields. Defaults to ``,`` - (comma). May be specified as a Unicode code point; see the - unicode_ directive for syntax details. - -``quote`` : char - A one-character string used to quote elements containing the - delimiter or which start with the quote character. Defaults to - ``"`` (quote). May be specified as a Unicode code point; see the - unicode_ directive for syntax details. - -``keepspace`` : flag - Treat whitespace immediately following the delimiter as - significant. The default is to ignore such whitespace. - -``escape`` : char - A one-character string used to escape the delimiter or quote - characters. May be specified as a Unicode code point; see the - unicode_ directive for syntax details. Used when the delimiter is - used in an unquoted field, or when quote characters are used - within a field. The default is to double-up the character, - e.g. "He said, ""Hi!""" - - .. Add another possible value, "double", to explicitly indicate - the default case? - - -List Table -========== - -:Directive Type: "list-table" -:Doctree Element: table -:Directive Arguments: 1, optional (table title). -:Directive Options: Possible. -:Directive Content: A uniform two-level bullet list. - -(New in Docutils 0.3.8. This is an initial implementation; `further -ideas`__ may be implemented in the future.) - -__ ../../dev/rst/alternatives.html#list-driven-tables - -The "list-table" directive is used to create a table from data in a -uniform two-level bullet list. "Uniform" means that each sublist -(second-level list) must contain the same number of list items. - -Example:: - - .. list-table:: Frozen Delights! - :widths: 15 10 30 - :header-rows: 1 - - * - Treat - - Quantity - - Description - * - Albatross - - 2.99 - - On a stick! - * - Crunchy Frog - - 1.49 - - If we took the bones out, it wouldn't be - crunchy, now would it? - * - Gannet Ripple - - 1.99 - - On a stick! - -The following options are recognized: - -``class`` : text - Set a "class" attribute value on the table element. See the - class_ directive below. - -``widths`` : integer [integer...] - A comma- or space-separated list of relative column widths. The - default is equal-width columns (100%/#columns). - -``header-rows`` : integer - The number of rows of list data to use in the table header. - Defaults to 0. - -``stub-columns`` : integer - The number of table columns to use as stubs (row titles, on the - left). Defaults to 0. - - ----------------- - Document Parts ----------------- - -.. _contents: - -Table of Contents -================= - -:Directive Type: "contents" -:Doctree Elements: pending, topic -:Directive Arguments: One, optional: title. -:Directive Options: Possible. -:Directive Content: None. - -The "contents" directive generates a table of contents (TOC) in a -topic_. Topics, and therefore tables of contents, may occur anywhere -a section or transition may occur. Body elements and topics may not -contain tables of contents. - -Here's the directive in its simplest form:: - - .. contents:: - -Language-dependent boilerplate text will be used for the title. The -English default title text is "Contents". - -An explicit title may be specified:: - - .. contents:: Table of Contents - -The title may span lines, although it is not recommended:: - - .. contents:: Here's a very long Table of - Contents title - -Options may be specified for the directive, using a field list:: - - .. contents:: Table of Contents - :depth: 2 - -If the default title is to be used, the options field list may begin -on the same line as the directive marker:: - - .. contents:: :depth: 2 - -The following options are recognized: - -``depth`` : integer - The number of section levels that are collected in the table of - contents. The default is unlimited depth. - -``local`` : flag (empty) - Generate a local table of contents. Entries will only include - subsections of the section in which the directive is given. If no - explicit title is given, the table of contents will not be titled. - -``backlinks`` : "entry" or "top" or "none" - Generate links from section headers back to the table of contents - entries, the table of contents itself, or generate no backlinks. - -``class`` : text - Set a "class" attribute value on the topic element. See the - class_ directive below. - - -.. _sectnum: -.. _section-autonumbering: - -Automatic Section Numbering -=========================== - -:Directive Type: "sectnum" or "section-autonumbering" (synonyms) -:Doctree Elements: pending, generated -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: None. - -The "sectnum" (or "section-autonumbering") directive automatically -numbers sections and subsections in a document. Section numbers are -of the "multiple enumeration" form, where each level has a number, -separated by periods. For example, the title of section 1, subsection -2, subsubsection 3 would have "1.2.3" prefixed. - -The "sectnum" directive does its work in two passes: the initial parse -and a transform. During the initial parse, a "pending" element is -generated which acts as a placeholder, storing any options internally. -At a later stage in the processing, the "pending" element triggers a -transform, which adds section numbers to titles. Section numbers are -enclosed in a "generated" element, and titles have their "auto" -attribute set to "1". - -The following options are recognized: - -``depth`` : integer - The number of section levels that are numbered by this directive. - The default is unlimited depth. - -``prefix`` : string - An arbitrary string that is prefixed to the automatically - generated section numbers. It may be something like "3.2.", which - will produce "3.2.1", "3.2.2", "3.2.2.1", and so on. Note that - any separating punctuation (in the example, a period, ".") must be - explicitly provided. The default is no prefix. - -``suffix`` : string - An arbitrary string that is appended to the automatically - generated section numbers. The default is no suffix. - -``start`` : integer - The value that will be used for the first section number. - Combined with ``prefix``, this may be used to force the right - numbering for a document split over several source files. The - default is 1. - - -.. _header: -.. _footer: - -Document Header & Footer -======================== - -:Directive Types: "header" and "footer" -:Doctree Elements: decoration, header, footer -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as body elements. - -(New in Docutils 0.3.8) - -The "header" and "footer" directives create document decorations, -useful for page navigation, notes, time/datestamp, etc. For example:: - - .. header:: This space for rent. - -This will add a paragraph to the document header, which will appear at -the top of the generated web page or at the top of every printed page. - -These directives may be used multiple times, cumulatively. There is -currently support for only one header and footer. - -.. note:: - - While it is possible to use the "header" and "footer" directives to - create navigational elements for web pages, you should be aware - that Docutils is meant to be used for *document* processing, and - that a navigation bar is not typically part of a document. - - Thus, you may soon find Docutils' abilities to be insufficient for - these purposes. At that time, you should consider using a - templating system (like ht2html_) rather than the "header" and - "footer" directives. - - .. _ht2html: http://ht2html.sourceforge.net/ - -In addition to the use of these directives to populate header and -footer content, content may also be added automatically by the -processing system. For example, if certain runtime settings are -enabled, the document footer is populated with processing information -such as a datestamp, a link to `the Docutils website`_, etc. - -.. _the Docutils website: http://docutils.sourceforge.net - - ------------- - References ------------- - -.. _target-notes: - -Target Footnotes -================ - -:Directive Type: "target-notes" -:Doctree Elements: pending, footnote, footnote_reference -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: None. - -The "target-notes" directive creates a footnote for each external -target in the text, and corresponding footnote references after each -reference. For every explicit target (of the form, ``.. _target name: -URL``) in the text, a footnote will be generated containing the -visible URL as content. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on all footnote_reference elements. - See the class_ directive below. - - -Footnotes -========= - -**NOT IMPLEMENTED YET** - -:Directive Type: "footnotes" -:Doctree Elements: pending, topic -:Directive Arguments: None? -:Directive Options: Possible? -:Directive Content: None. - -@@@ - - -Citations -========= - -**NOT IMPLEMENTED YET** - -:Directive Type: "citations" -:Doctree Elements: pending, topic -:Directive Arguments: None? -:Directive Options: Possible? -:Directive Content: None. - -@@@ - - ---------------- - HTML-Specific ---------------- - -Meta -==== - -:Directive Type: "meta" -:Doctree Element: meta (non-standard) -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Must contain a flat field list. - -The "meta" directive is used to specify HTML metadata stored in HTML -META tags. "Metadata" is data about data, in this case data about web -pages. Metadata is used to describe and classify web pages in the -World Wide Web, in a form that is easy for search engines to extract -and collate. - -Within the directive block, a flat field list provides the syntax for -metadata. The field name becomes the contents of the "name" attribute -of the META tag, and the field body (interpreted as a single string -without inline markup) becomes the contents of the "content" -attribute. For example:: - - .. meta:: - :description: The reStructuredText plaintext markup language - :keywords: plaintext, markup language - -This would be converted to the following HTML:: - - <meta name="description" - content="The reStructuredText plaintext markup language"> - <meta name="keywords" content="plaintext, markup language"> - -Support for other META attributes ("http-equiv", "scheme", "lang", -"dir") are provided through field arguments, which must be of the form -"attr=value":: - - .. meta:: - :description lang=en: An amusing story - :description lang=fr: Un histoire amusant - -And their HTML equivalents:: - - <meta name="description" lang="en" content="An amusing story"> - <meta name="description" lang="fr" content="Un histoire amusant"> - -Some META tags use an "http-equiv" attribute instead of the "name" -attribute. To specify "http-equiv" META tags, simply omit the name:: - - .. meta:: - :http-equiv=Content-Type: text/html; charset=ISO-8859-1 - -HTML equivalent:: - - <meta http-equiv="Content-Type" - content="text/html; charset=ISO-8859-1"> - - -Imagemap -======== - -**NOT IMPLEMENTED YET** - -Non-standard element: imagemap. - - ------------------------------------------ - Directives for Substitution Definitions ------------------------------------------ - -The directives in this section may only be used in substitution -definitions. They may not be used directly, in standalone context. -The `image`_ directive may be used both in substitution definitions -and in the standalone context. - - -.. _replace: - -Replacement Text -================ - -:Directive Type: "replace" -:Doctree Element: Text & inline elements -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: A single paragraph; may contain inline markup. - -The "replace" directive is used to indicate replacement text for a -substitution reference. It may be used within substitution -definitions only. For example, this directive can be used to expand -abbreviations:: - - .. |reST| replace:: reStructuredText - - Yes, |reST| is a long word, so I can't blame anyone for wanting to - abbreviate it. - -As reStructuredText doesn't support nested inline markup, the only way -to create a reference with styled text is to use substitutions with -the "replace" directive:: - - I recommend you try |Python|_. - - .. |Python| replace:: Python, *the* best language around - .. _Python: http://www.python.org/ - - -.. _unicode: - -Unicode Character Codes -======================= - -:Directive Type: "unicode" -:Doctree Element: Text -:Directive Arguments: One or more, required (Unicode character codes, - optional text, and comments). -:Directive Options: Possible. -:Directive Content: None. - -The "unicode" directive converts Unicode character codes (numerical -values) to characters, and may be used in substitution definitions -only. - -The arguments, separated by spaces, can be: - -* **character codes** as - - - decimal numbers or - - - hexadecimal numbers, prefixed by ``0x``, ``x``, ``\x``, ``U+``, - ``u``, or ``\u`` or as XML-style hexadecimal character entities, - e.g. ``ᨫ`` - -* **text**, which is used as-is. - -Text following " .. " is a comment and is ignored. The spaces between -the arguments are ignored and thus do not appear in the output. -Hexadecimal codes are case-insensitive. - -For example, the following text:: - - Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| - all rights reserved. - - .. |copy| unicode:: 0xA9 .. copyright sign - .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign - .. |---| unicode:: U+02014 .. em dash - :trim: - -results in: - - Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| - all rights reserved. - - .. |copy| unicode:: 0xA9 .. copyright sign - .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign - .. |---| unicode:: U+02014 .. em dash - :trim: - -The following options are recognized: - -``ltrim`` : flag - Whitespace to the left of the substitution reference is removed. - -``rtrim`` : flag - Whitespace to the right of the substitution reference is removed. - -``trim`` : flag - Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides - of the substitution reference is removed. - - -Date -==== - -:Directive Type: "date" -:Doctree Element: Text -:Directive Arguments: One, optional (date format). -:Directive Options: None. -:Directive Content: None. - -The "date" directive generates the current local date and inserts it -into the document as text. This directive may be used in substitution -definitions only. - -The optional directive content is interpreted as the desired date -format, using the same codes as Python's time.strftime function. The -default format is "%Y-%m-%d" (ISO 8601 date), but time fields can also -be used. Examples:: - - .. |date| date:: - .. |time| date:: %H:%M - - Today's date is |date|. - - This document was generated on |date| at |time|. - - ---------------- - Miscellaneous ---------------- - -.. _include: - -Including an External Document Fragment -======================================= - -:Directive Type: "include" -:Doctree Elements: depend on data being included -:Directive Arguments: One, required (path to the file to include). -:Directive Options: Possible. -:Directive Content: None. - -.. WARNING:: - - The "include" directive represents a potential security hole. It - can be disabled with the "file_insertion_enabled_" runtime setting. - - .. _file_insertion_enabled: ../../user/config.html#file-insertion-enabled - -The "include" directive reads a reStructuredText-formatted text file -and parses it in the current document's context at the point of the -directive. The directive argument is the path to the file to be -included, relative to the document containing the directive. For -example:: - - This first example will be parsed at the document level, and can - thus contain any construct, including section headers. - - .. include:: inclusion.txt - - Back in the main document. - - This second example will be parsed in a block quote context. - Therefore it may only contain body elements. It may not - contain section headers. - - .. include:: inclusion.txt - -If an included document fragment contains section structure, the title -adornments must match those of the master document. - -Standard data files intended for inclusion in reStructuredText -documents are distributed with the Docutils source code, located in -the "docutils" package in the ``docutils/parsers/rst/include`` -directory. To access these files, use the special syntax for standard -"include" data files, angle brackets around the file name:: - - .. include:: <isonum.txt> - -The current set of standard "include" data files consists of sets of -substitution definitions. See `reStructuredText Standard Substitution -Definition Sets`__ for details of the available standard data files. - -__ substitutions.html - -The following options are recognized: - -``literal`` : flag (empty) - The entire included text is inserted into the document as a single - literal block (useful for program listings). - -``encoding`` : name of text encoding - The text encoding of the external data file. Defaults to the - document's encoding (if specified). - - -.. _raw: - -Raw Data Pass-Through -===================== - -:Directive Type: "raw" -:Doctree Element: raw -:Directive Arguments: One or more, required (output format types). -:Directive Options: Possible. -:Directive Content: Stored verbatim, uninterpreted. None (empty) if a - "file" or "url" option given. - -.. WARNING:: - - The "raw" directive represents a potential security hole. It can - be disabled with the "raw_enabled_" or "file_insertion_enabled_" - runtime settings. - - .. _raw_enabled: ../../user/config.html#raw-enabled - -.. Caution:: - - The "raw" directive is a stop-gap measure allowing the author to - bypass reStructuredText's markup. It is a "power-user" feature - that should not be overused or abused. The use of "raw" ties - documents to specific output formats and makes them less portable. - - If you often need to use the "raw" directive or a "raw"-derived - interpreted text role, that is a sign either of overuse/abuse or - that functionality may be missing from reStructuredText. Please - describe your situation in a message to the Docutils-users_ mailing - list. - -.. _Docutils-users: ../../user/mailing-lists.html#docutils-users - -The "raw" directive indicates non-reStructuredText data that is to be -passed untouched to the Writer. The names of the output formats are -given in the directive arguments. The interpretation of the raw data -is up to the Writer. A Writer may ignore any raw output not matching -its format. - -For example, the following input would be passed untouched by an HTML -Writer:: - - .. raw:: html - - <hr width=50 size=10> - -A LaTeX Writer could insert the following raw content into its -output stream:: - - .. raw:: latex - - \setlength{\parindent}{0pt} - -Raw data can also be read from an external file, specified in a -directive option. In this case, the content block must be empty. For -example:: - - .. raw:: html - :file: inclusion.html - -The following options are recognized: - -``file`` : string (newlines removed) - The local filesystem path of a raw data file to be included. - -``url`` : string (whitespace removed) - An Internet URL reference to a raw data file to be included. - -``encoding`` : name of text encoding - The text encoding of the external raw data (file or URL). - Defaults to the document's encoding (if specified). - - -Class -===== - -:Directive Type: "class" -:Doctree Element: pending -:Directive Arguments: One or more, required (class names / attribute - values). -:Directive Options: None. -:Directive Content: Optional. If present, it is interpreted as body - elements. - -The "class" directive sets the "class" attribute value on its content -or on the first immediately following non-comment element [#]_. For -details of the "class" attribute, see `its entry`__ in `The Docutils -Document Tree`_. The directive argument consists of one or more -space-separated class names, which are converted to lowercase and all -non-alphanumeric characters are converted to hyphens. (For the -rationale, see below.) - -__ ../doctree.html#class - -Examples:: - - .. class:: special - - This is a "special" paragraph. - - .. class:: exceptional remarkable - - An Exceptional Section - ====================== - - This is an ordinary paragraph. - - .. class:: multiple - - First paragraph. - - Second paragraph. - -The text above is parsed and transformed into this doctree fragment:: - - <paragraph class="special"> - This is a "special" paragraph. - <section class="exceptional remarkable"> - <title> - An Exceptional Section - <paragraph> - This is an ordinary paragraph. - <paragraph class="multiple"> - First paragraph. - <paragraph class="multiple"> - Second paragraph. - -.. [#] To set a "class" attribute value on a block quote, the "class" - directive must be followed by an empty comment:: - - .. class:: highlights - .. - - Block quote text. - - The directive doesn't allow content, therefore an empty comment is - required to terminate the directive. Without the empty comment, - the block quote text would be interpreted as the "class" - directive's content, and the parser would complain. - -.. topic:: Rationale for Class Attribute Value Conversion - - Docutils identifiers are converted to conform to the regular - expression ``[a-z](-?[a-z0-9]+)*``. For CSS compatibility, - identifiers (the "class" and "id" attributes) should have no - underscores, colons, or periods. Hyphens may be used. - - - The `HTML 4.01 spec`_ defines identifiers based on SGML tokens: - - ID and NAME tokens must begin with a letter ([A-Za-z]) and - may be followed by any number of letters, digits ([0-9]), - hyphens ("-"), underscores ("_"), colons (":"), and periods - ("."). - - - However the `CSS1 spec`_ defines identifiers based on the "name" - token, a tighter interpretation ("flex" tokenizer notation - below; "latin1" and "escape" 8-bit characters have been replaced - with entities):: - - unicode \\[0-9a-f]{1,4} - latin1 [¡-ÿ] - escape {unicode}|\\[ -~¡-ÿ] - nmchar [-a-z0-9]|{latin1}|{escape} - name {nmchar}+ - - The CSS1 "nmchar" rule does not include underscores ("_"), colons - (":"), or periods ("."), therefore "class" and "id" attributes - should not contain these characters. They should be replaced with - hyphens ("-"). Combined with HTML's requirements (the first - character must be a letter; no "unicode", "latin1", or "escape" - characters), this results in the ``[a-z](-?[a-z0-9]+)*`` pattern. - - .. _HTML 4.01 spec: http://www.w3.org/TR/html401/ - .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1 - - -.. _role: - -Custom Interpreted Text Roles -============================= - -:Directive Type: "role" -:Doctree Element: None; affects subsequent parsing. -:Directive Arguments: Two; one required (new role name), one optional - (base role name, in parentheses). -:Directive Options: Possible (depends on base role). -:Directive Content: depends on base role. - -(New in Docutils 0.3.2) - -The "role" directive dynamically creates a custom interpreted text -role and registers it with the parser. This means that after -declaring a role like this:: - - .. role:: custom - -the document may use the new "custom" role:: - - An example of using :custom:`interpreted text` - -This will be parsed into the following document tree fragment:: - - <paragraph> - An example of using - <inline class="custom"> - interpreted text - -The role must be declared in a document before it can be used. - -The new role may be based on an existing role, specified as a second -argument in parentheses (whitespace optional):: - - .. role:: custom(emphasis) - - :custom:`text` - -The parsed result is as follows:: - - <paragraph> - <emphasis class="custom"> - text - -If no base role is explicitly specified, a generic custom role is -automatically used. Subsequent interpreted text will produce an -"inline" element with a "class" attribute, as in the first example -above. - -With most roles, the ":class:" option can be used to set a "class" -attribute that is different from the role name. For example:: - - .. role:: custom - :class: special - - :custom:`interpreted text` - -This is the parsed result:: - - <paragraph> - <inline class="special"> - interpreted text - -.. _role class: - -The following option is recognized by the "role" directive for most -base roles: - -``class`` : text - Set a "class" attribute value on the element produced (``inline``, - or element associated with a base class) when the custom - interpreted text role is used. If no directive options are - specified, a "class" option with the directive argument (role - name) as the value is implied. See the class_ directive above. - -Specific base roles may support other options and/or directive -content. See the `reStructuredText Interpreted Text Roles`_ document -for details. - -.. _reStructuredText Interpreted Text Roles: roles.html - - -.. _default-role: - -Setting the Default Interpreted Text Role -========================================= - -:Directive Type: "default-role" -:Doctree Element: None; affects subsequent parsing. -:Directive Arguments: One, optional (new default role name). -:Directive Options: None. -:Directive Content: None. - -(New in Docutils 0.3.10) - -The "default-role" directive sets the default interpreted text role, -the role that is used for interpreted text without an explicit role. -For example, after setting the default role like this:: - - .. default-role:: subscript - -any subsequent use of implicit-role interpreted text in the document -will use the "subscript" role:: - - An example of a `default` role. - -This will be parsed into the following document tree fragment:: - - <paragraph> - An example of a - <subscript> - default - role. - -Custom roles may be used (see the "role_" directive above), but it -must have been declared in a document before it can be set as the -default role. See the `reStructuredText Interpreted Text Roles`_ -document for details of built-in roles. - -The directive may be used without an argument to restore the initial -default interpreted text role, which is application-dependent. The -initial default interpreted text role of the standard reStructuredText -parser is "title-reference". - - -.. _title: - -Metadata Document Title -======================= - -:Directive Type: "title" -:Doctree Element: None. -:Directive Arguments: 1, required (the title text). -:Directive Options: None. -:Directive Content: None. - -The "title" directive specifies the document title as metadata, which -does not become part of the document body. It overrides a -document-supplied title. For example, in HTML output the metadata -document title appears in the title bar of the browser window. - - -Restructuredtext-Test-Directive -=============================== - -:Directive Type: "restructuredtext-test-directive" -:Doctree Element: system_warning -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as a literal block. - -This directive is provided for test purposes only. (Nobody is -expected to type in a name *that* long!) It is converted into a -level-1 (info) system message showing the directive data, possibly -followed by a literal block containing the rest of the directive -block. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/rst/introduction.txt b/docutils/docs/ref/rst/introduction.txt deleted file mode 100644 index b7829816e..000000000 --- a/docutils/docs/ref/rst/introduction.txt +++ /dev/null @@ -1,314 +0,0 @@ -===================================== - An Introduction to reStructuredText -===================================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get -plaintext markup syntax and parser system. It is useful for inline -program documentation (such as Python docstrings), for quickly -creating simple web pages, and for standalone documents. -reStructuredText_ is a proposed revision and reinterpretation of the -StructuredText_ and Setext_ lightweight markup systems. - -reStructuredText is designed for extensibility for specific -application domains. Its parser is a component of Docutils_. - -This document defines the goals_ of reStructuredText and provides a -history_ of the project. It is written using the reStructuredText -markup, and therefore serves as an example of its use. For a gentle -introduction to using reStructuredText, please read `A -ReStructuredText Primer`_. The `Quick reStructuredText`_ user -reference is also useful. The `reStructuredText Markup -Specification`_ is the definitive reference. There is also an -analysis of the `Problems With StructuredText`_. - -ReStructuredText's web page is -http://docutils.sourceforge.net/rst.html. - -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _StructuredText: - http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html -.. _Docutils: http://docutils.sourceforge.net/ -.. _A ReStructuredText Primer: ../../user/rst/quickstart.html -.. _Quick reStructuredText: ../../user/rst/quickref.html -.. _reStructuredText Markup Specification: restructuredtext.html -.. _Problems with StructuredText: ../../dev/rst/problems.html - - -Goals -===== - -The primary goal of reStructuredText_ is to define a markup syntax for -use in Python docstrings and other documentation domains, that is -readable and simple, yet powerful enough for non-trivial use. The -intended purpose of the reStructuredText markup is twofold: - -- the establishment of a set of standard conventions allowing the - expression of structure within plaintext, and - -- the conversion of such documents into useful structured data - formats. - -The secondary goal of reStructuredText is to be accepted by the Python -community (by way of being blessed by PythonLabs and the BDFL [#]_) as -a standard for Python inline documentation (possibly one of several -standards, to account for taste). - -.. [#] Python's creator and "Benevolent Dictator For Life", - Guido van Rossum. - -To clarify the primary goal, here are specific design goals, in order, -beginning with the most important: - -1. Readable. The marked-up text must be easy to read without any - prior knowledge of the markup language. It should be as easily - read in raw form as in processed form. - -2. Unobtrusive. The markup that is used should be as simple and - unobtrusive as possible. The simplicity of markup constructs - should be roughly proportional to their frequency of use. The most - common constructs, with natural and obvious markup, should be the - simplest and most unobtrusive. Less common constructs, for which - there is no natural or obvious markup, should be distinctive. - -3. Unambiguous. The rules for markup must not be open for - interpretation. For any given input, there should be one and only - one possible output (including error output). - -4. Unsurprising. Markup constructs should not cause unexpected output - upon processing. As a fallback, there must be a way to prevent - unwanted markup processing when a markup construct is used in a - non-markup context (for example, when documenting the markup syntax - itself). - -5. Intuitive. Markup should be as obvious and easily remembered as - possible, for the author as well as for the reader. Constructs - should take their cues from such naturally occurring sources as - plaintext email messages, newsgroup postings, and text - documentation such as README.txt files. - -6. Easy. It should be easy to mark up text using any ordinary text - editor. - -7. Scalable. The markup should be applicable regardless of the length - of the text. - -8. Powerful. The markup should provide enough constructs to produce a - reasonably rich structured document. - -9. Language-neutral. The markup should apply to multiple natural (as - well as artificial) languages, not only English. - -10. Extensible. The markup should provide a simple syntax and - interface for adding more complex general markup, and custom - markup. - -11. Output-format-neutral. The markup will be appropriate for - processing to multiple output formats, and will not be biased - toward any particular format. - -The design goals above were used as criteria for accepting or -rejecting syntax, or selecting between alternatives. - -It is emphatically *not* the goal of reStructuredText to define -docstring semantics, such as docstring contents or docstring length. -These issues are orthogonal to the markup syntax and beyond the scope -of this specification. - -Also, it is not the goal of reStructuredText to maintain compatibility -with StructuredText_ or Setext_. reStructuredText shamelessly steals -their great ideas and ignores the not-so-great. - -Author's note: - - Due to the nature of the problem we're trying to solve (or, - perhaps, due to the nature of the proposed solution), the above - goals unavoidably conflict. I have tried to extract and distill - the wisdom accumulated over the years in the Python Doc-SIG_ - mailing list and elsewhere, to come up with a coherent and - consistent set of syntax rules, and the above goals by which to - measure them. - - There will inevitably be people who disagree with my particular - choices. Some desire finer control over their markup, others - prefer less. Some are concerned with very short docstrings, - others with full-length documents. This specification is an - effort to provide a reasonably rich set of markup constructs in a - reasonably simple form, that should satisfy a reasonably large - group of reasonable people. - - David Goodger (goodger@users.sourceforge.net), 2001-04-20 - -.. _Doc-SIG: http://www.python.org/sigs/doc-sig/ - - -History -======= - -reStructuredText_, the specification, is based on StructuredText_ and -Setext_. StructuredText was developed by Jim Fulton of `Zope -Corporation`_ (formerly Digital Creations) and first released in 1996. -It is now released as a part of the open-source "Z Object Publishing -Environment" (ZOPE_). Ian Feldman's and Tony Sanders' earlier Setext_ -specification was either an influence on StructuredText or, by their -similarities, at least evidence of the correctness of this approach. - -I discovered StructuredText_ in late 1999 while searching for a way to -document the Python modules in one of my projects. Version 1.1 of -StructuredText was included in Daniel Larsson's pythondoc_. Although -I was not able to get pythondoc to work for me, I found StructuredText -to be almost ideal for my needs. I joined the Python Doc-SIG_ -(Documentation Special Interest Group) mailing list and found an -ongoing discussion of the shortcomings of the StructuredText -"standard". This discussion has been going on since the inception of -the mailing list in 1996, and possibly predates it. - -I decided to modify the original module with my own extensions and -some suggested by the Doc-SIG members. I soon realized that the -module was not written with extension in mind, so I embarked upon a -general reworking, including adapting it to the "re" regular -expression module (the original inspiration for the name of this -project). Soon after I completed the modifications, I discovered that -StructuredText.py was up to version 1.23 in the ZOPE distribution. -Implementing the new syntax extensions from version 1.23 proved to be -an exercise in frustration, as the complexity of the module had become -overwhelming. - -In 2000, development on StructuredTextNG_ ("Next Generation") began at -`Zope Corporation`_ (then Digital Creations). It seems to have many -improvements, but still suffers from many of the problems of classic -StructuredText. - -I decided that a complete rewrite was in order, and even started a -`reStructuredText SourceForge project`_ (now inactive). My -motivations (the "itches" I aim to "scratch") are as follows: - -- I need a standard format for inline documentation of the programs I - write. This inline documentation has to be convertible to other - useful formats, such as HTML. I believe many others have the same - need. - -- I believe in the Setext/StructuredText idea and want to help - formalize the standard. However, I feel the current specifications - and implementations have flaws that desperately need fixing. - -- reStructuredText could form part of the foundation for a - documentation extraction and processing system, greatly benefitting - Python. But it is only a part, not the whole. reStructuredText is - a markup language specification and a reference parser - implementation, but it does not aspire to be the entire system. I - don't want reStructuredText or a hypothetical Python documentation - processor to die stillborn because of over-ambition. - -- Most of all, I want to help ease the documentation chore, the bane - of many a programmer. - -Unfortunately I was sidetracked and stopped working on this project. -In November 2000 I made the time to enumerate the problems of -StructuredText and possible solutions, and complete the first draft of -a specification. This first draft was posted to the Doc-SIG in three -parts: - -- `A Plan for Structured Text`__ -- `Problems With StructuredText`__ -- `reStructuredText: Revised Structured Text Specification`__ - -__ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html -__ http://mail.python.org/pipermail/doc-sig/2000-November/001240.html -__ http://mail.python.org/pipermail/doc-sig/2000-November/001241.html - -In March 2001 a flurry of activity on the Doc-SIG spurred me to -further revise and refine my specification, the result of which you -are now reading. An offshoot of the reStructuredText project has been -the realization that a single markup scheme, no matter how well -thought out, may not be enough. In order to tame the endless debates -on Doc-SIG, a flexible `Docstring Processing System framework`_ needed -to be constructed. This framework has become the more important of -the two projects; reStructuredText_ has found its place as one -possible choice for a single component of the larger framework. - -The project web site and the first project release were rolled out in -June 2001, including posting the second draft of the spec [#spec-2]_ -and the first draft of PEPs 256, 257, and 258 [#peps-1]_ to the -Doc-SIG. These documents and the project implementation proceeded to -evolve at a rapid pace. Implementation history details can be found -in the `project history file`_. - -In November 2001, the reStructuredText parser was nearing completion. -Development of the parser continued with the addition of small -convenience features, improvements to the syntax, the filling in of -gaps, and bug fixes. After a long holiday break, in early 2002 most -development moved over to the other Docutils components, the -"Readers", "Writers", and "Transforms". A "standalone" reader -(processes standalone text file documents) was completed in February, -and a basic HTML writer (producing HTML 4.01, using CSS-1) was -completed in early March. - -`PEP 287`_, "reStructuredText Standard Docstring Format", was created -to formally propose reStructuredText as a standard format for Python -docstrings, PEPs, and other files. It was first posted to -comp.lang.python_ and the Python-dev_ mailing list on 2002-04-02. - -Version 0.4 of the reStructuredText__ and `Docstring Processing -System`_ projects were released in April 2002. The two projects were -immediately merged, renamed to "Docutils_", and a 0.1 release soon -followed. - -.. __: `reStructuredText SourceForge project`_ - -.. [#spec-2] The second draft of the spec: - - - `An Introduction to reStructuredText`__ - - `Problems With StructuredText`__ - - `reStructuredText Markup Specification`__ - - `Python Extensions to the reStructuredText Markup - Specification`__ - - __ http://mail.python.org/pipermail/doc-sig/2001-June/001858.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001859.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001860.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001861.html - -.. [#peps-1] First drafts of the PEPs: - - - `PEP 256: Docstring Processing System Framework`__ - - `PEP 258: DPS Generic Implementation Details`__ - - `PEP 257: Docstring Conventions`__ - - Current working versions of the PEPs can be found in - http://docutils.sourceforge.net/docs/peps/, and official versions - can be found in the `master PEP repository`_. - - __ http://mail.python.org/pipermail/doc-sig/2001-June/001855.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001856.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001857.html - - -.. _Zope Corporation: http://www.zope.com -.. _ZOPE: http://www.zope.org -.. _reStructuredText SourceForge project: - http://structuredtext.sourceforge.net/ -.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ -.. _StructuredTextNG: - http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG -.. _project history file: ../../../HISTORY.html -.. _PEP 287: ../../peps/pep-0287.html -.. _Docstring Processing System framework: ../../peps/pep-0256.html -.. _comp.lang.python: news:comp.lang.python -.. _Python-dev: http://mail.python.org/pipermail/python-dev/ -.. _Docstring Processing System: http://docstring.sourceforge.net/ -.. _master PEP repository: http://www.python.org/peps/ - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/rst/restructuredtext.txt b/docutils/docs/ref/rst/restructuredtext.txt deleted file mode 100644 index 1445619b3..000000000 --- a/docutils/docs/ref/rst/restructuredtext.txt +++ /dev/null @@ -1,2879 +0,0 @@ -======================================= - reStructuredText Markup Specification -======================================= -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. Note:: - - This document is a detailed technical specification; it is not a - tutorial or a primer. If this is your first exposure to - reStructuredText, please read `A ReStructuredText Primer`_ and the - `Quick reStructuredText`_ user reference first. - -.. _A ReStructuredText Primer: ../../user/rst/quickstart.html -.. _Quick reStructuredText: ../../user/rst/quickref.html - - -reStructuredText_ is plaintext that uses simple and intuitive -constructs to indicate the structure of a document. These constructs -are equally easy to read in raw and processed forms. This document is -itself an example of reStructuredText (raw, if you are reading the -text file, or processed, if you are reading an HTML document, for -example). The reStructuredText parser is a component of Docutils_. - -Simple, implicit markup is used to indicate special constructs, such -as section headings, bullet lists, and emphasis. The markup used is -as minimal and unobtrusive as possible. Less often-used constructs -and extensions to the basic reStructuredText syntax may have more -elaborate or explicit markup. - -reStructuredText is applicable to documents of any length, from the -very small (such as inline program documentation fragments, e.g. -Python docstrings) to the quite large (this document). - -The first section gives a quick overview of the syntax of the -reStructuredText markup by example. A complete specification is given -in the `Syntax Details`_ section. - -`Literal blocks`_ (in which no markup processing is done) are used for -examples throughout this document, to illustrate the plaintext markup. - - -.. contents:: - - ------------------------ - Quick Syntax Overview ------------------------ - -A reStructuredText document is made up of body or block-level -elements, and may be structured into sections. Sections_ are -indicated through title style (underlines & optional overlines). -Sections contain body elements and/or subsections. Some body elements -contain further elements, such as lists containing list items, which -in turn may contain paragraphs and other body elements. Others, such -as paragraphs, contain text and `inline markup`_ elements. - -Here are examples of `body elements`_: - -- Paragraphs_ (and `inline markup`_):: - - Paragraphs contain text and may contain inline markup: - *emphasis*, **strong emphasis**, `interpreted text`, ``inline - literals``, standalone hyperlinks (http://www.python.org), - external hyperlinks (Python_), internal cross-references - (example_), footnote references ([1]_), citation references - ([CIT2002]_), substitution references (|example|), and _`inline - internal targets`. - - Paragraphs are separated by blank lines and are left-aligned. - -- Five types of lists: - - 1. `Bullet lists`_:: - - - This is a bullet list. - - - Bullets can be "-", "*", or "+". - - 2. `Enumerated lists`_:: - - 1. This is an enumerated list. - - 2. Enumerators may be arabic numbers, letters, or roman - numerals. - - 3. `Definition lists`_:: - - 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. - - 4. `Field lists`_:: - - :what: Field lists map field names to field bodies, like - database records. They are often part of an extension - syntax. - - :how: 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. - - 5. `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 - /V DOS/VMS-style options too - - There must be at least two spaces between the option and the - description. - -- `Literal blocks`_:: - - Literal blocks are either indented or line-prefix-quoted blocks, - and indicated with a double-colon ("::") at the end of the - preceding paragraph (right here -->):: - - if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None - -- `Block quotes`_:: - - Block quotes consist of indented body elements: - - This theory, that is mine, is mine. - - -- 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) - -- Two syntaxes for tables_: - - 1. `Grid tables`_; complete, but complex and verbose:: - - +------------------------+------------+----------+ - | Header row, column 1 | Header 2 | Header 3 | - +========================+============+==========+ - | body row 1, column 1 | column 2 | column 3 | - +------------------------+------------+----------+ - | body row 2 | Cells may span | - +------------------------+-----------------------+ - - 2. `Simple tables`_; easy and compact, but limited:: - - ==================== ========== ========== - Header row, column 1 Header 2 Header 3 - ==================== ========== ========== - body row 1, column 1 column 2 column 3 - body row 2 Cells may span columns - ==================== ====================== - -- `Explicit markup blocks`_ all begin with an explicit block marker, - two periods and a space: - - - Footnotes_:: - - .. [1] A footnote contains body elements, consistently - indented by at least 3 spaces. - - - Citations_:: - - .. [CIT2002] Just like a footnote, except the label is - textual. - - - `Hyperlink targets`_:: - - .. _Python: http://www.python.org - - .. _example: - - The "_example" target above points to this paragraph. - - - Directives_:: - - .. image:: mylogo.png - - - `Substitution definitions`_:: - - .. |symbol here| image:: symbol.png - - - Comments_:: - - .. Comments begin with two dots and a space. Anything may - follow, except for the syntax of footnotes/citations, - hyperlink targets, directives, or substitution definitions. - - ----------------- - Syntax Details ----------------- - -Descriptions below list "doctree elements" (document tree element -names; XML DTD generic identifiers) corresponding to syntax -constructs. For details on the hierarchy of elements, please see `The -Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document -type definition. - - -Whitespace -========== - -Spaces are recommended for indentation_, but tabs may also be used. -Tabs will be converted to spaces. Tab stops are at every 8th column. - -Other whitespace characters (form feeds [chr(12)] and vertical tabs -[chr(11)]) are converted to single spaces before processing. - - -Blank Lines ------------ - -Blank lines are used to separate paragraphs and other elements. -Multiple successive blank lines are equivalent to a single blank line, -except within literal blocks (where all whitespace is preserved). -Blank lines may be omitted when the markup makes element separation -unambiguous, in conjunction with indentation. The first line of a -document is treated as if it is preceded by a blank line, and the last -line of a document is treated as if it is followed by a blank line. - - -Indentation ------------ - -Indentation is used to indicate -- and is only significant in -indicating -- block quotes, definitions (in definition list items), -and local nested content: - -- list item content (multi-line contents of list items, and multiple - body elements within a list item, including nested lists), -- the content of literal blocks, and -- the content of explicit markup blocks. - -Any text whose indentation is less than that of the current level -(i.e., unindented text or "dedents") ends the current level of -indentation. - -Since all indentation is significant, the level of indentation must be -consistent. For example, indentation is the sole markup indicator for -`block quotes`_:: - - This is a top-level paragraph. - - This paragraph belongs to a first-level block quote. - - Paragraph 2 of the first-level block quote. - -Multiple levels of indentation within a block quote will result in -more complex structures:: - - This is a top-level paragraph. - - This paragraph belongs to a first-level block quote. - - This paragraph belongs to a second-level block quote. - - Another top-level paragraph. - - This paragraph belongs to a second-level block quote. - - This paragraph belongs to a first-level block quote. The - second-level block quote above is inside this first-level - block quote. - -When a paragraph or other construct consists of more than one line of -text, the lines must be left-aligned:: - - This is a paragraph. The lines of - this paragraph are aligned at the left. - - This paragraph has problems. The - lines are not left-aligned. In addition - to potential misinterpretation, warning - and/or error messages will be generated - by the parser. - -Several constructs begin with a marker, and the body of the construct -must be indented relative to the marker. For constructs using simple -markers (`bullet lists`_, `enumerated lists`_, footnotes_, citations_, -`hyperlink targets`_, directives_, and comments_), the level of -indentation of the body is determined by the position of the first -line of text, which begins on the same line as the marker. For -example, bullet list bodies must be indented by at least two columns -relative to the left edge of the bullet:: - - - This is the first line of a bullet list - item's paragraph. All lines must align - relative to the first line. [1]_ - - This indented paragraph is interpreted - as a block quote. - - Because it is not sufficiently indented, - this paragraph does not belong to the list - item. - - .. [1] Here's a footnote. The second line is aligned - with the beginning of the footnote label. The ".." - marker is what determines the indentation. - -For constructs using complex markers (`field lists`_ and `option -lists`_), where the marker may contain arbitrary text, the indentation -of the first line *after* the marker determines the left edge of the -body. For example, field lists may have very long markers (containing -the field names):: - - :Hello: This field has a short field name, so aligning the field - body with the first line is feasible. - - :Number-of-African-swallows-required-to-carry-a-coconut: It would - be very difficult to align the field body with the left edge - of the first line. It may even be preferable not to begin the - body on the same line as the marker. - - -Escaping Mechanism -================== - -The character set universally available to plaintext documents, 7-bit -ASCII, is limited. No matter what characters are used for markup, -they will already have multiple meanings in written text. Therefore -markup characters *will* sometimes appear in text **without being -intended as markup**. Any serious markup system requires an escaping -mechanism to override the default meaning of the characters used for -the markup. In reStructuredText we use the backslash, commonly used -as an escaping character in other domains. - -A backslash followed by any character (except whitespace characters) -escapes that character. The escaped character represents the -character itself, and is prevented from playing a role in any markup -interpretation. The backslash is removed from the output. A literal -backslash is represented by two backslashes in a row (the first -backslash "escapes" the second, preventing it being interpreted in an -"escaping" role). - -Backslash-escaped whitespace characters are removed from the document. -This allows for character-level `inline markup`_. - -There are two contexts in which backslashes have no special meaning: -literal blocks and inline literals. In these contexts, a single -backslash represents a literal backslash, without having to double up. - -Please note that the reStructuredText specification and parser do not -address the issue of the representation or extraction of text input -(how and in what form the text actually *reaches* the parser). -Backslashes and other characters may serve a character-escaping -purpose in certain contexts and must be dealt with appropriately. For -example, Python uses backslashes in strings to escape certain -characters, but not others. The simplest solution when backslashes -appear in Python docstrings is to use raw docstrings:: - - r"""This is a raw docstring. Backslashes (\) are not touched.""" - - -Reference Names -=============== - -Simple reference names are single words consisting of alphanumerics -plus isolated (no two adjacent) internal hyphens, underscores, and -periods; no whitespace or other characters are allowed. Footnote -labels (Footnotes_ & `Footnote References`_), citation labels -(Citations_ & `Citation References`_), `interpreted text`_ roles, and -some `hyperlink references`_ use the simple reference name syntax. - -Reference names using punctuation or whose names are phrases (two or -more space-separated words) are called "phrase-references". -Phrase-references are expressed by enclosing the phrase in backquotes -and treating the backquoted text as a reference name:: - - Want to learn about `my favorite programming language`_? - - .. _my favorite programming language: http://www.python.org - -Simple reference names may also optionally use backquotes. - -Reference names are whitespace-neutral and case-insensitive. When -resolving reference names internally: - -- whitespace is normalized (one or more spaces, horizontal or vertical - tabs, newlines, carriage returns, or form feeds, are interpreted as - a single space), and - -- case is normalized (all alphabetic characters are converted to - lowercase). - -For example, the following `hyperlink references`_ are equivalent:: - - - `A HYPERLINK`_ - - `a hyperlink`_ - - `A - Hyperlink`_ - -Hyperlinks_, footnotes_, and citations_ all share the same namespace -for reference names. The labels of citations (simple reference names) -and manually-numbered footnotes (numbers) are entered into the same -database as other hyperlink names. This means that a footnote -(defined as "``.. [1]``") which can be referred to by a footnote -reference (``[1]_``), can also be referred to by a plain hyperlink -reference (1_). Of course, each type of reference (hyperlink, -footnote, citation) may be processed and rendered differently. Some -care should be taken to avoid reference name conflicts. - - -Document Structure -================== - -Document --------- - -Doctree element: document. - -The top-level element of a parsed reStructuredText document is the -"document" element. After initial parsing, the document element is a -simple container for a document fragment, consisting of `body -elements`_, transitions_, and sections_, but lacking a document title -or other bibliographic elements. The code that calls the parser may -choose to run one or more optional post-parse transforms_, -rearranging the document fragment into a complete document with a -title and possibly other metadata elements (author, date, etc.; see -`Bibliographic Fields`_). - -Specifically, there is no way to indicate a document title and -subtitle explicitly in reStructuredText. Instead, a lone top-level -section title (see Sections_ below) can be treated as the document -title. Similarly, a lone second-level section title immediately after -the "document title" can become the document subtitle. The rest of -the sections are then lifted up a level or two. See the `DocTitle -transform`_ for details. - - -Sections --------- - -Doctree elements: section, title. - -Sections are identified through their titles, which are marked up with -adornment: "underlines" below the title text, or underlines and -matching "overlines" above the title. An underline/overline is a -single repeated punctuation character that begins in column 1 and -forms a line extending at least as far as the right edge of the title -text. Specifically, an underline/overline character may be any -non-alphanumeric printable 7-bit ASCII character [#]_. When an -overline is used, the length and character used must match the -underline. Underline-only adornment styles are distinct from -overline-and-underline styles that use the same character. There may -be any number of levels of section titles, although some output -formats may have limits (HTML has 6 levels). - -.. [#] The following are all valid section title adornment - characters:: - - ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ - - Some characters are more suitable than others. The following are - recommended:: - - = - ` : . ' " ~ ^ _ * + # - -Rather than imposing a fixed number and order of section title -adornment styles, the order enforced will be the order as encountered. -The first style encountered will be an outermost title (like HTML H1), -the second style will be a subtitle, the third will be a subsubtitle, -and so on. - -Below are examples of section title styles:: - - =============== - Section Title - =============== - - --------------- - Section Title - --------------- - - Section Title - ============= - - Section Title - ------------- - - Section Title - ````````````` - - Section Title - ''''''''''''' - - Section Title - ............. - - Section Title - ~~~~~~~~~~~~~ - - Section Title - ************* - - Section Title - +++++++++++++ - - Section Title - ^^^^^^^^^^^^^ - -When a title has both an underline and an overline, the title text may -be inset, as in the first two examples above. This is merely -aesthetic and not significant. Underline-only title text may *not* be -inset. - -A blank line after a title is optional. All text blocks up to the -next title of the same or higher level are included in a section (or -subsection, etc.). - -All section title styles need not be used, nor need any specific -section title style be used. However, a document must be consistent -in its use of section titles: once a hierarchy of title styles is -established, sections must use that hierarchy. - -Each section title automatically generates a hyperlink target pointing -to the section. The text of the hyperlink target (the "reference -name") is the same as that of the section title. See `Implicit -Hyperlink Targets`_ for a complete description. - -Sections may contain `body elements`_, transitions_, and nested -sections. - - -Transitions ------------ - -Doctree element: transition. - - Instead of subheads, extra space or a type ornament between - paragraphs may be used to mark text divisions or to signal - changes in subject or emphasis. - - (The Chicago Manual of Style, 14th edition, section 1.80) - -Transitions are commonly seen in novels and short fiction, as a gap -spanning one or more lines, with or without a type ornament such as a -row of asterisks. Transitions separate other body elements. A -transition should not begin or end a section or document, nor should -two transitions be immediately adjacent. - -The syntax for a transition marker is a horizontal line of 4 or more -repeated punctuation characters. The syntax is the same as section -title underlines without title text. Transition markers require blank -lines before and after:: - - Para. - - ---------- - - Para. - -Unlike section title underlines, no hierarchy of transition markers is -enforced, nor do differences in transition markers accomplish -anything. It is recommended that a single consistent style be used. - -The processing system is free to render transitions in output in any -way it likes. For example, horizontal rules (``<hr>``) in HTML output -would be an obvious choice. - - -Body Elements -============= - -Paragraphs ----------- - -Doctree element: paragraph. - -Paragraphs consist of blocks of left-aligned text with no markup -indicating any other body element. Blank lines separate paragraphs -from each other and from other body elements. Paragraphs may contain -`inline markup`_. - -Syntax diagram:: - - +------------------------------+ - | paragraph | - | | - +------------------------------+ - - +------------------------------+ - | paragraph | - | | - +------------------------------+ - - -Bullet Lists ------------- - -Doctree elements: bullet_list, list_item. - -A text block which begins with a "-", "*", or "+", followed by -whitespace, is a bullet list item (a.k.a. "unordered" list item). -List item bodies must be left-aligned and indented relative to the -bullet; the text immediately after the bullet determines the -indentation. For example:: - - - This is the first bullet list item. The blank line above the - first list item is required; blank lines between list items - (such as below this paragraph) are optional. - - - This is the first paragraph in the second item in the list. - - This is the second paragraph in the second item in the list. - The blank line above this paragraph is required. The left edge - of this paragraph lines up with the paragraph above, both - indented relative to the bullet. - - - This is a sublist. The bullet lines up with the left edge of - the text blocks above. A sublist is a new list so requires a - blank line above and below. - - - This is the third item of the main list. - - This paragraph is not part of the list. - -Here are examples of **incorrectly** formatted bullet lists:: - - - This first line is fine. - A blank line is required between list items and paragraphs. - (Warning) - - - The following line appears to be a new sublist, but it is not: - - This is a paragraph continuation, not a sublist (since there's - no blank line). This line is also incorrectly indented. - - Warnings may be issued by the implementation. - -Syntax diagram:: - - +------+-----------------------+ - | "- " | list item | - +------| (body elements)+ | - +-----------------------+ - - -Enumerated Lists ----------------- - -Doctree elements: enumerated_list, list_item. - -Enumerated lists (a.k.a. "ordered" lists) are similar to bullet lists, -but use enumerators instead of bullets. An enumerator consists of an -enumeration sequence member and formatting, followed by whitespace. -The following enumeration sequences are recognized: - -- arabic numerals: 1, 2, 3, ... (no upper limit). -- uppercase alphabet characters: A, B, C, ..., Z. -- lower-case alphabet characters: a, b, c, ..., z. -- uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999). -- lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999). - -In addition, the auto-enumerator, "#", may be used to automatically -enumerate a list. Auto-enumerated lists may begin with explicit -enumeration, which sets the sequence. Fully auto-enumerated lists use -arabic numerals and begin with 1. (Auto-enumerated lists are new in -Docutils 0.3.8.) - -The following formatting types are recognized: - -- suffixed with a period: "1.", "A.", "a.", "I.", "i.". -- surrounded by parentheses: "(1)", "(A)", "(a)", "(I)", "(i)". -- suffixed with a right-parenthesis: "1)", "A)", "a)", "I)", "i)". - -While parsing an enumerated list, a new list will be started whenever: - -- An enumerator is encountered which does not have the same format and - sequence type as the current list (e.g. "1.", "(a)" produces two - separate lists). - -- The enumerators are not in sequence (e.g., "1.", "3." produces two - separate lists). - -It is recommended that the enumerator of the first list item be -ordinal-1 ("1", "A", "a", "I", or "i"). Although other start-values -will be recognized, they may not be supported by the output format. A -level-1 [info] system message will be generated for any list beginning -with a non-ordinal-1 enumerator. - -Lists using Roman numerals must begin with "I"/"i" or a -multi-character value, such as "II" or "XV". Any other -single-character Roman numeral ("V", "X", "L", "C", "D", "M") will be -interpreted as a letter of the alphabet, not as a Roman numeral. -Likewise, lists using letters of the alphabet may not begin with -"I"/"i", since these are recognized as Roman numeral 1. - -The second line of each enumerated list item is checked for validity. -This is to prevent ordinary paragraphs from being mistakenly -interpreted as list items, when they happen to begin with text -identical to enumerators. For example, this text is parsed as an -ordinary paragraph:: - - A. Einstein was a really - smart dude. - -However, ambiguity cannot be avoided if the paragraph consists of only -one line. This text is parsed as an enumerated list item:: - - A. Einstein was a really smart dude. - -If a single-line paragraph begins with text identical to an enumerator -("A.", "1.", "(b)", "I)", etc.), the first character will have to be -escaped in order to have the line parsed as an ordinary paragraph:: - - \A. Einstein was a really smart dude. - -Examples of nested enumerated lists:: - - 1. Item 1 initial text. - - a) Item 1a. - b) Item 1b. - - 2. a) Item 2a. - b) Item 2b. - -Example syntax diagram:: - - +-------+----------------------+ - | "1. " | list item | - +-------| (body elements)+ | - +----------------------+ - - -Definition Lists ----------------- - -Doctree elements: definition_list, definition_list_item, term, -classifier, definition. - -Each definition list item contains a term, optional classifiers, and a -definition. A term is a simple one-line word or phrase. Optional -classifiers may follow the term on the same line, each after an inline -" : " (space, colon, space). A definition is a block indented -relative to the term, and may contain multiple paragraphs and other -body elements. There may be no blank line between a term line and a -definition block (this distinguishes definition lists from `block -quotes`_). Blank lines are required before the first and after the -last definition list item, but are optional in-between. For example:: - - term 1 - Definition 1. - - term 2 - Definition 2, paragraph 1. - - Definition 2, paragraph 2. - - term 3 : classifier - Definition 3. - - term 4 : classifier one : classifier two - Definition 4. - -Inline markup is parsed in the term line before the classifier -delimiter (" : ") is recognized. The delimiter will only be -recognized if it appears outside of any inline markup. - -A definition list may be used in various ways, including: - -- As a dictionary or glossary. The term is the word itself, a - classifier may be used to indicate the usage of the term (noun, - verb, etc.), and the definition follows. - -- To describe program variables. The term is the variable name, a - classifier may be used to indicate the type of the variable (string, - integer, etc.), and the definition describes the variable's use in - the program. This usage of definition lists supports the classifier - syntax of Grouch_, a system for describing and enforcing a Python - object schema. - -Syntax diagram:: - - +----------------------------+ - | term [ " : " classifier ]* | - +--+-------------------------+--+ - | definition | - | (body elements)+ | - +----------------------------+ - - -Field Lists ------------ - -Doctree elements: field_list, field, field_name, field_body. - -Field lists are used as part of an extension syntax, such as options -for directives_, or database-like records meant for further -processing. They may also be used for two-column table-like -structures resembling database records (label & data pairs). -Applications of reStructuredText may recognize field names and -transform fields or field bodies in certain contexts. For examples, -see `Bibliographic Fields`_ below, or the "image_" and "meta_" -directives in `reStructuredText Directives`_. - -Field lists are mappings from field names to field bodies, modeled on -RFC822_ headers. A field name may consist of any characters, but -colons (":") inside of field names must be escaped with a backslash. -Inline markup is parsed in field names. Field names are -case-insensitive when further processed or transformed. The field -name, along with a single colon prefix and suffix, together form the -field marker. The field marker is followed by whitespace and the -field body. The field body may contain multiple body elements, -indented relative to the field marker. The first line after the field -name marker determines the indentation of the field body. For -example:: - - :Date: 2001-08-16 - :Version: 1 - :Authors: - Me - - Myself - - I - :Indentation: Since the field marker may be quite long, the second - and subsequent lines of the field body do not have to line up - with the first line, but they must be indented relative to the - field name marker, and they must line up with each other. - :Parameter i: integer - -The interpretation of individual words in a multi-word field name is -up to the application. The application may specify a syntax for the -field name. For example, second and subsequent words may be treated -as "arguments", quoted phrases may be treated as a single argument, -and direct support for the "name=value" syntax may be added. - -Standard RFC822_ headers cannot be used for this construct because -they are ambiguous. A word followed by a colon at the beginning of a -line is common in written text. However, in well-defined contexts -such as when a field list invariably occurs at the beginning of a -document (PEPs and email messages), standard RFC822 headers could be -used. - -Syntax diagram (simplified):: - - +--------------------+----------------------+ - | ":" field name ":" | field body | - +-------+------------+ | - | (body elements)+ | - +-----------------------------------+ - - -Bibliographic Fields -```````````````````` - -Doctree elements: docinfo, author, authors, organization, contact, -version, status, date, copyright, field, topic. - -When a field list is the first non-comment element in a document -(after the document title, if there is one), it may have its fields -transformed to document bibliographic data. This bibliographic data -corresponds to the front matter of a book, such as the title page and -copyright page. - -Certain registered field names (listed below) are recognized and -transformed to the corresponding doctree elements, most becoming child -elements of the "docinfo" element. No ordering is required of these -fields, although they may be rearranged to fit the document structure, -as noted. Unless otherwise indicated below, each of the bibliographic -elements' field bodies may contain a single paragraph only. Field -bodies may be checked for `RCS keywords`_ and cleaned up. Any -unrecognized fields will remain as generic fields in the docinfo -element. - -The registered bibliographic field names and their corresponding -doctree elements are as follows: - -- Field name "Author": author element. -- "Authors": authors. -- "Organization": organization. -- "Contact": contact. -- "Address": address. -- "Version": version. -- "Status": status. -- "Date": date. -- "Copyright": copyright. -- "Dedication": topic. -- "Abstract": topic. - -The "Authors" field may contain either: a single paragraph consisting -of a list of authors, separated by ";" or ","; or a bullet list whose -elements each contain a single paragraph per author. ";" is checked -first, so "Doe, Jane; Doe, John" will work. In some languages -(e.g. Swedish), there is no singular/plural distinction between -"Author" and "Authors", so only an "Authors" field is provided, and a -single name is interpreted as an "Author". If a single name contains -a comma, end it with a semicolon to disambiguate: ":Authors: Doe, -Jane;". - -The "Address" field is for a multi-line surface mailing address. -Newlines and whitespace will be preserved. - -The "Dedication" and "Abstract" fields may contain arbitrary body -elements. Only one of each is allowed. They become topic elements -with "Dedication" or "Abstract" titles (or language equivalents) -immediately following the docinfo element. - -This field-name-to-element mapping can be replaced for other -languages. See the `DocInfo transform`_ implementation documentation -for details. - -Unregistered/generic fields may contain one or more paragraphs or -arbitrary body elements. - - -RCS Keywords -```````````` - -`Bibliographic fields`_ recognized by the parser are normally checked -for RCS [#]_ keywords and cleaned up [#]_. RCS keywords may be -entered into source files as "$keyword$", and once stored under RCS or -CVS [#]_, they are expanded to "$keyword: expansion text $". For -example, a "Status" field will be transformed to a "status" element:: - - :Status: $keyword: expansion text $ - -.. [#] Revision Control System. -.. [#] RCS keyword processing can be turned off (unimplemented). -.. [#] Concurrent Versions System. CVS uses the same keywords as RCS. - -Processed, the "status" element's text will become simply "expansion -text". The dollar sign delimiters and leading RCS keyword name are -removed. - -The RCS keyword processing only kicks in when the field list is in -bibliographic context (first non-comment construct in the document, -after a document title if there is one). - - -Option Lists ------------- - -Doctree elements: option_list, option_list_item, option_group, option, -option_string, option_argument, description. - -Option lists are two-column lists of command-line options and -descriptions, documenting a program's options. For example:: - - -a Output all. - -b Output both (this description is - quite long). - -c arg Output just arg. - --long Output all day long. - - -p This option has two paragraphs in the description. - This is the first. - - This is the second. Blank lines may be omitted between - options (as above) or left in (as here and below). - - --very-long-option A VMS-style option. Note the adjustment for - the required two spaces. - - --an-even-longer-option - The description can also start on the next line. - - -2, --two This option has two variants. - - -f FILE, --file=FILE These two options are synonyms; both have - arguments. - - /V A VMS/DOS-style option. - -There are several types of options recognized by reStructuredText: - -- Short POSIX options consist of one dash and an option letter. -- Long POSIX options consist of two dashes and an option word; some - systems use a single dash. -- Old GNU-style "plus" options consist of one plus and an option - letter ("plus" options are deprecated now, their use discouraged). -- DOS/VMS options consist of a slash and an option letter or word. - -Please note that both POSIX-style and DOS/VMS-style options may be -used by DOS or Windows software. These and other variations are -sometimes used mixed together. The names above have been chosen for -convenience only. - -The syntax for short and long POSIX options is based on the syntax -supported by Python's getopt.py_ module, which implements an option -parser similar to the `GNU libc getopt_long()`_ function but with some -restrictions. There are many variant option systems, and -reStructuredText option lists do not support all of them. - -Although long POSIX and DOS/VMS option words may be allowed to be -truncated by the operating system or the application when used on the -command line, reStructuredText option lists do not show or support -this with any special syntax. The complete option word should be -given, supported by notes about truncation if and when applicable. - -Options may be followed by an argument placeholder, whose role and -syntax should be explained in the description text. Either a space or -an equals sign may be used as a delimiter between options and option -argument placeholders; short options ("-" or "+" prefix only) may omit -the delimiter. Option arguments may take one of two forms: - -- Begins with a letter (``[a-zA-Z]``) and subsequently consists of - letters, numbers, underscores and hyphens (``[a-zA-Z0-9_-]``). -- Begins with an open-angle-bracket (``<``) and ends with a - close-angle-bracket (``>``); any characters except angle brackets - are allowed internally. - -Multiple option "synonyms" may be listed, sharing a single -description. They must be separated by comma-space. - -There must be at least two spaces between the option(s) and the -description. The description may contain multiple body elements. The -first line after the option marker determines the indentation of the -description. As with other types of lists, blank lines are required -before the first option list item and after the last, but are optional -between option entries. - -Syntax diagram (simplified):: - - +----------------------------+-------------+ - | option [" " argument] " " | description | - +-------+--------------------+ | - | (body elements)+ | - +----------------------------------+ - - -Literal Blocks --------------- - -Doctree element: literal_block. - -A paragraph consisting of two colons ("::") signifies that the -following text block(s) comprise a literal block. The literal block -must either be indented or quoted (see below). No markup processing -is done within a literal block. It is left as-is, and is typically -rendered in a monospaced typeface:: - - This is a typical paragraph. An indented literal block follows. - - :: - - for a in [5,4,3,2,1]: # this is program code, shown as-is - print a - print "it's..." - # a literal block continues until the indentation ends - - This text has returned to the indentation of the first paragraph, - is outside of the literal block, and is therefore treated as an - ordinary paragraph. - -The paragraph containing only "::" will be completely removed from the -output; no empty paragraph will remain. - -As a convenience, the "::" is recognized at the end of any paragraph. -If immediately preceded by whitespace, both colons will be removed -from the output (this is the "partially minimized" form). When text -immediately precedes the "::", *one* colon will be removed from the -output, leaving only one colon visible (i.e., "::" will be replaced by -":"; this is the "fully minimized" form). - -In other words, these are all equivalent (please pay attention to the -colons after "Paragraph"): - -1. Expanded form:: - - Paragraph: - - :: - - Literal block - -2. Partially minimized form:: - - Paragraph: :: - - Literal block - -3. Fully minimized form:: - - Paragraph:: - - Literal block - -All whitespace (including line breaks, but excluding minimum -indentation for indented literal blocks) is preserved. Blank lines -are required before and after a literal block, but these blank lines -are not included as part of the literal block. - - -Indented Literal Blocks -``````````````````````` - -Indented literal blocks are indicated by indentation relative to the -surrounding text (leading whitespace on each line). The minimum -indentation will be removed from each line of an indented literal -block. The literal block need not be contiguous; blank lines are -allowed between sections of indented text. The literal block ends -with the end of the indentation. - -Syntax diagram:: - - +------------------------------+ - | paragraph | - | (ends with "::") | - +------------------------------+ - +---------------------------+ - | indented literal block | - +---------------------------+ - - -Quoted Literal Blocks -````````````````````` - -Quoted literal blocks are unindented contiguous blocks of text where -each line begins with the same non-alphanumeric printable 7-bit ASCII -character [#]_. A blank line ends a quoted literal block. The -quoting characters are preserved in the processed document. - -.. [#] - The following are all valid quoting characters:: - - ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ - - Note that these are the same characters as are valid for title - adornment of sections_. - -Possible uses include literate programming in Haskell and email -quoting:: - - John Doe wrote:: - - >> Great idea! - > - > Why didn't I think of that? - - You just did! ;-) - -Syntax diagram:: - - +------------------------------+ - | paragraph | - | (ends with "::") | - +------------------------------+ - +------------------------------+ - | ">" per-line-quoted | - | ">" contiguous literal block | - +------------------------------+ - - -Line Blocks ------------ - -Doctree elements: line_block, line. (New in Docutils 0.3.5.) - -Line blocks are useful for address blocks, verse (poetry, song -lyrics), and unadorned lists, where the structure of lines is -significant. Line blocks are groups of lines beginning with vertical -bar ("|") prefixes. Each vertical bar prefix indicates a new line, so -line breaks are preserved. Initial indents are also significant, -resulting in a nested structure. Inline markup is supported. -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 must be indented, but need not be aligned with the left edge of -the text above it. A line block ends with a blank line. - -This example illustrates continuation lines:: - - | Lend us a couple of bob till Thursday. - | I'm absolutely skint. - | But I'm expecting a postal order and I can pay you back - as soon as it comes. - | Love, Ewan. - -This example illustrates the nesting of line blocks, indicated by the -initial indentation of new lines:: - - 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... - -Syntax diagram:: - - +------+-----------------------+ - | "| " | line | - +------| continuation line | - +-----------------------+ - - -Block Quotes ------------- - -Doctree element: block_quote, attribution. - -A text block that is indented relative to the preceding text, without -markup indicating it to be a literal block, is a block quote. All -markup processing (for body elements and inline markup) continues -within the block quote:: - - This is an ordinary paragraph, introducing a block quote. - - "It is my business to know things. That is my trade." - - -- Sherlock Holmes - -If the final block of a block quote begins with "--", "---", or a true -em-dash (flush left within the block quote), it is interpreted as an -attribution. If the attribution consists of multiple lines, the left -edges of the second and subsequent lines must align. - -Blank lines are required before and after a block quote, but these -blank lines are not included as part of the block quote. - -Syntax diagram:: - - +------------------------------+ - | (current level of | - | indentation) | - +------------------------------+ - +---------------------------+ - | block quote | - | (body elements)+ | - | | - | -- attribution text | - | (optional) | - +---------------------------+ - - -Doctest Blocks --------------- - -Doctree element: doctest_block. - -Doctest blocks are interactive Python sessions cut-and-pasted into -docstrings. They are meant to illustrate usage by example, and -provide an elegant and powerful testing environment via the `doctest -module`_ in the Python standard library. - -Doctest blocks are text blocks which begin with ``">>> "``, the Python -interactive interpreter main prompt, and end with a blank line. -Doctest blocks are treated as a special case of literal blocks, -without requiring the literal block syntax. If both are present, the -literal block syntax takes priority over Doctest block syntax:: - - This is an ordinary paragraph. - - >>> print 'this is a Doctest block' - this is a Doctest block - - The following is a literal block:: - - >>> This is not recognized as a doctest block by - reStructuredText. It *will* be recognized by the doctest - module, though! - -Indentation is not required for doctest blocks. - - -Tables ------- - -Doctree elements: table, tgroup, colspec, thead, tbody, row, entry. - -ReStructuredText provides two syntaxes for delineating table cells: -`Grid Tables`_ and `Simple Tables`_. - -As with other body elements, blank lines are required before and after -tables. Tables' left edges should align with the left edge of -preceding text blocks; if indented, the table is considered to be part -of a block quote. - -Once isolated, each table cell is treated as a miniature document; the -top and bottom cell boundaries act as delimiting blank lines. Each -cell contains zero or more body elements. Cell contents may include -left and/or right margins, which are removed before processing. - - -Grid Tables -``````````` - -Grid tables provide a complete table representation via grid-like -"ASCII art". Grid tables allow arbitrary cell contents (body -elements), and both row and column spans. However, grid tables can be -cumbersome to produce, especially for simple data sets. The `Emacs -table mode`_ is a tool that allows easy editing of grid tables, in -Emacs. See `Simple Tables`_ for a simpler (but limited) -representation. - -Grid tables are described with a visual grid made up of the characters -"-", "=", "|", and "+". The hyphen ("-") is used for horizontal lines -(row separators). The equals sign ("=") may be used to separate -optional header rows from the table body (not supported by the `Emacs -table mode`_). The vertical bar ("|") is used for vertical lines -(column separators). The plus sign ("+") is used for intersections of -horizontal and vertical lines. Example:: - - +------------------------+------------+----------+----------+ - | 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. | - +------------------------+------------+---------------------+ - -Some care must be taken with grid tables to avoid undesired -interactions with cell text in rare cases. For example, the following -table contains a cell in row 2 spanning from column 2 to column 4:: - - +--------------+----------+-----------+-----------+ - | row 1, col 1 | column 2 | column 3 | column 4 | - +--------------+----------+-----------+-----------+ - | row 2 | | - +--------------+----------+-----------+-----------+ - | row 3 | | | | - +--------------+----------+-----------+-----------+ - -If a vertical bar is used in the text of that cell, it could have -unintended effects if accidentally aligned with column boundaries:: - - +--------------+----------+-----------+-----------+ - | row 1, col 1 | column 2 | column 3 | column 4 | - +--------------+----------+-----------+-----------+ - | row 2 | Use the command ``ls | more``. | - +--------------+----------+-----------+-----------+ - | row 3 | | | | - +--------------+----------+-----------+-----------+ - -Several solutions are possible. All that is needed is to break the -continuity of the cell outline rectangle. One possibility is to shift -the text by adding an extra space before:: - - +--------------+----------+-----------+-----------+ - | row 1, col 1 | column 2 | column 3 | column 4 | - +--------------+----------+-----------+-----------+ - | row 2 | Use the command ``ls | more``. | - +--------------+----------+-----------+-----------+ - | row 3 | | | | - +--------------+----------+-----------+-----------+ - -Another possibility is to add an extra line to row 2:: - - +--------------+----------+-----------+-----------+ - | row 1, col 1 | column 2 | column 3 | column 4 | - +--------------+----------+-----------+-----------+ - | row 2 | Use the command ``ls | more``. | - | | | - +--------------+----------+-----------+-----------+ - | row 3 | | | | - +--------------+----------+-----------+-----------+ - - -Simple Tables -````````````` - -Simple tables provide a compact and easy to type but limited -row-oriented table representation for simple data sets. Cell contents -are typically single paragraphs, although arbitrary body elements may -be represented in most cells. Simple tables allow multi-line rows (in -all but the first column) and column spans, but not row spans. See -`Grid Tables`_ above for a complete table representation. - -Simple tables are described with horizontal borders made up of "=" and -"-" characters. The equals sign ("=") is used for top and bottom -table borders, and to separate optional header rows from the table -body. The hyphen ("-") is used to indicate column spans in a single -row by underlining the joined columns, and may optionally be used to -explicitly and/or visually separate rows. - -A simple table begins with a top border of equals signs with one or -more spaces at each column boundary (two or more spaces recommended). -Regardless of spans, the top border *must* fully describe all table -columns. There must be at least two columns in the table (to -differentiate it from section headers). The last of the optional -header rows is underlined with '=', again with spaces at column -boundaries. There may not be a blank line below the header row -separator; it would be interpreted as the bottom border of the table. -The bottom boundary of the table consists of '=' underlines, also with -spaces at column boundaries. For example, here is a truth table, a -three-column table with one header row and four body rows:: - - ===== ===== ======= - A B A and B - ===== ===== ======= - False False False - True False False - False True False - True True True - ===== ===== ======= - -Underlines of '-' may be used to indicate column spans by "filling in" -column margins to join adjacent columns. Column span underlines must -be complete (they must cover all columns) and align with established -column boundaries. Text lines containing column span underlines may -not contain any other text. A column span underline applies only to -one row immediately above it. For example, here is a table with a -column span in the header:: - - ===== ===== ====== - Inputs Output - ------------ ------ - A B A or B - ===== ===== ====== - False False False - True False True - False True True - True True True - ===== ===== ====== - -Each line of text must contain spaces at column boundaries, except -where cells have been joined by column spans. Each line of text -starts a new row, except when there is a blank cell in the first -column. In that case, that line of text is parsed as a continuation -line. For this reason, cells in the first column of new rows (*not* -continuation lines) *must* contain some text; blank cells would lead -to a misinterpretation. An empty comment ("..") is sufficient and -will be omitted from the processed output (see Comments_ below). -Also, this mechanism limits cells in the first column to only one line -of text. Use `grid tables`_ if this limitation is unacceptable. - -Underlines of '-' may also be used to visually separate rows, even if -there are no column spans. This is especially useful in long tables, -where rows are many lines long. - -Blank lines are permitted within simple tables. Their interpretation -depends on the context. Blank lines *between* rows are ignored. -Blank lines *within* multi-line rows may separate paragraphs or other -body elements within cells. - -The rightmost column is unbounded; text may continue past the edge of -the table (as indicated by the table borders). However, it is -recommended that borders be made long enough to contain the entire -text. - -The following example illustrates continuation lines (row 2 consists -of two lines of text, and four lines for row 3), a blank line -separating paragraphs (row 3, column 2), and text extending past the -right edge of the table:: - - ===== ===== - col 1 col 2 - ===== ===== - 1 Second column of row 1. - 2 Second column of row 2. - Second line of paragraph. - 3 - Second column of row 3. - - - Second item in bullet - list (row 3, column 2). - ===== ===== - - -Explicit Markup Blocks ----------------------- - -An explicit markup block is a text block: - -- whose first line begins with ".." followed by whitespace (the - "explicit markup start"), -- whose second and subsequent lines (if any) are indented relative to - the first, and -- which ends before an unindented line. - -Explicit markup blocks are analogous to bullet list items, with ".." -as the bullet. The text on the lines immediately after the explicit -markup start determines the indentation of the block body. The -maximum common indentation is always removed from the second and -subsequent lines of the block body. Therefore if the first construct -fits in one line, and the indentation of the first and second -constructs should differ, the first construct should not begin on the -same line as the explicit markup start. - -Blank lines are required between explicit markup blocks and other -elements, but are optional between explicit markup blocks where -unambiguous. - -The explicit markup syntax is used for footnotes, citations, hyperlink -targets, directives, substitution definitions, and comments. - - -Footnotes -````````` - -Doctree elements: footnote, label. - -Each footnote consists of an explicit markup start (".. "), a left -square bracket, the footnote label, a right square bracket, and -whitespace, followed by indented body elements. A footnote label can -be: - -- a whole decimal number consisting of one or more digits, - -- a single "#" (denoting `auto-numbered footnotes`_), - -- a "#" followed by a simple reference name (an `autonumber label`_), - or - -- a single "*" (denoting `auto-symbol footnotes`_). - -The footnote content (body elements) must be consistently indented (by -at least 3 spaces) and left-aligned. The first body element within a -footnote may often begin on the same line as the footnote label. -However, if the first element fits on one line and the indentation of -the remaining elements differ, the first element must begin on the -line after the footnote label. Otherwise, the difference in -indentation will not be detected. - -Footnotes may occur anywhere in the document, not only at the end. -Where and how they appear in the processed output depends on the -processing system. - -Here is a manually numbered footnote:: - - .. [1] Body elements go here. - -Each footnote automatically generates a hyperlink target pointing to -itself. The text of the hyperlink target name is the same as that of -the footnote label. `Auto-numbered footnotes`_ generate a number as -their footnote label and reference name. See `Implicit Hyperlink -Targets`_ for a complete description of the mechanism. - -Syntax diagram:: - - +-------+-------------------------+ - | ".. " | "[" label "]" footnote | - +-------+ | - | (body elements)+ | - +-------------------------+ - - -Auto-Numbered Footnotes -....................... - -A number sign ("#") may be used as the first character of a footnote -label to request automatic numbering of the footnote or footnote -reference. - -The first footnote to request automatic numbering is assigned the -label "1", the second is assigned the label "2", and so on (assuming -there are no manually numbered footnotes present; see `Mixed Manual -and Auto-Numbered Footnotes`_ below). A footnote which has -automatically received a label "1" generates an implicit hyperlink -target with name "1", just as if the label was explicitly specified. - -.. _autonumber label: `autonumber labels`_ - -A footnote may specify a label explicitly while at the same time -requesting automatic numbering: ``[#label]``. These labels are called -_`autonumber labels`. Autonumber labels do two things: - -- On the footnote itself, they generate a hyperlink target whose name - is the autonumber label (doesn't include the "#"). - -- They allow an automatically numbered footnote to be referred to more - than once, as a footnote reference or hyperlink reference. For - example:: - - If [#note]_ is the first footnote reference, it will show up as - "[1]". We can refer to it again as [#note]_ and again see - "[1]". We can also refer to it as note_ (an ordinary internal - hyperlink reference). - - .. [#note] This is the footnote labeled "note". - -The numbering is determined by the order of the footnotes, not by the -order of the references. For footnote references without autonumber -labels (``[#]_``), the footnotes and footnote references must be in -the same relative order but need not alternate in lock-step. For -example:: - - [#]_ is a reference to footnote 1, and [#]_ is a reference to - footnote 2. - - .. [#] This is footnote 1. - .. [#] This is footnote 2. - .. [#] This is footnote 3. - - [#]_ is a reference to footnote 3. - -Special care must be taken if footnotes themselves contain -auto-numbered footnote references, or if multiple references are made -in close proximity. Footnotes and references are noted in the order -they are encountered in the document, which is not necessarily the -same as the order in which a person would read them. - - -Auto-Symbol Footnotes -..................... - -An asterisk ("*") may be used for footnote labels to request automatic -symbol generation for footnotes and footnote references. The asterisk -may be the only character in the label. For example:: - - Here is a symbolic footnote reference: [*]_. - - .. [*] This is the footnote. - -A transform will insert symbols as labels into corresponding footnotes -and footnote references. The number of references must be equal to -the number of footnotes. One symbol footnote cannot have multiple -references. - -The standard Docutils system uses the following symbols for footnote -marks [#]_: - -- asterisk/star ("*") -- dagger (HTML character entity "†", Unicode U+02020) -- double dagger ("‡"/U+02021) -- section mark ("§"/U+000A7) -- pilcrow or paragraph mark ("¶"/U+000B6) -- number sign ("#") -- spade suit ("♠"/U+02660) -- heart suit ("♥"/U+02665) -- diamond suit ("♦"/U+02666) -- club suit ("♣"/U+02663) - -.. [#] This list was inspired by the list of symbols for "Note - Reference Marks" in The Chicago Manual of Style, 14th edition, - section 12.51. "Parallels" ("||") were given in CMoS instead of - the pilcrow. The last four symbols (the card suits) were added - arbitrarily. - -If more than ten symbols are required, the same sequence will be -reused, doubled and then tripled, and so on ("**" etc.). - -.. Note:: When using auto-symbol footnotes, the choice of output - encoding is important. Many of the symbols used are not encodable - in certain common text encodings such as Latin-1 (ISO 8859-1). The - use of UTF-8 for the output encoding is recommended. An - alternative for HTML and XML output is to use the - "xmlcharrefreplace" `output encoding error handler`__. - -__ ../../user/config.html#output-encoding-error-handler - - -Mixed Manual and Auto-Numbered Footnotes -........................................ - -Manual and automatic footnote numbering may both be used within a -single document, although the results may not be expected. Manual -numbering takes priority. Only unused footnote numbers are assigned -to auto-numbered footnotes. The following example should be -illustrative:: - - [2]_ will be "2" (manually numbered), - [#]_ will be "3" (anonymous auto-numbered), and - [#label]_ will be "1" (labeled auto-numbered). - - .. [2] This footnote is labeled manually, so its number is fixed. - - .. [#label] This autonumber-labeled footnote will be labeled "1". - It is the first auto-numbered footnote and no other footnote - with label "1" exists. The order of the footnotes is used to - determine numbering, not the order of the footnote references. - - .. [#] This footnote will be labeled "3". It is the second - auto-numbered footnote, but footnote label "2" is already used. - - -Citations -````````` - -Citations are identical to footnotes except that they use only -non-numeric labels such as ``[note]`` or ``[GVR2001]``. Citation -labels are simple `reference names`_ (case-insensitive single words -consisting of alphanumerics plus internal hyphens, underscores, and -periods; no whitespace). Citations may be rendered separately and -differently from footnotes. For example:: - - Here is a citation reference: [CIT2002]_. - - .. [CIT2002] This is the citation. It's just like a footnote, - except the label is textual. - - -.. _hyperlinks: - -Hyperlink Targets -````````````````` - -Doctree element: target. - -These are also called _`explicit hyperlink targets`, to differentiate -them from `implicit hyperlink targets`_ defined below. - -Hyperlink targets identify a location within or outside of a document, -which may be linked to by `hyperlink references`_. - -Hyperlink targets may be named or anonymous. Named hyperlink targets -consist of an explicit markup start (".. "), an underscore, the -reference name (no trailing underscore), a colon, whitespace, and a -link block:: - - .. _hyperlink-name: link-block - -Reference names are whitespace-neutral and case-insensitive. See -`Reference Names`_ for details and examples. - -Anonymous hyperlink targets consist of an explicit markup start -(".. "), two underscores, a colon, whitespace, and a link block; there -is no reference name:: - - .. __: anonymous-hyperlink-target-link-block - -An alternate syntax for anonymous hyperlinks consists of two -underscores, a space, and a link block:: - - __ anonymous-hyperlink-target-link-block - -See `Anonymous Hyperlinks`_ below. - -There are three types of hyperlink targets: internal, external, and -indirect. - -1. _`Internal hyperlink targets` have empty link blocks. They provide - an end point allowing a hyperlink to connect one place to another - within a document. An internal hyperlink target points to the - element following the target. For example:: - - Clicking on this internal hyperlink will take us to the target_ - below. - - .. _target: - - The hyperlink target above points to this paragraph. - - Internal hyperlink targets may be "chained". Multiple adjacent - internal hyperlink targets all point to the same element:: - - .. _target1: - .. _target2: - - The targets "target1" and "target2" are synonyms; they both - point to this paragraph. - - If the element "pointed to" is an external hyperlink target (with a - URI in its link block; see #2 below) the URI from the external - hyperlink target is propagated to the internal hyperlink targets; - they will all "point to" the same URI. There is no need to - duplicate a URI. For example, all three of the following hyperlink - targets refer to the same URI:: - - .. _Python DOC-SIG mailing list archive: - .. _archive: - .. _Doc-SIG: http://mail.python.org/pipermail/doc-sig/ - - An inline form of internal hyperlink target is available; see - `Inline Internal Targets`_. - -2. _`External hyperlink targets` have an absolute or relative URI or - email address in their link blocks. For example, take the - following input:: - - See the Python_ home page for info. - - `Write to me`_ with your questions. - - .. _Python: http://www.python.org - .. _Write to me: jdoe@example.com - - After processing into HTML, the hyperlinks might be expressed as:: - - See the <a href="http://www.python.org">Python</a> home page - for info. - - <a href="mailto:jdoe@example.com">Write to me</a> with your - questions. - - An external hyperlink's URI may begin on the same line as the - explicit markup start and target name, or it may begin in an - indented text block immediately following, with no intervening - blank lines. If there are multiple lines in the link block, they - are concatenated. Any whitespace is removed (whitespace is - permitted to allow for line wrapping). The following external - hyperlink targets are equivalent:: - - .. _one-liner: http://docutils.sourceforge.net/rst.html - - .. _starts-on-this-line: http:// - docutils.sourceforge.net/rst.html - - .. _entirely-below: - http://docutils. - sourceforge.net/rst.html - - If an external hyperlink target's URI contains an underscore as its - last character, it must be escaped to avoid being mistaken for an - indirect hyperlink target:: - - This link_ refers to a file called ``underscore_``. - - .. _link: underscore\_ - - It is possible (although not generally recommended) to include URIs - directly within hyperlink references. See `Embedded URIs`_ below. - -3. _`Indirect hyperlink targets` have a hyperlink reference in their - link blocks. In the following example, target "one" indirectly - references whatever target "two" references, and target "two" - references target "three", an internal hyperlink target. In - effect, all three reference the same thing:: - - .. _one: two_ - .. _two: three_ - .. _three: - - Just as with `hyperlink references`_ anywhere else in a document, - if a phrase-reference is used in the link block it must be enclosed - in backquotes. As with `external hyperlink targets`_, the link - block of an indirect hyperlink target may begin on the same line as - the explicit markup start or the next line. It may also be split - over multiple lines, in which case the lines are joined with - whitespace before being normalized. - - For example, the following indirect hyperlink targets are - equivalent:: - - .. _one-liner: `A HYPERLINK`_ - .. _entirely-below: - `a hyperlink`_ - .. _split: `A - Hyperlink`_ - -If the reference name contains any colons, either: - -- the phrase must be enclosed in backquotes:: - - .. _`FAQTS: Computers: Programming: Languages: Python`: - http://python.faqts.com/ - -- or the colon(s) must be backslash-escaped in the link target:: - - .. _Chapter One\: "Tadpole Days": - - It's not easy being green... - -See `Implicit Hyperlink Targets`_ below for the resolution of -duplicate reference names. - -Syntax diagram:: - - +-------+----------------------+ - | ".. " | "_" name ":" link | - +-------+ block | - | | - +----------------------+ - - -Anonymous Hyperlinks -.................... - -The `World Wide Web Consortium`_ recommends in its `HTML Techniques -for Web Content Accessibility Guidelines`_ that authors should -"clearly identify the target of each link." Hyperlink references -should be as verbose as possible, but duplicating a verbose hyperlink -name in the target is onerous and error-prone. Anonymous hyperlinks -are designed to allow convenient verbose hyperlink references, and are -analogous to `Auto-Numbered Footnotes`_. They are particularly useful -in short or one-off documents. However, this feature is easily abused -and can result in unreadable plaintext and/or unmaintainable -documents. Caution is advised. - -Anonymous `hyperlink references`_ are specified with two underscores -instead of one:: - - See `the web site of my favorite programming language`__. - -Anonymous targets begin with ".. __:"; no reference name is required -or allowed:: - - .. __: http://www.python.org - -As a convenient alternative, anonymous targets may begin with "__" -only:: - - __ http://www.python.org - -The reference name of the reference is not used to match the reference -to its target. Instead, the order of anonymous hyperlink references -and targets within the document is significant: the first anonymous -reference will link to the first anonymous target. The number of -anonymous hyperlink references in a document must match the number of -anonymous targets. For readability, it is recommended that targets be -kept close to references. Take care when editing text containing -anonymous references; adding, removing, and rearranging references -require attention to the order of corresponding targets. - - -Directives -`````````` - -Doctree elements: depend on the directive. - -Directives are an extension mechanism for reStructuredText, a way of -adding support for new constructs without adding new primary syntax -(directives may support additional syntax locally). All standard -directives (those implemented and registered in the reference -reStructuredText parser) are described in the `reStructuredText -Directives`_ document, and are always available. Any other directives -are domain-specific, and may require special action to make them -available when processing the document. - -For example, here's how an image_ may be placed:: - - .. image:: mylogo.jpeg - -A figure_ (a graphic with a caption) may placed like this:: - - .. figure:: larch.png - - The larch. - -An admonition_ (note, caution, etc.) contains other body elements:: - - .. note:: This is a paragraph - - - Here is a bullet list. - -Directives are indicated by an explicit markup start (".. ") followed -by the directive type, two colons, and whitespace (together called the -"directive marker"). Directive types are case-insensitive single -words (alphanumerics plus internal hyphens, underscores, and periods; -no whitespace). Two colons are used after the directive type for -these reasons: - -- Two colons are distinctive, and unlikely to be used in common text. - -- Two colons avoids clashes with common comment text like:: - - .. Danger: modify at your own risk! - -- If an implementation of reStructuredText does not recognize a - directive (i.e., the directive-handler is not installed), a level-3 - (error) system message is generated, and the entire directive block - (including the directive itself) will be included as a literal - block. Thus "::" is a natural choice. - -The directive block is consists of any text on the first line of the -directive after the directive marker, and any subsequent indented -text. The interpretation of the directive block is up to the -directive code. There are three logical parts to the directive block: - -1. Directive arguments. -2. Directive options. -3. Directive content. - -Individual directives can employ any combination of these parts. -Directive arguments can be filesystem paths, URLs, title text, etc. -Directive options are indicated using `field lists`_; the field names -and contents are directive-specific. Arguments and options must form -a contiguous block beginning on the first or second line of the -directive; a blank line indicates the beginning of the directive -content block. If either arguments and/or options are employed by the -directive, a blank line must separate them from the directive content. -The "figure" directive employs all three parts:: - - .. figure:: larch.png - :scale: 50 - - The larch. - -Simple directives may not require any content. If a directive that -does not employ a content block is followed by indented text anyway, -it is an error. If a block quote should immediately follow a -directive, use an empty comment in-between (see Comments_ below). - -Actions taken in response to directives and the interpretation of text -in the directive content block or subsequent text block(s) are -directive-dependent. See `reStructuredText Directives`_ for details. - -Directives are meant for the arbitrary processing of their contents, -which can be transformed into something possibly unrelated to the -original text. It may also be possible for directives to be used as -pragmas, to modify the behavior of the parser, such as to experiment -with alternate syntax. There is no parser support for this -functionality at present; if a reasonable need for pragma directives -is found, they may be supported. - -Directives do not generate "directive" elements; they are a *parser -construct* only, and have no intrinsic meaning outside of -reStructuredText. Instead, the parser will transform recognized -directives into (possibly specialized) document elements. Unknown -directives will trigger level-3 (error) system messages. - -Syntax diagram:: - - +-------+-------------------------------+ - | ".. " | directive type "::" directive | - +-------+ block | - | | - +-------------------------------+ - - -Substitution Definitions -```````````````````````` - -Doctree element: substitution_definition. - -Substitution definitions are indicated by an explicit markup start -(".. ") followed by a vertical bar, the substitution text, another -vertical bar, whitespace, and the definition block. Substitution text -may not begin or end with whitespace. A substitution definition block -contains an embedded inline-compatible directive (without the leading -".. "), such as "image_" or "replace_". For example:: - - The |biohazard| symbol must be used on containers used to - dispose of medical waste. - - .. |biohazard| image:: biohazard.png - -It is an error for a substitution definition block to directly or -indirectly contain a circular substitution reference. - -`Substitution references`_ are replaced in-line by the processed -contents of the corresponding definition (linked by matching -substitution text). Matches are case-sensitive but forgiving; if no -exact match is found, a case-insensitive comparison is attempted. - -Substitution definitions allow the power and flexibility of -block-level directives_ to be shared by inline text. They are a way -to include arbitrarily complex inline structures within text, while -keeping the details out of the flow of text. They are the equivalent -of SGML/XML's named entities or programming language macros. - -Without the substitution mechanism, every time someone wants an -application-specific new inline structure, they would have to petition -for a syntax change. In combination with existing directive syntax, -any inline structure can be coded without new syntax (except possibly -a new directive). - -Syntax diagram:: - - +-------+-----------------------------------------------------+ - | ".. " | "|" substitution text "| " directive type "::" data | - +-------+ directive block | - | | - +-----------------------------------------------------+ - -Following are some use cases for the substitution mechanism. Please -note that most of the embedded directives shown are examples only and -have not been implemented. - -Objects - Substitution references may be used to associate ambiguous text - with a unique object identifier. - - For example, many sites may wish to implement an inline "user" - directive:: - - |Michael| and |Jon| are our widget-wranglers. - - .. |Michael| user:: mjones - .. |Jon| user:: jhl - - Depending on the needs of the site, this may be used to index the - document for later searching, to hyperlink the inline text in - various ways (mailto, homepage, mouseover Javascript with profile - and contact information, etc.), or to customize presentation of - the text (include username in the inline text, include an icon - image with a link next to the text, make the text bold or a - different color, etc.). - - The same approach can be used in documents which frequently refer - to a particular type of objects with unique identifiers but - ambiguous common names. Movies, albums, books, photos, court - cases, and laws are possible. For example:: - - |The Transparent Society| offers a fascinating alternate view - on privacy issues. - - .. |The Transparent Society| book:: isbn=0738201448 - - Classes or functions, in contexts where the module or class names - are unclear and/or interpreted text cannot be used, are another - possibility:: - - 4XSLT has the convenience method |runString|, so you don't - have to mess with DOM objects if all you want is the - transformed output. - - .. |runString| function:: module=xml.xslt class=Processor - -Images - Images are a common use for substitution references:: - - West led the |H| 3, covered by dummy's |H| Q, East's |H| K, - and trumped in hand with the |S| 2. - - .. |H| image:: /images/heart.png - :height: 11 - :width: 11 - .. |S| image:: /images/spade.png - :height: 11 - :width: 11 - - * |Red light| means stop. - * |Green light| means go. - * |Yellow light| means go really fast. - - .. |Red light| image:: red_light.png - .. |Green light| image:: green_light.png - .. |Yellow light| image:: yellow_light.png - - |-><-| is the official symbol of POEE_. - - .. |-><-| image:: discord.png - .. _POEE: http://www.poee.org/ - - The "image_" directive has been implemented. - -Styles [#]_ - Substitution references may be used to associate inline text with - an externally defined presentation style:: - - Even |the text in Texas| is big. - - .. |the text in Texas| style:: big - - The style name may be meaningful in the context of some particular - output format (CSS class name for HTML output, LaTeX style name - for LaTeX, etc), or may be ignored for other output formats (such - as plaintext). - - .. @@@ This needs to be rethought & rewritten or removed: - - Interpreted text is unsuitable for this purpose because the set - of style names cannot be predefined - it is the domain of the - content author, not the author of the parser and output - formatter - and there is no way to associate a style name - argument with an interpreted text style role. Also, it may be - desirable to use the same mechanism for styling blocks:: - - .. style:: motto - At Bob's Underwear Shop, we'll do anything to get in - your pants. - - .. style:: disclaimer - All rights reversed. Reprint what you like. - - .. [#] There may be sufficient need for a "style" mechanism to - warrant simpler syntax such as an extension to the interpreted - text role syntax. The substitution mechanism is cumbersome for - simple text styling. - -Templates - Inline markup may be used for later processing by a template - engine. For example, a Zope_ author might write:: - - Welcome back, |name|! - - .. |name| tal:: replace user/getUserName - - After processing, this ZPT output would result:: - - Welcome back, - <span tal:replace="user/getUserName">name</span>! - - Zope would then transform this to something like "Welcome back, - David!" during a session with an actual user. - -Replacement text - The substitution mechanism may be used for simple macro - substitution. This may be appropriate when the replacement text - is repeated many times throughout one or more documents, - especially if it may need to change later. A short example is - unavoidably contrived:: - - |RST| is a little annoying to type over and over, especially - when writing about |RST| itself, and spelling out the - bicapitalized word |RST| every time isn't really necessary for - |RST| source readability. - - .. |RST| replace:: reStructuredText_ - .. _reStructuredText: http://docutils.sourceforge.net/rst.html - - Substitution is also appropriate when the replacement text cannot - be represented using other inline constructs, or is obtrusively - long:: - - But still, that's nothing compared to a name like - |j2ee-cas|__. - - .. |j2ee-cas| replace:: - the Java `TM`:super: 2 Platform, Enterprise Edition Client - Access Services - __ http://developer.java.sun.com/developer/earlyAccess/ - j2eecas/ - - The "replace_" directive has been implemented. - - -Comments -```````` - -Doctree element: comment. - -Arbitrary indented text may follow the explicit markup start and will -be processed as a comment element. No further processing is done on -the comment block text; a comment contains a single "text blob". -Depending on the output formatter, comments may be removed from the -processed output. The only restriction on comments is that they not -use the same syntax as any of the other explicit markup constructs: -substitution definitions, directives, footnotes, citations, or -hyperlink targets. To ensure that none of the other explicit markup -constructs is recognized, leave the ".." on a line by itself:: - - .. This is a comment - .. - _so: is this! - .. - [and] this! - .. - this:: too! - .. - |even| this:: ! - -An explicit markup start followed by a blank line and nothing else -(apart from whitespace) is an "empty comment". It serves to terminate -a preceding construct, and does **not** consume any indented text -following. To have a block quote follow a list or any indented -construct, insert an unindented empty comment in-between. - -Syntax diagram:: - - +-------+----------------------+ - | ".. " | comment | - +-------+ block | - | | - +----------------------+ - - -Implicit Hyperlink Targets -========================== - -Implicit hyperlink targets are generated by section titles, footnotes, -and citations, and may also be generated by extension constructs. -Implicit hyperlink targets otherwise behave identically to explicit -`hyperlink targets`_. - -Problems of ambiguity due to conflicting duplicate implicit and -explicit reference names are avoided by following this procedure: - -1. `Explicit hyperlink targets`_ override any implicit targets having - the same reference name. The implicit hyperlink targets are - removed, and level-1 (info) system messages are inserted. - -2. Duplicate implicit hyperlink targets are removed, and level-1 - (info) system messages inserted. For example, if two or more - sections have the same title (such as "Introduction" subsections of - a rigidly-structured document), there will be duplicate implicit - hyperlink targets. - -3. Duplicate explicit hyperlink targets are removed, and level-2 - (warning) system messages are inserted. Exception: duplicate - `external hyperlink targets`_ (identical hyperlink names and - referenced URIs) do not conflict, and are not removed. - -System messages are inserted where target links have been removed. -See "Error Handling" in `PEP 258`_. - -The parser must return a set of *unique* hyperlink targets. The -calling software (such as the Docutils_) can warn of unresolvable -links, giving reasons for the messages. - - -Inline Markup -============= - -In reStructuredText, inline markup applies to words or phrases within -a text block. The same whitespace and punctuation that serves to -delimit words in written text is used to delimit the inline markup -syntax constructs. The text within inline markup may not begin or end -with whitespace. Arbitrary `character-level inline markup`_ is -supported although not encouraged. Inline markup cannot be nested. - -There are nine inline markup constructs. Five of the constructs use -identical start-strings and end-strings to indicate the markup: - -- emphasis_: "*" -- `strong emphasis`_: "**" -- `interpreted text`_: "`" -- `inline literals`_: "``" -- `substitution references`_: "|" - -Three constructs use different start-strings and end-strings: - -- `inline internal targets`_: "_`" and "`" -- `footnote references`_: "[" and "]_" -- `hyperlink references`_: "`" and "\`_" (phrases), or just a - trailing "_" (single words) - -`Standalone hyperlinks`_ are recognized implicitly, and use no extra -markup. - -The inline markup start-string and end-string recognition rules are as -follows. If any of the conditions are not met, the start-string or -end-string will not be recognized or processed. - -1. Inline markup start-strings must start a text block or be - immediately preceded by whitespace or one of:: - - ' " ( [ { < - / : - -2. Inline markup start-strings must be immediately followed by - non-whitespace. - -3. Inline markup end-strings must be immediately preceded by - non-whitespace. - -4. Inline markup end-strings must end a text block or be immediately - followed by whitespace or one of:: - - ' " ) ] } > - / : . , ; ! ? \ - -5. If an inline markup start-string is immediately preceded by a - single or double quote, "(", "[", "{", or "<", it must not be - immediately followed by the corresponding single or double quote, - ")", "]", "}", or ">". - -6. An inline markup end-string must be separated by at least one - character from the start-string. - -7. An unescaped backslash preceding a start-string or end-string will - disable markup recognition, except for the end-string of `inline - literals`_. See `Escaping Mechanism`_ above for details. - -For example, none of the following are recognized as containing inline -markup start-strings: - -- asterisks: * "*" '*' (*) (* [*] {*} 1*x BOM32_* -- double asterisks: ** a**b O(N**2) etc. -- backquotes: ` `` etc. -- underscores: _ __ __init__ __init__() etc. -- vertical bars: | || etc. - -It may be desirable to use inline literals for some of these anyhow, -especially if they represent code snippets. It's a judgment call. - -These cases *do* require either literal-quoting or escaping to avoid -misinterpretation:: - - *4, class_, *args, **kwargs, `TeX-quoted', *ML, *.txt - -The inline markup recognition rules were devised intentionally to -allow 90% of non-markup uses of "*", "`", "_", and "|" *without* -resorting to backslashes. For 9 of the remaining 10%, use inline -literals or literal blocks:: - - "``\*``" -> "\*" (possibly in another font or quoted) - -Only those who understand the escaping and inline markup rules should -attempt the remaining 1%. ;-) - -Inline markup delimiter characters are used for multiple constructs, -so to avoid ambiguity there must be a specific recognition order for -each character. The inline markup recognition order is as follows: - -- Asterisks: `Strong emphasis`_ ("**") is recognized before emphasis_ - ("*"). - -- Backquotes: `Inline literals`_ ("``"), `inline internal targets`_ - (leading "_`", trailing "`"), are mutually independent, and are - recognized before phrase `hyperlink references`_ (leading "`", - trailing "\`_") and `interpreted text`_ ("`"). - -- Trailing underscores: Footnote references ("[" + label + "]_") and - simple `hyperlink references`_ (name + trailing "_") are mutually - independent. - -- Vertical bars: `Substitution references`_ ("|") are independently - recognized. - -- `Standalone hyperlinks`_ are the last to be recognized. - - -Character-Level Inline Markup ------------------------------ - -It is possible to mark up individual characters within a word with -backslash escapes (see `Escaping Mechanism`_ above). Backslash -escapes can be used to allow arbitrary text to immediately follow -inline markup:: - - Python ``list``\s use square bracket syntax. - -The backslash will disappear from the processed document. The word -"list" will appear as inline literal text, and the letter "s" will -immediately follow it as normal text, with no space in-between. - -Arbitrary text may immediately precede inline markup using -backslash-escaped whitespace:: - - Possible in *re*\ ``Structured``\ *Text*, though not encouraged. - -The backslashes and spaces separating "re", "Structured", and "Text" -above will disappear from the processed document. - -.. CAUTION:: - - The use of backslash-escapes for character-level inline markup is - not encouraged. Such use is ugly and detrimental to the - unprocessed document's readability. Please use this feature - sparingly and only where absolutely necessary. - - -Emphasis --------- - -Doctree element: emphasis. - -Start-string = end-string = "*". - -Text enclosed by single asterisk characters is emphasized:: - - This is *emphasized text*. - -Emphasized text is typically displayed in italics. - - -Strong Emphasis ---------------- - -Doctree element: strong. - -Start-string = end-string = "**". - -Text enclosed by double-asterisks is emphasized strongly:: - - This is **strong text**. - -Strongly emphasized text is typically displayed in boldface. - - -Interpreted Text ----------------- - -Doctree element: depends on the explicit or implicit role and -processing. - -Start-string = end-string = "`". - -Interpreted text is text that is meant to be related, indexed, linked, -summarized, or otherwise processed, but the text itself is typically -left alone. Interpreted text is enclosed by single backquote -characters:: - - This is `interpreted text`. - -The "role" of the interpreted text determines how the text is -interpreted. The role may be inferred implicitly (as above; the -"default role" is used) or indicated explicitly, using a role marker. -A role marker consists of a colon, the role name, and another colon. -A role name is a single word consisting of alphanumerics plus internal -hyphens, underscores, and periods; no whitespace or other characters -are allowed. A role marker is either a prefix or a suffix to the -interpreted text, whichever reads better; it's up to the author:: - - :role:`interpreted text` - - `interpreted text`:role: - -Interpreted text allows extensions to the available inline descriptive -markup constructs. To emphasis_, `strong emphasis`_, `inline -literals`_, and `hyperlink references`_, we can add "title reference", -"index entry", "acronym", "class", "red", "blinking" or anything else -we want. Only pre-determined roles are recognized; unknown roles will -generate errors. A core set of standard roles is implemented in the -reference parser; see `reStructuredText Interpreted Text Roles`_ for -individual descriptions. In addition, applications may support -specialized roles. - - -Inline Literals ---------------- - -Doctree element: literal. - -Start-string = end-string = "``". - -Text enclosed by double-backquotes is treated as inline literals:: - - This text is an example of ``inline literals``. - -Inline literals may contain any characters except two adjacent -backquotes in an end-string context (according to the recognition -rules above). No markup interpretation (including backslash-escape -interpretation) is done within inline literals. - -Line breaks are *not* preserved in inline literals. Although a -reStructuredText parser will preserve runs of spaces in its output, -the final representation of the processed document is dependent on the -output formatter, thus the preservation of whitespace cannot be -guaranteed. If the preservation of line breaks and/or other -whitespace is important, `literal blocks`_ should be used. - -Inline literals are useful for short code snippets. For example:: - - The regular expression ``[+-]?(\d+(\.\d*)?|\.\d+)`` matches - floating-point numbers (without exponents). - - -Hyperlink References --------------------- - -Doctree element: reference. - -- Named hyperlink references: - - - Start-string = "" (empty string), end-string = "_". - - Start-string = "`", end-string = "\`_". (Phrase references.) - -- Anonymous hyperlink references: - - - Start-string = "" (empty string), end-string = "__". - - Start-string = "`", end-string = "\`__". (Phrase references.) - -Hyperlink references are indicated by a trailing underscore, "_", -except for `standalone hyperlinks`_ which are recognized -independently. The underscore can be thought of as a right-pointing -arrow. The trailing underscores point away from hyperlink references, -and the leading underscores point toward `hyperlink targets`_. - -Hyperlinks consist of two parts. In the text body, there is a source -link, a reference name with a trailing underscore (or two underscores -for `anonymous hyperlinks`_):: - - See the Python_ home page for info. - -A target link with a matching reference name must exist somewhere else -in the document. See `Hyperlink Targets`_ for a full description). - -`Anonymous hyperlinks`_ (which see) do not use reference names to -match references to targets, but otherwise behave similarly to named -hyperlinks. - - -Embedded URIs -````````````` - -A hyperlink reference may directly embed a target URI inline, within -angle brackets ("<...>") as follows:: - - See the `Python home page <http://www.python.org>`_ for info. - -This is exactly equivalent to:: - - See the `Python home page`_ for info. - - .. _Python home page: http://www.python.org - -The bracketed URI must be preceded by whitespace and be the last text -before the end string. With a single trailing underscore, the -reference is named and the same target URI may be referred to again. - -With two trailing underscores, the reference and target are both -anonymous, and the target cannot be referred to again. These are -"one-off" hyperlinks. For example:: - - `RFC 2396 <http://www.rfc-editor.org/rfc/rfc2396.txt>`__ and `RFC - 2732 <http://www.rfc-editor.org/rfc/rfc2732.txt>`__ together - define the syntax of URIs. - -Equivalent to:: - - `RFC 2396`__ and `RFC 2732`__ together define the syntax of URIs. - - __ http://www.rfc-editor.org/rfc/rfc2396.txt - __ http://www.rfc-editor.org/rfc/rfc2732.txt - -If reference text happens to end with angle-bracketed text that is -*not* a URI, the open-angle-bracket needs to be backslash-escaped. -For example, here is a reference to a title describing a tag:: - - See `HTML Element: \<a>`_ below. - -The reference text may also be omitted, in which case the URI will be -duplicated for use as the reference text. This is useful for relative -URIs where the address or file name is also the desired reference -text:: - - See `<a_named_relative_link>`_ or `<an_anonymous_relative_link>`__ - for details. - -.. CAUTION:: - - This construct offers easy authoring and maintenance of hyperlinks - at the expense of general readability. Inline URIs, especially - long ones, inevitably interrupt the natural flow of text. For - documents meant to be read in source form, the use of independent - block-level `hyperlink targets`_ is **strongly recommended**. The - embedded URI construct is most suited to documents intended *only* - to be read in processed form. - - -Inline Internal Targets ------------------------- - -Doctree element: target. - -Start-string = "_`", end-string = "`". - -Inline internal targets are the equivalent of explicit `internal -hyperlink targets`_, but may appear within running text. The syntax -begins with an underscore and a backquote, is followed by a hyperlink -name or phrase, and ends with a backquote. Inline internal targets -may not be anonymous. - -For example, the following paragraph contains a hyperlink target named -"Norwegian Blue":: - - Oh yes, the _`Norwegian Blue`. What's, um, what's wrong with it? - -See `Implicit Hyperlink Targets`_ for the resolution of duplicate -reference names. - - -Footnote References -------------------- - -Doctree element: footnote_reference. - -Start-string = "[", end-string = "]_". - -Each footnote reference consists of a square-bracketed label followed -by a trailing underscore. Footnote labels are one of: - -- one or more digits (i.e., a number), - -- a single "#" (denoting `auto-numbered footnotes`_), - -- a "#" followed by a simple reference name (an `autonumber label`_), - or - -- a single "*" (denoting `auto-symbol footnotes`_). - -For example:: - - Please RTFM [1]_. - - .. [1] Read The Fine Manual - - -Citation References -------------------- - -Doctree element: citation_reference. - -Start-string = "[", end-string = "]_". - -Each citation reference consists of a square-bracketed label followed -by a trailing underscore. Citation labels are simple `reference -names`_ (case-insensitive single words, consisting of alphanumerics -plus internal hyphens, underscores, and periods; no whitespace). - -For example:: - - Here is a citation reference: [CIT2002]_. - -See Citations_ for the citation itself. - - -Substitution References ------------------------ - -Doctree element: substitution_reference, reference. - -Start-string = "|", end-string = "|" (optionally followed by "_" or -"__"). - -Vertical bars are used to bracket the substitution reference text. A -substitution reference may also be a hyperlink reference by appending -a "_" (named) or "__" (anonymous) suffix; the substitution text is -used for the reference text in the named case. - -The processing system replaces substitution references with the -processed contents of the corresponding `substitution definitions`_ -(which see for the definition of "correspond"). Substitution -definitions produce inline-compatible elements. - -Examples:: - - This is a simple |substitution reference|. It will be replaced by - the processing system. - - This is a combination |substitution and hyperlink reference|_. In - addition to being replaced, the replacement text or element will - refer to the "substitution and hyperlink reference" target. - - -Standalone Hyperlinks ---------------------- - -Doctree element: reference. - -Start-string = end-string = "" (empty string). - -A URI (absolute URI [#URI]_ or standalone email address) within a text -block is treated as a general external hyperlink with the URI itself -as the link's text. For example:: - - See http://www.python.org for info. - -would be marked up in HTML as:: - - See <a href="http://www.python.org">http://www.python.org</a> for - info. - -Two forms of URI are recognized: - -1. Absolute URIs. These consist of a scheme, a colon (":"), and a - scheme-specific part whose interpretation depends on the scheme. - - The scheme is the name of the protocol, such as "http", "ftp", - "mailto", or "telnet". The scheme consists of an initial letter, - followed by letters, numbers, and/or "+", "-", ".". Recognition is - limited to known schemes, per the `Official IANA Registry of URI - Schemes`_ and the W3C's `Retired Index of WWW Addressing Schemes`_. - - The scheme-specific part of the resource identifier may be either - hierarchical or opaque: - - - Hierarchical identifiers begin with one or two slashes and may - use slashes to separate hierarchical components of the path. - Examples are web pages and FTP sites:: - - http://www.python.org - - ftp://ftp.python.org/pub/python - - - Opaque identifiers do not begin with slashes. Examples are - email addresses and newsgroups:: - - mailto:someone@somewhere.com - - news:comp.lang.python - - With queries, fragments, and %-escape sequences, URIs can become - quite complicated. A reStructuredText parser must be able to - recognize any absolute URI, as defined in RFC2396_ and RFC2732_. - -2. Standalone email addresses, which are treated as if they were - absolute URIs with a "mailto:" scheme. Example:: - - someone@somewhere.com - -Punctuation at the end of a URI is not considered part of the URI, -unless the URI is terminated by a closing angle bracket (">"). -Backslashes may be used in URIs to escape markup characters, -specifically asterisks ("*") and underscores ("_") which are vaid URI -characters (see `Escaping Mechanism`_ above). - -.. [#URI] Uniform Resource Identifier. URIs are a general form of - URLs (Uniform Resource Locators). For the syntax of URIs see - RFC2396_ and RFC2732_. - - -Units -===== - -(New in Docutils 0.3.10.) - -All measures consist of a positive floating point number in standard -(non-scientific) notation and a unit, possibly separated by one or -more spaces. - -Units are only supported where explicitly mentioned in the reference -manuals. - - -Length Units ------------- - -The following length units are supported by the reStructuredText -parser: - -* em (ems, the height of the element's font) -* ex (x-height, the height of the letter "x") -* px (pixels, relative to the canvas resolution) -* in (inches; 1in=2.54cm) -* cm (centimeters; 1cm=10mm) -* mm (millimeters) -* pt (points; 1pt=1/72in) -* pc (picas; 1pc=12pt) - -(List and explanations taken from -http://www.htmlhelp.com/reference/css/units.html#length.) - -The following are all valid length values: "1.5em", "20 mm", ".5in". - - -Percentage Units ----------------- - -Percentage values have a percent sign ("%") as unit. Percentage -values are relative to other values, depending on the context in which -they occur. - - ----------------- - Error Handling ----------------- - -Doctree element: system_message, problematic. - -Markup errors are handled according to the specification in `PEP -258`_. - - -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _Docutils: http://docutils.sourceforge.net/ -.. _The Docutils Document Tree: ../doctree.html -.. _Docutils Generic DTD: ../docutils.dtd -.. _transforms: - http://docutils.sourceforge.net/docutils/transforms/ -.. _Grouch: http://www.mems-exchange.org/software/grouch/ -.. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt -.. _DocTitle transform: -.. _DocInfo transform: - http://docutils.sourceforge.net/docutils/transforms/frontmatter.py -.. _getopt.py: - http://www.python.org/doc/current/lib/module-getopt.html -.. _GNU libc getopt_long(): - http://www.gnu.org/software/libc/manual/html_node/Getopt-Long-Options.html -.. _doctest module: - http://www.python.org/doc/current/lib/module-doctest.html -.. _Emacs table mode: http://table.sourceforge.net/ -.. _Official IANA Registry of URI Schemes: - http://www.iana.org/assignments/uri-schemes -.. _Retired Index of WWW Addressing Schemes: - http://www.w3.org/Addressing/schemes.html -.. _World Wide Web Consortium: http://www.w3.org/ -.. _HTML Techniques for Web Content Accessibility Guidelines: - http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text -.. _image: directives.html#image -.. _replace: directives.html#replace -.. _meta: directives.html#meta -.. _figure: directives.html#figure -.. _admonition: directives.html#admonitions -.. _reStructuredText Directives: directives.html -.. _reStructuredText Interpreted Text Roles: roles.html -.. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt -.. _RFC2732: http://www.rfc-editor.org/rfc/rfc2732.txt -.. _Zope: http://www.zope.com/ -.. _PEP 258: ../../peps/pep-0258.html - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/rst/roles.txt b/docutils/docs/ref/rst/roles.txt deleted file mode 100644 index 3b8b114bc..000000000 --- a/docutils/docs/ref/rst/roles.txt +++ /dev/null @@ -1,318 +0,0 @@ -========================================= - reStructuredText Interpreted Text Roles -========================================= - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -This document describes the interpreted text roles implemented in the -reference reStructuredText parser. - -Interpreted text uses backquotes (`) around the text. An explicit -role marker may optionally appear before or after the text, delimited -with colons. For example:: - - This is `interpreted text` using the default role. - - This is :title:`interpreted text` using an explicit role. - -A default role may be defined by applications of reStructuredText; it -is used if no explicit ``:role:`` prefix or suffix is given. The -"default default role" is `:title-reference:`_. It can be changed -using the default-role_ directive. - -See the `Interpreted Text`_ section in the `reStructuredText Markup -Specification`_ for syntax details. For details on the hierarchy of -elements, please see `The Docutils Document Tree`_ and the `Docutils -Generic DTD`_ XML document type definition. For interpreted text role -implementation details, see `Creating reStructuredText Interpreted -Text Roles`_. - -.. _"role" directive: directives.html#role -.. _default-role: directives.html#default-role -.. _Interpreted Text: restructuredtext.html#interpreted-text -.. _reStructuredText Markup Specification: restructuredtext.html -.. _The Docutils Document Tree: ../doctree.html -.. _Docutils Generic DTD: ../docutils.dtd -.. _Creating reStructuredText Interpreted Text Roles: - ../../howto/rst-roles.html - - -.. contents:: - - ---------------- - Customization ---------------- - -Custom interpreted text roles may be defined in a document with the -`"role" directive`_. Customization details are listed with each role. - -.. _class: - -A ``class`` option is recognized by the "role" directive for most -interpreted text roles. A description__ is provided in the `"role" -directive`_ documentation. - -__ directives.html#role-class - - ----------------- - Standard Roles ----------------- - -``:emphasis:`` -============== - -:Aliases: None -:DTD Element: emphasis -:Customization: - :Options: class_. - :Content: None. - -Implements emphasis. These are equivalent:: - - *text* - :emphasis:`text` - - -``:literal:`` -============== - -:Aliases: None -:DTD Element: literal -:Customization: - :Options: class_. - :Content: None. - -Implements inline literal text. These are equivalent:: - - ``text`` - :literal:`text` - -Care must be taken with backslash-escapes though. These are *not* -equivalent:: - - ``text \ and \ backslashes`` - :literal:`text \ and \ backslashes` - -The backslashes in the first line are preserved (and do nothing), -whereas the backslashes in the second line escape the following -spaces. - - -``:pep-reference:`` -=================== - -:Aliases: ``:PEP:`` -:DTD Element: reference -:Customization: - :Options: class_. - :Content: None. - -The ``:pep-reference:`` role is used to create an HTTP reference to a -PEP (Python Enhancement Proposal). The ``:PEP:`` alias is usually -used. For example:: - - See :PEP:`287` for more information about reStructuredText. - -This is equivalent to:: - - See `PEP 287`__ for more information about reStructuredText. - - __ http://www.python.org/peps/pep-0287.html - - -``:rfc-reference:`` -=================== - -:Aliases: ``:RFC:`` -:DTD Element: reference -:Customization: - :Options: class_. - :Content: None. - -The ``:rfc-reference:`` role is used to create an HTTP reference to an -RFC (Internet Request for Comments). The ``:RFC:`` alias is usually -used. For example:: - - See :RFC:`2822` for information about email headers. - -This is equivalent to:: - - See `RFC 2822`__ for information about email headers. - - __ http://www.faqs.org/rfcs/rfc2822.html - - -``:strong:`` -============ - -:Aliases: None -:DTD Element: strong -:Customization: - :Options: class_. - :Content: None. - -Implements strong emphasis. These are equivalent:: - - **text** - :strong:`text` - - -``:subscript:`` -=============== - -:Aliases: ``:sub:`` -:DTD Element: subscript -:Customization: - :Options: class_. - :Content: None. - -Implements subscripts. - -.. Tip:: - - Whitespace or punctuation is required around interpreted text, but - often not desired with subscripts & superscripts. - Backslash-escaped whitespace can be used; the whitespace will be - removed from the processed document:: - - H\ :sub:`2`\ O - E = mc\ :sup:`2` - - In such cases, readability of the plain text can be greatly - improved with substitutions:: - - The chemical formula for pure water is |H2O|. - - .. |H2O| replace:: H\ :sub:`2`\ O - - See `the reStructuredText spec`__ for further information on - `character-level markup`__ and `the substitution mechanism`__. - - __ restructuredtext.html - __ restructuredtext.html#character-level-inline-markup - __ restructuredtext.html#substitution-references - - -``:superscript:`` -================= - -:Aliases: ``:sup:`` -:DTD Element: superscript -:Customization: - :Options: class_. - :Content: None. - -Implements superscripts. See the tip in `:subscript:`_ above. - - -``:title-reference:`` -===================== - -:Aliases: ``:title:``, ``:t:``. -:DTD Element: title_reference -:Customization: - :Options: class_. - :Content: None. - -The ``:title-reference:`` role is used to describe the titles of -books, periodicals, and other materials. It is the equivalent of the -HTML "cite" element, and it is expected that HTML writers will -typically render "title_reference" elements using "cite". - -Since title references are typically rendered with italics, they are -often marked up using ``*emphasis*``, which is misleading and vague. -The "title_reference" element provides accurate and unambiguous -descriptive markup. - -Let's assume ``:title-reference:`` is the default interpreted text -role (see below) for this example:: - - `Design Patterns` [GoF95]_ is an excellent read. - -The following document fragment (pseudo-XML_) will result from -processing:: - - <paragraph> - <title_reference> - Design Patterns - - <citation_reference refname="gof95"> - GoF95 - is an excellent read. - -``:title-reference:`` is the default interpreted text role in the -standard reStructuredText parser. This means that no explicit role is -required. Applications of reStructuredText may designate a different -default role, in which case the explicit ``:title-reference:`` role -must be used to obtain a ``title_reference`` element. - - -.. _pseudo-XML: ../doctree.html#pseudo-xml - - -------------------- - Specialized Roles -------------------- - -``raw`` -======= - -:Aliases: None -:DTD Element: raw -:Customization: - :Options: class_, format - :Content: None - -.. WARNING:: - - The "raw" role is a stop-gap measure allowing the author to bypass - reStructuredText's markup. It is a "power-user" feature that - should not be overused or abused. The use of "raw" ties documents - to specific output formats and makes them less portable. - - If you often need to use "raw"-derived interpreted text roles or - the "raw" directive, that is a sign either of overuse/abuse or that - functionality may be missing from reStructuredText. Please - describe your situation in a message to the Docutils-users_ mailing - list. - - .. _Docutils-users: ../../user/mailing-lists.html#docutils-user - -The "raw" role indicates non-reStructuredText data that is to be -passed untouched to the Writer. It is the inline equivalent of the -`"raw" directive`_; see its documentation for details on the -semantics. - -.. _"raw" directive: directives.html#raw - -The "raw" role cannot be used directly. The `"role" directive`_ must -first be used to build custom roles based on the "raw" role. One or -more formats (Writer names) must be provided in a "format" option. - -For example, the following creates an HTML-specific "raw-html" role:: - - .. role:: raw-html(raw) - :format: html - -This role can now be used directly to pass data untouched to the HTML -Writer. For example:: - - If there just *has* to be a line break here, - :raw-html:`<br />` - it can be accomplished with a "raw"-derived role. - But the line block syntax should be considered first. - -.. Tip:: Roles based on "raw" should clearly indicate their origin, so - they are not mistaken for reStructuredText markup. Using a "raw-" - prefix for role names is recommended. - -In addition to "class_", the following option is recognized: - -``format`` : text - One or more space-separated output format names (Writer names). |