diff options
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/doctree.txt | 4970 | ||||
| -rw-r--r-- | docs/ref/docutils.dtd | 606 | ||||
| -rw-r--r-- | docs/ref/rst/definitions.txt | 180 | ||||
| -rw-r--r-- | docs/ref/rst/directives.txt | 1727 | ||||
| -rw-r--r-- | docs/ref/rst/introduction.txt | 314 | ||||
| -rw-r--r-- | docs/ref/rst/restructuredtext.txt | 2879 | ||||
| -rw-r--r-- | docs/ref/rst/roles.txt | 318 | ||||
| -rw-r--r-- | docs/ref/soextblx.dtd | 312 | ||||
| -rw-r--r-- | docs/ref/transforms.txt | 116 |
9 files changed, 11422 insertions, 0 deletions
diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt new file mode 100644 index 000000000..25e5f9594 --- /dev/null +++ b/docs/ref/doctree.txt @@ -0,0 +1,4970 @@ +============================ + The Docutils Document Tree +============================ + +A Guide to the Docutils DTD +*************************** + +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ +:Copyright: This document has been placed in the public domain. + + +.. contents:: :depth: 1 + + +This document describes the XML data structure of Docutils_ documents: +the relationships and semantics of elements and attributes. The +Docutils document structure is formally defined by the `Docutils +Generic DTD`_ XML document type definition, docutils.dtd_, which is +the definitive source for details of element structural relationships. + +This document does not discuss implementation details. Those can be +found in internal documentation (docstrings) for the +``docutils.nodes`` module, where the document tree data structure is +implemented in a class library. + +The reader is assumed to have some familiarity with XML or SGML, and +an understanding of the data structure meaning of "tree". For a list +of introductory articles, see `Introducing the Extensible Markup +Language (XML)`_. + +The reStructuredText_ markup is used for illustrative examples +throughout this document. For a gentle introduction, see `A +ReStructuredText Primer`_. For complete technical details, see the +`reStructuredText Markup Specification`_. + + +.. _Docutils: http://docutils.sourceforge.net/ +.. _Docutils Generic DTD: +.. _Docutils DTD: +.. _docutils.dtd: docutils.dtd +.. _Introducing the Extensible Markup Language (XML): + http://xml.coverpages.org/xmlIntro.html +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _A ReStructuredText Primer: ../user/rst/quickstart.html +.. _reStructuredText Markup Specification: rst/restructuredtext.html + + +------------------- + Element Hierarchy +------------------- + +.. contents:: :local: + +Below is a simplified diagram of the hierarchy of elements in the +Docutils document tree structure. An element may contain any other +elements immediately below it in the diagram. Notes are written in +square brackets. Element types in parentheses indicate recursive or +one-to-many relationships; sections may contain (sub)sections, tables +contain further body elements, etc. :: + + +--------------------------------------------------------------------+ + | document [may begin with a title, subtitle, decoration, docinfo] | + | +--------------------------------------+ + | | sections [each begins with a title] | + +-----------------------------+-------------------------+------------+ + | [body elements:] | (sections) | + | | - literal | - lists | | - hyperlink +------------+ + | | blocks | - tables | | targets | + | para- | - doctest | - block | foot- | - sub. defs | + | graphs | blocks | quotes | notes | - comments | + +---------+-----------+----------+-------+--------------+ + | [text]+ | [text] | (body elements) | [text] | + | (inline +-----------+------------------+--------------+ + | markup) | + +---------+ + +The Docutils document model uses a simple, recursive model for section +structure. A document_ node may contain body elements and section_ +elements. Sections in turn may contain body elements and sections. +The level (depth) of a section element is determined from its physical +nesting level; unlike other document models (``<h1>`` in HTML_, +``<sect1>`` in DocBook_, ``<div1>`` in XMLSpec_) the level is not +incorporated into the element name. + +The Docutils document model uses strict element content models. Every +element has a unique structure and semantics, but elements may be +classified into general categories (below). Only elements which are +meant to directly contain text data have a mixed content model, where +text data and inline elements may be intermixed. This is unlike the +much looser HTML_ document model, where paragraphs and text data may +occur at the same level. + + +Structural Elements +=================== + +Structural elements may only contain child elements; they do not +directly contain text data. Structural elements may contain body +elements or further structural elements. Structural elements can only +be child elements of other structural elements. + +Category members: document_, section_, topic_, sidebar_ + + +Structural Subelements +---------------------- + +Structural subelements are child elements of structural elements. +Simple structuctural subelements (title_, subtitle_) contain text +data; the others are compound and do not directly contain text data. + +Category members: title_, subtitle_, decoration_, docinfo_, +transition_ + + +Bibliographic Elements +`````````````````````` + +The docinfo_ element is an optional child of document_. It groups +bibliographic elements together. All bibliographic elements except +authors_ and field_ contain text data. authors_ contains further +bibliographic elements (most notably author_). field_ contains +field_name_ and field_body_ body subelements. + +Category members: address_, author_, authors_, contact_, copyright_, +date_, field_, organization_, revision_, status_, version_ + + +Decorative Elements +``````````````````` + +The decoration_ element is also an optional child of document_. It +groups together elements used to generate page headers and footers. + +Category members: footer_, header_ + + +Body Elements +============= + +Body elements are contained within structural elements and compound +body elements. There are two subcategories of body elements: simple +and compound. + +Category members: admonition_, attention_, block_quote_, bullet_list_, +caution_, citation_, comment_, compound_, container_, danger_, +definition_list_, doctest_block_, enumerated_list_, error_, +field_list_, figure_, footnote_, hint_, image_, important_, +line_block_, literal_block_, note_, option_list_, paragraph_, +pending_, raw_, rubric_, substitution_definition_, system_message_, +table_, target_, tip_, warning_ + + +Simple Body Elements +-------------------- + +Simple body elements are empty or directly contain text data. Those +that contain text data may also contain inline elements. Such +elements therefore have a "mixed content model". + +Category members: comment_, doctest_block_, image_, literal_block_, +paragraph_, pending_, raw_, rubric_, substitution_definition_, target_ + + +Compound Body Elements +---------------------- + +Compound body elements contain local substructure (body subelements) +and further body elements. They do not directly contain text data. + +Category members: admonition_, attention_, block_quote_, bullet_list_, +caution_, citation_, compound_, container_, danger_, definition_list_, +enumerated_list_, error_, field_list_, figure_, footnote_, hint_, +important_, line_block, note_, option_list_, system_message_, table_, +tip_, warning_ + + +Body Subelements +```````````````` + +Compound body elements contain specific subelements (e.g. bullet_list_ +contains list_item_). Subelements may themselves be compound elements +(containing further child elements, like field_) or simple data +elements (containing text data, like field_name_). These subelements +always occur within specific parent elements, never at the body +element level (beside paragraphs, etc.). + +Category members (simple): attribution_, caption_, classifier_, +colspec_, field_name_, label_, line_, option_argument_, +option_string_, term_ + +Category members (compound): definition_, definition_list_item_, +description_, entry_, field_, field_body_, legend_, list_item_, +option_, option_group_, option_list_item_, row_, tbody_, tgroup_, +thead_ + + +Inline Elements +=============== + +Inline elements directly contain text data, and may also contain +further inline elements. Inline elements are contained within simple +body elements. Most inline elements have a "mixed content model". + +Category members: abbreviation_, acronym_, citation_reference_, +emphasis_, footnote_reference_, generated_, image_, inline_, literal_, +problematic_, reference_, strong_, subscript_, +substitution_reference_, superscript_, target_, title_reference_, raw_ + + +.. _HTML: http://www.w3.org/MarkUp/ +.. _DocBook: http://docbook.org/tdg/en/html/docbook.html +.. _XMLSpec: http://www.w3.org/XML/1998/06/xmlspec-report.htm + + +------------------- + Element Reference +------------------- + +.. contents:: :local: + :depth: 1 + +Each element in the DTD (document type definition) is described in its +own section below. Each section contains an introduction plus the +following subsections: + +* Details (of element relationships and semantics): + + - Category: One or more references to the element categories in + `Element Hierarchy`_ above. Some elements belong to more than one + category. + + - Parents: A list of elements which may contain the element. + + - Children: A list of elements which may occur within the element. + + - Analogues: Describes analogous elements in well-known document + models such as HTML_ or DocBook_. Lists similarities and + differences. + + - Processing: Lists formatting or rendering recommendations for the + element. + +* Content Model: + + The formal XML content model from the `Docutils DTD`_, followed by: + + - Attributes: Describes (or refers to descriptions of) the possible + values and semantics of each attribute. + + - Parameter Entities: Lists the parameter entities which directly or + indirectly include the element. + +* Examples: reStructuredText_ examples are shown along with + fragments of the document trees resulting from parsing. + _`Pseudo-XML` is used for the results of parsing and processing. + Pseudo-XML is a representation of XML where nesting is indicated by + indentation and end-tags are not shown. Some of the precision of + real XML is given up in exchange for easier readability. For + example, the following are equivalent: + + - Real XML:: + + <document> + <section ids="a-title" names="a title"> + <title>A Title</title> + <paragraph>A paragraph.</paragraph> + </section> + </document> + + - Pseudo-XML:: + + <document> + <section ids="a-title" names="a title"> + <title> + A Title + <paragraph> + A paragraph. + +-------------------- + +Many of the element reference sections below are marked "_`to be +completed`". Please help complete this document by contributing to +its writing. + + +``abbreviation`` +================ + +`To be completed`_. + + +``acronym`` +=========== + +`To be completed`_. + + +``address`` +=========== + +The ``address`` element holds the surface mailing address information +for the author (individual or group) of the document, or a third-party +contact address. Its structure is identical to that of the +literal_block_ element: whitespace is significant, especially +newlines. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + The following elements may contain ``address``: docinfo_, authors_ + +:Children: + ``address`` elements contain text data plus `inline elements`_. + +:Analogues: + ``address`` is analogous to the DocBook "address" element. + +:Processing: + As with the literal_block_ element, newlines and other whitespace + is significant and must be preserved. However, a monospaced + typeface need not be used. + + See also docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``address`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus `xml:space`_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``address``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Address: 123 Example Ave. + Example, EX + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <address> + 123 Example Ave. + Example, EX + +See docinfo_ for a more complete example, including processing +context. + + +``admonition`` +============== + +This element is a generic, titled admonition. Also see the specific +admonition elements Docutils offers (in alphabetical order): caution_, +danger_, error_, hint_, important_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``admonition``. + +:Children: + ``admonition`` elements begin with a title_ and may contain one or + more `body elements`_. + +:Analogues: + ``admonition`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.). + + +Content Model +------------- + +.. parsed-literal:: + + (title_, (`%body.elements;`_)+) + +:Attributes: + The ``admonition`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``admonition``. The `%structure.model;`_ parameter entity + indirectly includes ``admonition``. + + +Examples +-------- + +reStructuredText source:: + + .. admonition:: And, by the way... + + You can make up your own admonition too. + +Pseudo-XML_ fragment from simple parsing:: + + <admonition class="admonition-and-by-the-way"> + <title> + And, by the way... + <paragraph> + You can make up your own admonition too. + + +``attention`` +============= + +The ``attention`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): caution_, danger_, error_, +hint_, important_, note_, tip_, warning_, and the generic admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``attention``. + +:Children: + ``attention`` elements contain one or more `body elements`_. + +:Analogues: + ``attention`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Attention!" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``attention`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``attention``. The `%structure.model;`_ parameter entity + indirectly includes ``attention``. + + +Examples +-------- + +reStructuredText source:: + + .. Attention:: All your base are belong to us. + +Pseudo-XML_ fragment from simple parsing:: + + <attention> + <paragraph> + All your base are belong to us. + + +``attribution`` +=============== + +`To be completed`_. + + +``author`` +========== + +The ``author`` element holds the name of the author of the document. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + The following elements may contain ``author``: docinfo_, authors_ + +:Children: + ``author`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``author`` is analogous to the DocBook "author" element. + +:Processing: + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``author`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``author``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Author: J. Random Hacker + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <author> + J. Random Hacker + +See docinfo_ for a more complete example, including processing +context. + + +``authors`` +=========== + +The ``authors`` element is a container for author information for +documents with multiple authors. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + Only the docinfo_ element contains ``authors``. + +:Children: + ``authors`` elements may contain the following elements: author_, + organization_, address_, contact_ + +:Analogues: + ``authors`` is analogous to the DocBook "authors" element. + +:Processing: + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + ((author_, organization_?, address_?, contact_?)+) + +:Attributes: + The ``authors`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``authors``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Authors: J. Random Hacker; Jane Doe + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <authors> + <author> + J. Random Hacker + <author> + Jane Doe + +In reStructuredText, multiple author's names are separated with +semicolons (";") or commas (","); semicolons take precedence. There +is currently no way to represent the author's organization, address, +or contact in a reStructuredText "Authors" field. + +See docinfo_ for a more complete example, including processing +context. + + +``block_quote`` +=============== + +The ``block_quote`` element is used for quotations set off from the +main text (standalone). + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``block_quote``. + +:Children: + ``block_quote`` elements contain `body elements`_ followed by an + optional attribution_ element. + +:Analogues: + ``block_quote`` is analogous to the "blockquote" element in both + HTML and DocBook. + +:Processing: + ``block_quote`` elements serve to set their contents off from the + main text, typically with indentation and/or other decoration. + + +Content Model +------------- + +.. parsed-literal:: + + ((`%body.elements;`_)+, attribution_?) + +:Attributes: + The ``block_quote`` element contains only the `common + attributes`_: ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``block_quote``. The `%structure.model;`_ parameter entity + indirectly includes ``block_quote``. + + +Examples +-------- + +reStructuredText source:: + + As a great paleontologist once said, + + This theory, that is mine, is mine. + + -- Anne Elk (Miss) + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + As a great paleontologist once said, + <block_quote> + <paragraph> + This theory, that is mine, is mine. + <attribution> + Anne Elk (Miss) + + +``bullet_list`` +=============== + +The ``bullet_list`` element contains list_item_ elements which are +uniformly marked with bullets. Bullets are typically simple dingbats +(symbols) such as circles and squares. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``bullet_list``. + +:Children: + ``bullet_list`` elements contain one or more list_item_ elements. + +:Analogues: + ``bullet_list`` is analogous to the HTML "ul" element and to the + DocBook "itemizedlist" element. HTML's "ul" is short for + "unordered list", which we consider to be a misnomer. "Unordered" + implies that the list items may be randomly rearranged without + affecting the meaning of the list. Bullet lists *are* often + ordered; the ordering is simply left implicit. + +:Processing: + Each list item should begin a new vertical block, prefaced by a + bullet/dingbat. + + +Content Model +------------- + +.. parsed-literal:: + + (list_item_ +) + +:Attributes: + The ``bullet_list`` element contains the `common attributes`_ + (ids_, names_, dupnames_, source_, and classes_), plus bullet_. + + ``bullet`` is used to record the style of bullet from the input + data. In documents processed from reStructuredText_, it contains + one of "-", "+", or "*". It may be ignored in processing. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``bullet_list``. The `%structure.model;`_ parameter entity + indirectly includes ``bullet_list``. + + +Examples +-------- + +reStructuredText_ source:: + + - Item 1, paragraph 1. + + Item 1, paragraph 2. + + - Item 2. + +Pseudo-XML_ fragment from simple parsing:: + + <bullet_list bullet="-"> + <list_item> + <paragraph> + Item 1, paragraph 1. + <paragraph> + Item 1, paragraph 2. + <list_item> + <paragraph> + Item 2. + +See list_item_ for another example. + + +``caption`` +=========== + +`To be completed`_. + + +``caution`` +=========== + +The ``caution`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, danger_, error_, +hint_, important_, note_, tip_, warning_, and the generic admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``caution``. + +:Children: + ``caution`` elements contain one or more `body elements`_. + +:Analogues: + ``caution`` is analogous to the DocBook "caution" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Caution" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``caution`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``caution``. The `%structure.model;`_ parameter entity + indirectly includes ``caution``. + + +Examples +-------- + +reStructuredText source:: + + .. Caution:: Don't take any wooden nickels. + +Pseudo-XML_ fragment from simple parsing:: + + <caution> + <paragraph> + Don't take any wooden nickels. + + +``citation`` +============ + +`To be completed`_. + + +``citation_reference`` +====================== + +`To be completed`_. + + +``classifier`` +============== + +The ``classifier`` element contains the classification or type of the +term_ being defined in a definition_list_. For example, it can be +used to indicate the type of a variable. + + +Details +------- + +:Category: + `Body Subelements`_ (simple) + +:Parents: + Only the definition_list_item_ element contains ``classifier``. + +:Children: + ``classifier`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``classifier`` has no direct analogues in common DTDs. It can be + emulated with primitives or type effects. + +:Processing: + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``classifier`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +Here is a hypothetical data dictionary. reStructuredText_ source:: + + name : string + Customer name. + i : int + Temporary index variable. + +Pseudo-XML_ fragment from simple parsing:: + + <definition_list> + <definition_list_item> + <term> + name + <classifier> + string + <definition> + <paragraph> + Customer name. + <definition_list_item> + <term> + i + <classifier> + int + <definition> + <paragraph> + Temporary index variable. + + +``colspec`` +=========== + +`To be completed`_. + + +``comment`` +=========== + +`To be completed`_. + + +``compound`` +============ + +`To be completed`_. + + +``contact`` +=========== + +The ``contact`` element holds contact information for the author +(individual or group) of the document, or a third-party contact. It +is typically used for an email or web address. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + The following elements may contain ``contact``: docinfo_, authors_ + +:Children: + ``contact`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``contact`` is analogous to the DocBook "email" element. The HTML + "address" element serves a similar purpose. + +:Processing: + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``contact`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``contact``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Contact: jrh@example.com + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <contact> + <reference refuri="mailto:jrh@example.com"> + jrh@example.com + +See docinfo_ for a more complete example, including processing +context. + + +``container`` +============= + +`To be completed`_. + + +``copyright`` +============= + +The ``copyright`` element contains the document's copyright statement. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + Only the docinfo_ element contains ``copyright``. + +:Children: + ``copyright`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``copyright`` is analogous to the DocBook "copyright" element. + +:Processing: + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``copyright`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``copyright``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Copyright: This document has been placed in the public domain. + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <copyright> + This document has been placed in the public domain. + +See docinfo_ for a more complete example, including processing +context. + + +``danger`` +========== + +The ``danger`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, error_, +hint_, important_, note_, tip_, warning_, and the generic admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``danger``. + +:Children: + ``danger`` elements contain one or more `body elements`_. + +:Analogues: + ``danger`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "!DANGER!" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``danger`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``danger``. The `%structure.model;`_ parameter entity + indirectly includes ``danger``. + + +Examples +-------- + +reStructuredText source:: + + .. DANGER:: Mad scientist at work! + +Pseudo-XML_ fragment from simple parsing:: + + <danger> + <paragraph> + Mad scientist at work! + + +``date`` +======== + +The ``date`` element contains the date of publication, release, or +last modification of the document. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + Only the docinfo_ element contains ``date``. + +:Children: + ``date`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``date`` is analogous to the DocBook "date" element. + +:Processing: + Often used with the RCS/CVS keyword "Date". See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``date`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``date``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Date: 2002-08-20 + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <date> + 2002-08-20 + +See docinfo_ for a more complete example, including processing +context. + + +``decoration`` +============== + +The ``decoration`` element is a container for header_ and footer_ +elements and potential future extensions. These elements are used for +notes, time/datestamp, processing information, etc. + + +Details +------- + +:Category: + `Structural Subelements`_ + +:Parents: + Only the document_ element contains ``decoration``. + +:Children: + ``decoration`` elements may contain `decorative elements`_. + +:Analogues: + There are no direct analogies to ``decoration`` in HTML or in + DocBook. Equivalents are typically constructed from primitives + and/or generated by the processing system. + +:Processing: + See the individual `decorative elements`_. + + +Content Model +------------- + +.. parsed-literal:: + + (header_?, footer_?) + +Although the content model doesn't specifically require contents, no +empty ``decoration`` elements are ever created. + +:Attributes: + The ``decoration`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +reStructuredText_ source:: + + A paragraph. + +Complete pseudo-XML_ result after parsing and applying transforms, +assuming that the datestamp command-line option or configuration +setting has been supplied:: + + <document> + <decoration> + <footer> + <paragraph> + Generated on: 2002-08-20. + <paragraph> + A paragraph. + + +``definition`` +============== + +The ``definition`` element is a container for the body elements used +to define a term_ in a definition_list_. + + +Details +------- + +:Category: + `Body Subelements`_ (compound) + +:Parents: + Only definition_list_item_ elements contain ``definition``. + +:Children: + ``definition`` elements may contain `body elements`_. + +:Analogues: + ``definition`` is analogous to the HTML "dd" element and to the + DocBook "listitem" element (inside a "variablelistentry" element). + +:Processing: + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``definition`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the definition_list_, definition_list_item_, and +classifier_ elements. + + +``definition_list`` +=================== + +The ``definition_list`` element contains a list of terms and their +definitions. It can be used for glossaries or dictionaries, to +describe or classify things, for dialogues, or to itemize subtopics +(such as in this reference). + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``definition_list``. + +:Children: + ``definition_list`` elements contain one or more + definition_list_item_ elements. + +:Analogues: + ``definition_list`` is analogous to the HTML "dl" element and to + the DocBook "variablelist" element. + +:Processing: + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + (definition_list_item_ +) + +:Attributes: + The ``definition_list`` element contains only the `common + attributes`_: ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``definition_list``. The `%structure.model;`_ parameter entity + indirectly includes ``definition_list``. + + +Examples +-------- + +reStructuredText_ source:: + + Term + Definition. + + Term : classifier + The ' : ' indicates a classifier in + definition list item terms only. + +Pseudo-XML_ fragment from simple parsing:: + + <definition_list> + <definition_list_item> + <term> + Term + <definition> + <paragraph> + Definition. + <definition_list_item> + <term> + Term + <classifier> + classifier + <definition> + <paragraph> + The ' : ' indicates a classifier in + definition list item terms only. + +See definition_list_item_ and classifier_ for further examples. + + +``definition_list_item`` +======================== + +The ``definition_list_item`` element contains a single +term_/definition_ pair (with optional classifier_). + + +Details +------- + +:Category: + `Body Subelements`_ (compound) + +:Parents: + Only the definition_list_ element contains + ``definition_list_item``. + +:Children: + ``definition_list_item`` elements each contain a single term_, + an optional classifier_, and a definition_. + +:Analogues: + ``definition_list_item`` is analogous to the DocBook + "variablelistentry" element. + +:Processing: + The optional classifier_ can be rendered differently from the + term_. They should be separated visually, typically by spaces + plus a colon or dash. + + +Content Model +------------- + +.. parsed-literal:: + + (term_, classifier_?, definition_) + +:Attributes: + The ``definition_list_item`` element contains only the `common + attributes`_: ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +reStructuredText_ source:: + + Tyrannosaurus Rex : carnivore + Big and scary; the "Tyrant King". + + Brontosaurus : herbivore + All brontosauruses are thin at one end, + much much thicker in the middle + and then thin again at the far end. + + -- Anne Elk (Miss) + +Pseudo-XML_ fragment from simple parsing:: + + <definition_list> + <definition_list_item> + <term> + Tyrannosaurus Rex + <classifier> + carnivore + <definition> + <paragraph> + Big and scary; the "Tyrant King". + <definition_list_item> + <term> + Brontosaurus + <classifier> + herbivore + <definition> + <paragraph> + All brontosauruses are thin at one end, + much much thicker in the middle + and then thin again at the far end. + <paragraph> + -- Anne Elk (Miss) + +See definition_list_ and classifier_ for further examples. + + +``description`` +=============== + +The ``description`` element contains body elements, describing the +purpose or effect of a command-line option or group of options. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_list_item_ element contains ``description``. + +:Children: + ``description`` elements may contain `body elements`_. + +:Analogues: + ``description`` has no direct analogues in common DTDs. + +:Processing: + See option_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``description`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the option_list_ element. + + +``docinfo`` +=========== + +The ``docinfo`` element is a container for document bibliographic +data, or meta-data (data about the document). It corresponds to the +front matter of a book, such as the title page and copyright page. + + +Details +------- + +:Category: + `Structural Subelements`_ + +:Parents: + Only the document_ element contains ``docinfo``. + +:Children: + ``docinfo`` elements contain `bibliographic elements`_. + +:Analogues: + ``docinfo`` is analogous to DocBook "info" elements ("bookinfo" + etc.). There are no directly analogous HTML elements; the "meta" + element carries some of the same information, albeit invisibly. + +:Processing: + The ``docinfo`` element may be rendered as a two-column table or + in other styles. It may even be invisible or omitted from the + processed output. Meta-data may be extracted from ``docinfo`` + children; for example, HTML ``<meta>`` tags may be constructed. + + When Docutils_ transforms a reStructuredText_ field_list_ into a + ``docinfo`` element (see the examples below), RCS/CVS keywords are + normally stripped from simple (one paragraph) field bodies. For + complete details, please see `RCS Keywords`_ in the + `reStructuredText Markup Specification`_. + + .. _RCS Keywords: rst/restructuredtext.html#rcs-keywords + + +Content Model +------------- + +.. parsed-literal:: + + (`%bibliographic.elements;`_)+ + +:Attributes: + The ``docinfo`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +Docinfo is represented in reStructuredText_ by a field_list_ in a +bibliographic context: the first non-comment element of a document_, +after any document title_/subtitle_. The field list is transformed +into a ``docinfo`` element and its children by a transform. Source:: + + Docinfo Example + =============== + + :Author: J. Random Hacker + :Contact: jrh@example.com + :Date: 2002-08-18 + :Status: Work In Progress + :Version: 1 + :Filename: $RCSfile$ + :Copyright: This document has been placed in the public domain. + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="docinfo-example" names="docinfo example"> + <title> + Docinfo Example + <docinfo> + <author> + J. Random Hacker + <contact> + <reference refuri="mailto:jrh@example.com"> + jrh@example.com + <date> + 2002-08-18 + <status> + Work In Progress + <version> + 1 + <field> + <field_name> + Filename + <field_body> + <paragraph> + doctree.txt + <copyright> + This document has been placed in the public domain. + +Note that "Filename" is a non-standard ``docinfo`` field, so becomes a +generic ``field`` element. Also note that the "RCSfile" keyword +syntax has been stripped from the "Filename" data. + +See field_list_ for an example in a non-bibliographic context. Also +see the individual examples for the various `bibliographic elements`_. + + +``doctest_block`` +================= + +The ``doctest_block`` element is a Python-specific variant of +literal_block_. It is a block of text where line breaks and +whitespace are significant and must be preserved. ``doctest_block`` +elements are used for interactive Python interpreter sessions, which +are distinguished by their input prompt: ``>>>``. 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 module: + http://www.python.org/doc/current/lib/module-doctest.html + + +Details +------- + +:Category: + `Simple Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``doctest_block``. + +:Children: + ``doctest_block`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``doctest_block`` is analogous to the HTML "pre" element and to + the DocBook "programlisting" and "screen" elements. + +:Processing: + As with literal_block_, ``doctest_block`` elements are typically + rendered in a monospaced typeface. It is crucial that all + whitespace and line breaks are preserved in the rendered form. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``doctest_block`` element contains the `common attributes`_ + (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``doctest_block``. The `%structure.model;`_ parameter entity + indirectly includes ``doctest_block``. + + +Examples +-------- + +reStructuredText source:: + + This is an ordinary paragraph. + + >>> print 'this is a Doctest block' + this is a Doctest block + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + This is an ordinary paragraph. + <doctest_block xml:space="preserve"> + >>> print 'this is a Doctest block' + this is a Doctest block + + +``document`` +============ + +The ``document`` element is the root (topmost) element of the Docutils +document tree. ``document`` is the direct or indirect ancestor of +every other element in the tree. It encloses the entire document +tree. It is the starting point for a document. + + +Details +------- + +:Category: + `Structural Elements`_ + +:Parents: + The ``document`` element has no parents. + +:Children: + ``document`` elements may contain `structural subelements`_, + `structural elements`_, and `body elements`_. + +:Analogues: + ``document`` is analogous to the HTML "html" element and to + several DocBook elements such as "book". + + +Content Model +------------- + +.. parsed-literal:: + + ( (title_, subtitle_?)?, + decoration_?, + (docinfo_, transition_?)?, + `%structure.model;`_ ) + +Depending on the source of the data and the stage of processing, the +"document" may not initially contain a "title". A document title is +not directly representable in reStructuredText_. Instead, a lone +top-level section may have its title promoted to become the document +title_, and similarly for a lone second-level (sub)section's title to +become the document subtitle_. + +The contents of "decoration_" may be specified in a document, +constructed programmatically, or both. The "docinfo_" may be +transformed from an initial field_list_. + +See the `%structure.model;`_ parameter entity for details of the body +of a ``document``. + +:Attributes: + The ``document`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus an optional title__ + attribute which stores the document title metadata. + + __ `title (attribute)`_ + + +Examples +-------- + +reStructuredText_ source:: + + A Title + ======= + + A paragraph. + +Complete pseudo-XML_ result from simple parsing:: + + <document> + <section ids="a-title" names="a title"> + <title> + A Title + <paragraph> + A paragraph. + +After applying transforms, the section title is promoted to become the +document title:: + + <document ids="a-title" names="a title"> + <title> + A Title + <paragraph> + A paragraph. + + +``emphasis`` +============ + +`To be completed`_. + + +``entry`` +========= + +`To be completed`_. + + +``enumerated_list`` +=================== + +The ``enumerated_list`` element contains list_item_ elements which are +uniformly marked with enumerator labels. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``enumerated_list``. + +:Children: + ``enumerated_list`` elements contain one or more list_item_ + elements. + +:Analogues: + ``enumerated_list`` is analogous to the HTML "ol" element and to + the DocBook "orderedlist" element. + +:Processing: + Each list item should begin a new vertical block, prefaced by a + enumeration marker (such as "1."). + + +Content Model +------------- + +.. parsed-literal:: + + (list_item_ +) + +:Attributes: + The ``enumerated_list`` element contains the `common attributes`_ + (ids_, names_, dupnames_, source_, and classes_), plus enumtype_, + prefix_, suffix_, and start_. + + ``enumtype`` is used to record the intended enumeration sequence, + one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z), + "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ..., + mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ..., + MMMMCMXCIX [4999]). + + ``prefix`` stores the formatting characters used before the + enumerator. In documents originating from reStructuredText_ data, + it will contain either "" (empty string) or "(" (left + parenthesis). It may or may not affect processing. + + ``suffix`` stores the formatting characters used after the + enumerator. In documents originating from reStructuredText_ data, + it will contain either "." (period) or ")" (right parenthesis). + Depending on the capabilities of the output format, this attribute + may or may not affect processing. + + ``start`` contains the ordinal value of the first item in the + list, in decimal. For lists beginning at value 1 ("1", "a", "A", + "i", or "I"), this attribute may be omitted. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``enumerated_list``. The `%structure.model;`_ parameter entity + indirectly includes ``enumerated_list``. + + +Examples +-------- + +reStructuredText_ source:: + + 1. Item 1. + + (A) Item A. + (B) Item B. + (C) Item C. + + 2. Item 2. + +Pseudo-XML_ fragment from simple parsing:: + + <enumerated_list enumtype="arabic" prefix="" suffix="."> + <list_item> + <paragraph> + Item 1. + <enumerated_list enumtype="upperalpha" prefix="(" suffix=")"> + <list_item> + <paragraph> + Item A. + <list_item> + <paragraph> + Item B. + <list_item> + <paragraph> + Item C. + <list_item> + <paragraph> + Item 2. + +See list_item_ for another example. + + +``error`` +========= + +The ``error`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, hint_, important_, note_, tip_, warning_, and the generic +admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``error``. + +:Children: + ``error`` elements contain one or more `body elements`_. + +:Analogues: + ``error`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Error" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``error`` element contains only the `common attributes`_: ids_, + names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``error``. The `%structure.model;`_ parameter entity indirectly + includes ``error``. + + +Examples +-------- + +reStructuredText source:: + + .. Error:: Does not compute. + +Pseudo-XML_ fragment from simple parsing:: + + <error> + <paragraph> + Does not compute. + + +``field`` +========= + +The ``field`` element contains a pair of field_name_ and field_body_ +elements. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + The following elements may contain ``field``: docinfo_, + field_list_ + +:Children: + Each ``field`` element contains one field_name_ and one + field_body_ element. + +:Analogues: + ``field`` has no direct analogues in common DTDs. + +:Processing: + See field_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (field_name_, field_body_) + +:Attributes: + The ``field`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``field``. + + +Examples +-------- + +See the examples for the field_list_ and docinfo_ elements. + + +``field_body`` +============== + +The ``field_body`` element contains body elements. It is analogous to +a database field's data. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the field_ element contains ``field_body``. + +:Children: + ``field_body`` elements may contain `body elements`_. + +:Analogues: + ``field_body`` has no direct analogues in common DTDs. + +:Processing: + See field_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)* + +:Attributes: + The ``field_body`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the field_list_ and docinfo_ elements. + + +``field_list`` +============== + +The ``field_list`` element contains two-column table-like structures +resembling database records (label & data pairs). Field lists are +often meant for further processing. In reStructuredText_, field lists +are used to represent bibliographic fields (contents of the docinfo_ +element) and directive options. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``field_list``. + +:Children: + ``field_list`` elements contain one or more field_ elements. + +:Analogues: + ``field_list`` has no direct analogues in common DTDs. It can be + emulated with primitives such as tables. + +:Processing: + A ``field_list`` is typically rendered as a two-column list, where + the first column contains "labels" (usually with a colon suffix). + However, field lists are often used for extension syntax or + special processing. Such structures do not survive as field lists + to be rendered. + + +Content Model +------------- + +.. parsed-literal:: + + (field_ +) + +:Attributes: + The ``field_list`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``field_list``. The `%structure.model;`_ parameter entity + indirectly includes ``field_list``. + + +Examples +-------- + +reStructuredText_ source:: + + :Author: Me + :Version: 1 + :Date: 2001-08-11 + :Parameter i: integer + +Pseudo-XML_ fragment from simple parsing:: + + <field_list> + <field> + <field_name> + Author + <field_body> + <paragraph> + Me + <field> + <field_name> + Version + <field_body> + <paragraph> + 1 + <field> + <field_name> + Date + <field_body> + <paragraph> + 2001-08-11 + <field> + <field_name> + Parameter i + <field_body> + <paragraph> + integer + + +``field_name`` +============== + +The ``field_name`` element contains text; it is analogous to a +database field's name. + + +Details +------- + +:Category: + `Body Subelements`_ (simple) + +:Parents: + Only the field_ element contains ``field_name``. + +:Children: + ``field_name`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``field_name`` has no direct analogues in common DTDs. + +:Processing: + See field_list_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``field_name`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the field_list_ and docinfo_ elements. + + +``figure`` +========== + +`To be completed`_. + + +``footer`` +========== + +The ``footer`` element is a container element whose contents are meant +to appear at the bottom of a web page, or repeated at the bottom of +every printed page. The ``footer`` element may contain processing +information (datestamp, a link to Docutils_, etc.) as well as custom +content. + + +Details +------- + +:Category: + `Decorative Elements`_ + +:Parents: + Only the decoration_ element contains ``footer``. + +:Children: + ``footer`` elements may contain `body elements`_. + +:Analogues: + There are no direct analogies to ``footer`` in HTML or DocBook. + Equivalents are typically constructed from primitives and/or + generated by the processing system. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``footer`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +reStructuredText_ source:: + + A paragraph. + +Complete pseudo-XML_ result after parsing and applying transforms, +assuming that the datestamp command-line option or configuration +setting has been supplied:: + + <document> + <decoration> + <footer> + <paragraph> + Generated on: 2002-08-20. + <paragraph> + A paragraph. + + +``footnote`` +============ + +`To be completed`_. + + +``footnote_reference`` +====================== + +`To be completed`_. + + +``generated`` +============= + +Docutils wraps ``generated`` elements around text that is inserted +(generated) by Docutils; i.e., text that was not in the document, like +section numbers inserted by the "sectnum" directive. + +`To be completed`_. + + +``header`` +========== + +The ``header`` element is a container element whose contents are meant +to appear at the top of a web page, or at the top of every printed +page. + + +Details +------- + +:Category: + `Decorative Elements`_ + +:Parents: + Only the decoration_ element contains ``header``. + +:Children: + ``header`` elements may contain `body elements`_. + +:Analogues: + There are no direct analogies to ``header`` in HTML or DocBook. + Equivalents are typically constructed from primitives and/or + generated by the processing system. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``header`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +reStructuredText source fragment:: + + .. header:: This space for rent. + +Pseudo-XML_ fragment from simple parsing:: + + <document> + <decoration> + <header> + <paragraph> + This space for rent. + + +``hint`` +======== + +The ``hint`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, important_, note_, tip_, warning_, and the generic +admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``hint``. + +:Children: + ``hint`` elements contain one or more `body elements`_. + +:Analogues: + ``hint`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Hint" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``hint`` element contains only the `common attributes`_: ids_, + names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``hint``. The `%structure.model;`_ parameter entity indirectly + includes ``hint``. + + +Examples +-------- + +reStructuredText source:: + + .. Hint:: It's bigger than a bread box. + +Pseudo-XML_ fragment from simple parsing:: + + <hint> + <paragraph> + It's bigger than a bread box. + + +``image`` +========= + +`To be completed`_. + + +``important`` +============= + +The ``important`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, hint_, note_, tip_, warning_, and the generic +admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``important``. + +:Children: + ``important`` elements contain one or more `body elements`_. + +:Analogues: + ``important`` is analogous to the DocBook "important" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Important" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``important`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``important``. The `%structure.model;`_ parameter entity + indirectly includes ``important``. + + +Examples +-------- + +reStructuredText source:: + + .. Important:: + + * Wash behind your ears. + * Clean up your room. + * Back up your data. + * Call your mother. + +Pseudo-XML_ fragment from simple parsing:: + + <important> + <bullet_list> + <list_item> + <paragraph> + Wash behind your ears. + <list_item> + <paragraph> + Clean up your room. + <list_item> + <paragraph> + Back up your data. + <list_item> + <paragraph> + Call your mother. + + +``inline`` +========== + +`To be completed`_. + + +``label`` +========= + +`To be completed`_. + + +``legend`` +========== + +`To be completed`_. + + +``line`` +======== + +The ``line`` element contains a single line of text, part of a +`line_block`_. + + +Details +------- + +:Category: + `Body Subelements`_ (simple) + +:Parents: + Only the `line_block`_ element contains ``line``. + +:Children: + ``line`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``line`` has no direct analogues in common DTDs. It can be + emulated with primitives or type effects. + +:Processing: + See `line_block`_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``line`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus `xml:space`_. + + +Examples +-------- + +See `line_block`_. + + +``line_block`` +============== + +The ``line_block`` element contains a sequence of lines and nested +line blocks. Line breaks (implied between elements) and leading +whitespace (indicated by nesting) is significant and must be +preserved. ``line_block`` elements are commonly used for verse and +addresses. See `literal_block`_ for an alternative useful for program +listings and interactive computer sessions. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``line_block``. + +:Children: + ``line_block`` elements may contain line_ elements and nested + ``line_block`` elements. + +:Analogues: + ``line_block`` is analogous to the DocBook "literallayout" element + and to the HTML "pre" element (with modifications to typeface + styles). + +:Processing: + Unline ``literal_block``, ``line_block`` elements are typically + rendered in an ordinary text typeface. It is crucial that leading + whitespace and line breaks are preserved in the rendered form. + + +Content Model +------------- + +.. parsed-literal:: + + (line_ | line_block_)+ + +:Attributes: + The ``line_block`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus `xml:space`_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``line_block``. The `%structure.model;`_ parameter entity + indirectly includes ``line_block``. + + +Examples +-------- + +reStructuredText uses a directive to indicate a ``line_block``. +Example source:: + + 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... + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + Take it away, Eric the Orchestra Leader! + <line_block> + <line> + A one, two, a one two three four + <line> + <line> + Half a bee, philosophically, + <line_block> + <line> + must, + <emphasis> + ipso facto + , half not be. + <line> + But half the bee has got to be, + <line_block> + <line> + <emphasis> + vis a vis + its entity. D'you see? + <line> + <line> + But can a bee be said to be + <line_block> + <line> + or not to be an entire bee, + <line_block> + <line> + when half the bee is not a bee, + <line_block> + <line> + due to some ancient injury? + <line> + <line> + Singing... + + +``list_item`` +============= + +The ``list_item`` element is a container for the elements of a list +item. + + +Details +------- + +:Category: + `Body Subelements`_ (compound) + +:Parents: + The bullet_list_ and enumerated_list_ elements contain + ``list_item``. + +:Children: + ``list_item`` elements may contain `body elements`_. + +:Analogues: + ``list_item`` is analogous to the HTML "li" element and to the + DocBook "listitem" element. + +:Processing: + See bullet_list_ or enumerated_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)* + +:Attributes: + The ``list_item`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +reStructuredText_ source:: + + 1. Outer list, item 1. + + * Inner list, item 1. + * Inner list, item 2. + + 2. Outer list, item 2. + +Pseudo-XML_ fragment from simple parsing:: + + <enumerated_list enumtype="arabic" prefix="" suffix="."> + <list_item> + <paragraph> + Outer list, item 1. + <bullet_list bullet="*"> + <list_item> + <paragraph> + Inner list, item 1. + <list_item> + <paragraph> + Inner list, item 2. + <list_item> + <paragraph> + Outer list, item 2. + +See bullet_list_ or enumerated_list_ for further examples. + + +``literal`` +=========== + +`To be completed`_. + + +``literal_block`` +================= + +The ``literal_block`` element contains a block of text where line +breaks and whitespace are significant and must be preserved. +``literal_block`` elements are commonly used for program listings and +interactive computer sessions. See `line_block`_ for an alternative +useful for verse and addresses. + + +Details +------- + +:Category: + `Simple Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``literal_block``. + +:Children: + ``literal_block`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``literal_block`` is analogous to the HTML "pre" element and to + the DocBook "programlisting" and "screen" elements. + +:Processing: + ``literal_block`` elements are typically rendered in a monospaced + typeface. It is crucial that all whitespace and line breaks are + preserved in the rendered form. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``literal_block`` element contains the `common attributes`_ + (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``literal_block``. The `%structure.model;`_ parameter entity + indirectly includes ``literal_block``. + + +Examples +-------- + +reStructuredText source:: + + Here is a literal block:: + + if literal_block: + text = 'is left as-is' + spaces_and_linebreaks = 'are preserved' + markup_processing = None + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + Here is a literal block: + <literal_block xml:space="preserve"> + if literal_block: + text = 'is left as-is' + spaces_and_linebreaks = 'are preserved' + markup_processing = None + + +``note`` +======== + +The ``note`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, hint_, important_, tip_, warning_, and the generic +admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``note``. + +:Children: + ``note`` elements contain one or more `body elements`_. + +:Analogues: + ``note`` is analogous to the DocBook "note" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Note" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``note`` element contains only the `common attributes`_: ids_, + names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``note``. The `%structure.model;`_ parameter entity indirectly + includes ``note``. + + +Examples +-------- + +reStructuredText source:: + + .. Note:: Admonitions can be handy to break up a + long boring technical document. + +Pseudo-XML_ fragment from simple parsing:: + + <note> + <paragraph> + Admonitions can be handy to break up a + long boring technical document. + +``option`` +========== + +The ``option`` element groups an option string together with zero or +more option argument placeholders. Note that reStructuredText_ +currently supports only one argument per option. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_group_ element contains ``option``. + +:Children: + Each ``option`` element contains one option_string_ and zero or + more option_argument_ elements. + +:Analogues: + ``option`` has no direct analogues in common DTDs. + +:Processing: + See option_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (option_string_, option_argument_ \*) + +:Attributes: + The ``option`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the option_list_ element. + + +``option_argument`` +=================== + +The ``option_argument`` element contains placeholder text for option +arguments. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_ element contains ``option_argument``. + +:Children: + ``option_argument`` elements contain text data only. + +:Analogues: + ``option_argument`` has no direct analogues in common DTDs. + +:Processing: + The value of the "delimiter" attribute is prefixed to the + ``option_argument``, separating it from its option_string_ or a + preceding ``option_argument``. The ``option_argument`` text is + typically rendered in a monospaced typeface, possibly italicized + or otherwise altered to indicate its placeholder nature. + + +Content Model +------------- + +.. parsed-literal:: + + (#PCDATA) + +:Attributes: + The ``option_argument`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus delimiter_. + + ``delimiter`` contains the text preceding the ``option_argument``: + either the text separating it from the option_string_ (typically + either "=" or " ") or the text between option arguments (typically + either "," or " "). + + +Examples +-------- + +See the examples for the option_list_ element. + + +``option_group`` +================ + +The ``option_group`` element groups together one or more option_ +elements, all synonyms. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_list_item_ element contains ``option_group``. + +:Children: + ``option_group`` elements contain one or more option_ elements. + + ``option_group`` is an empty element and has no children. + + Each ``option_group`` element contains one _ and + one _ element. + +:Analogues: + ``option_group`` has no direct analogues in common DTDs. + +:Processing: + Typically option_ elements within an ``option_group`` are joined + together in a comma-separated list. + + +Content Model +------------- + +.. parsed-literal:: + + (option_group_, description_) + +:Attributes: + The ``option_group`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the option_list_ element. + + +``option_list`` +=============== + +Each ``option_list`` element contains a two-column list of +command-line options and descriptions, documenting a program's +options. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``option_list``. + +:Children: + ``option_list`` elements contain one or more option_list_item_ + elements. + +:Analogues: + ``option_list`` has no direct analogues in common DTDs. It can be + emulated with primitives such as tables. + +:Processing: + An ``option_list`` is typically rendered as a two-column list, + where the first column contains option strings and arguments, and + the second column contains descriptions. + + +Content Model +------------- + +.. parsed-literal:: + + (option_list_item_ +) + +:Attributes: + The ``option_list`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``option_list``. The `%structure.model;`_ parameter entity + indirectly includes ``option_list``. + + +Examples +-------- + +reStructuredText_ source:: + + -a command-line option "a" + -1 file, --one=file, --two file + Multiple options with arguments. + +Pseudo-XML_ fragment from simple parsing:: + + <option_list> + <option_list_item> + <option_group> + <option> + <option_string> + -a + <description> + <paragraph> + command-line option "a" + <option_list_item> + <option_group> + <option> + <option_string> + -1 + <option_argument delimiter=" "> + file + <option> + <option_string> + --one + <option_argument delimiter="="> + file + <option> + <option_string> + --two + <option_argument delimiter=" "> + file + <description> + <paragraph> + Multiple options with arguments. + + +``option_list_item`` +==================== + +The ``option_list_item`` element is a container for a pair of +option_group_ and description_ elements. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_list_ element contains ``option_list_item``. + +:Children: + Each ``option_list_item`` element contains one option_group_ and + one description_ element. + +:Analogues: + ``option_list_item`` has no direct analogues in common DTDs. + +:Processing: + See option_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (option_group_, description_) + +:Attributes: + The ``option_list_item`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the option_list_ element. + + +``option_string`` +================= + +The ``option_string`` element contains the text of a command-line +option. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_ element contains ``option_string``. + +:Children: + ``option_string`` elements contain text data only. + +:Analogues: + ``option_string`` has no direct analogues in common DTDs. + +:Processing: + The ``option_string`` text is typically rendered in a monospaced + typeface. + + +Content Model +------------- + +.. parsed-literal:: + + (#PCDATA) + +:Attributes: + The ``option_string`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the option_list_ element. + + +``organization`` +================ + +The ``organization`` element contains the name of document author's +organization, or the organization responsible for the document. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + Only the docinfo_ element contains ``organization``. + +:Children: + ``organization`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``organization`` is analogous to the DocBook "orgname", + "corpname", or "publishername" elements. + +:Processing: + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``organization`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``organization``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Organization: Humankind + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <organization> + Humankind + +See docinfo_ for a more complete example, including processing +context. + + +``paragraph`` +============= + +The ``paragraph`` element contains the text and inline elements of a +single paragraph, a fundamental building block of documents. + + +Details +------- + +:Category: + `Simple Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``paragraph``. + +:Children: + ``paragraph`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``paragraph`` is analogous to the HTML "p" element and to the + DocBook "para" elements. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``paragraph`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``paragraph``. The `%structure.model;`_ parameter entity + indirectly includes ``paragraph``. + + +Examples +-------- + +reStructuredText_ source:: + + A paragraph. + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + A paragraph. + + +``pending`` +=========== + +`To be completed`_. + + +``problematic`` +=============== + +`To be completed`_. + + +``raw`` +======= + +`To be completed`_. + + +``reference`` +============= + +`To be completed`_. + + +``revision`` +============ + +The ``revision`` element contains the revision number of the document. +It can be used alone or in conjunction with version_. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + Only the docinfo_ element contains ``revision``. + +:Children: + ``revision`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``revision`` is analogous to but simpler than the DocBook + "revision" element. It closely matches the DocBook "revnumber" + element, but in a simpler context. + +:Processing: + Often used with the RCS/CVS keyword "Revision". See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``revision`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``revision``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Version: 1 + :Revision: b + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <version> + 1 + <revision> + b + +See docinfo_ for a more complete example, including processing +context. + + +``row`` +======= + +`To be completed`_. + + +``rubric`` +========== + + 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 + +A rubric is like an informal heading that doesn't correspond to the +document's structure. + +`To be completed`_. + + +``section`` +=========== + +The ``section`` element is the main unit of hierarchy for Docutils +documents. Docutils ``section`` elements are a recursive structure; a +``section`` may contain other ``section`` elements, without limit. +Paragraphs and other body elements may occur before a ``section``, but +not after it. + + +Details +------- + +:Category: + `Structural Elements`_ + +:Parents: + The following elements may contain ``section``: document_, + section_ + +:Children: + ``section`` elements begin with a title_, and may contain `body + elements`_ as well as transition_, topic_, and sidebar_ elements. + +:Analogues: + ``section`` is analogous to DocBook recursive "section" elements, + and to HTML "div" elements combined with "h1" etc. title elements. + + +Content Model +------------- + +.. parsed-literal:: + + (title_, + `%structure.model;`_) + +See the `%structure.model;`_ parameter entity for details of the body +of a ``section``. + +:Attributes: + The ``section`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%section.elements;`_ parameter entity directly includes + ``section``. The `%structure.model;`_ parameter entity indirectly + includes ``section``. + + +Examples +-------- + +reStructuredText_ source:: + + Title 1 + ======= + Paragraph 1. + + Title 2 + ------- + Paragraph 2. + + Title 3 + ======= + Paragraph 3. + + Title 4 + ------- + Paragraph 4. + +Complete pseudo-XML_ result after parsing:: + + <document> + <section ids="title-1" names="title 1"> + <title> + Title 1 + <paragraph> + Paragraph 1. + <section ids="title-2" names="title 2"> + <title> + Title 2 + <paragraph> + Paragraph 2. + <section ids="title-3" names="title 3"> + <title> + Title 3 + <paragraph> + Paragraph 3. + <section ids="title-4" names="title 4"> + <title> + Title 4 + <paragraph> + Paragraph 4. + + +``sidebar`` +=========== + +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. + +The ``sidebar`` element is a nonrecursive section_-like construct +which may occur at the top level of a section_ wherever a body element +(list, table, etc.) is allowed. In other words, ``sidebar`` elements +cannot nest inside body elements, so you can't have a ``sidebar`` +inside a ``table`` or a ``list``, or inside another ``sidebar`` (or +topic_). + + +Details +------- + +:Category: + `Structural Elements`_ + +:Parents: + The following elements may contain ``sidebar``: document_, + section_ + +:Children: + ``sidebar`` elements begin with a title_ and an optional subtitle_ + and contain `body elements`_ and topic_ elements. + +:Analogues: + ``sidebar`` is analogous to the DocBook "sidebar" element. + +:Processing: + A ``sidebar`` element should be set off from the rest of the + document somehow, typically with a border. Sidebars typically + "float" to the side of the page and the document's main text flows + around them. + + +Content Model +------------- + +.. parsed-literal:: + + (title_, subtitle_?, + (`%body.elements;`_ | topic_)+) + +:Attributes: + The ``sidebar`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%structure.model;`_ parameter entity directly includes + ``sidebar``. + + +Examples +-------- + +The `"sidebar" directive`_ is used to create a ``sidebar`` element. +reStructuredText_ source:: + + .. sidebar:: Title + :subtitle: If Desired + + Body. + +Pseudo-XML_ fragment from simple parsing:: + + <sidebar> + <title> + Title + <subtitle> + If Desired + <paragraph> + Body. + +.. _"sidebar" directive: rst/directives.html#sidebar + + +``status`` +========== + +The ``status`` element contains a status statement for the document, +such as "Draft", "Final", "Work In Progress", etc. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + Only the docinfo_ element contains ``status``. + +:Children: + ``status`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``status`` is analogous to the DocBook "status" element. + +:Processing: + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``status`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``status``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Status: Work In Progress + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <status> + Work In Progress + +See docinfo_ for a more complete example, including processing +context. + + +``strong`` +========== + +`To be completed`_. + + +``subscript`` +============= + +`To be completed`_. + + +``substitution_definition`` +=========================== + +`To be completed`_. + + +``substitution_reference`` +========================== + +`To be completed`_. + + +``subtitle`` +============ + +The ``subtitle`` element stores the subtitle of a document_. + + +Details +------- + +:Category: + `Structural Subelements`_ + +:Parents: + The document_ and sidebar_ elements may contain ``subtitle``. + +:Children: + ``subtitle`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``subtitle`` is analogous to HTML header elements ("h2" etc.) and + to the DocBook "subtitle" element. + +:Processing: + A document's subtitle is usually rendered smaller than its title_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``subtitle`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +reStructuredText_ source:: + + ======= + Title + ======= + ---------- + Subtitle + ---------- + + A paragraph. + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="title" names="title"> + <title> + Title + <subtitle ids="subtitle" names="subtitle"> + Subtitle + <paragraph> + A paragraph. + +Note how two section levels have collapsed, promoting their titles to +become the document's title and subtitle. Since there is only one +structural element (document), the subsection's ``ids`` and ``names`` +attributes are stored in the ``subtitle`` element. + + +``superscript`` +=============== + +`To be completed`_. + + +``system_message`` +================== + +`To be completed`_. + + +``table`` +========= + +`To be completed`_. + + +``target`` +========== + +`To be completed`_. + + +``tbody`` +========= + +`To be completed`_. + + +``term`` +======== + +The ``term`` element contains a word or phrase being defined in a +definition_list_. + + +Details +------- + +:Category: + `Body Subelements`_ (simple) + +:Parents: + Only the definition_list_item_ element contains ``term``. + +:Children: + ``term`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``term`` is analogous to the HTML "dt" element and to the DocBook + "term" element. + +:Processing: + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``term`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the definition_list_, definition_list_item_, and +classifier_ elements. + + +``tgroup`` +========== + +`To be completed`_. + + +``thead`` +========= + +`To be completed`_. + + +``tip`` +======= + +The ``tip`` element is an admonition, a distinctive and self-contained +notice. Also see the other admonition elements Docutils offers (in +alphabetical order): attention_, caution_, danger_, error_, hint_, +important_, note_, warning_, and the generic admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``tip``. + +:Children: + ``tip`` elements contain one or more `body elements`_. + +:Analogues: + ``tip`` is analogous to the DocBook "tip" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Tip" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``tip`` element contains only the `common attributes`_: ids_, + names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes ``tip``. + The `%structure.model;`_ parameter entity indirectly includes + ``tip``. + + +Examples +-------- + +reStructuredText source:: + + .. Tip:: 15% if the service is good. + +Pseudo-XML_ fragment from simple parsing:: + + <tip> + <paragraph> + 15% if the service is good. + + +.. _title: + +``title`` +========= + +The ``title`` element stores the title of a document_, section_, +topic_, sidebar_, or generic admonition_. + + +Details +------- + +:Category: + `Structural Subelements`_ + +:Parents: + The following elements may contain ``title``: document_, section_, + topic_, sidebar_, admonition_ + +:Children: + ``title`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``title`` is analogous to HTML "title" and header ("h1" etc.) + elements, and to the DocBook "title" element. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``title`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus refid_ and auto_. + + ``refid`` is used as a backlink to a table of contents entry. + + ``auto`` is used to indicate (with value "1") that the ``title`` + has been numbered automatically. + + +Examples +-------- + +reStructuredText_ source:: + + A Title + ======= + + A paragraph. + +Pseudo-XML_ fragment from simple parsing:: + + <section ids="a-title" names="a title"> + <title> + A Title + <paragraph> + A paragraph. + + +``title_reference`` +=================== + +`To be completed`_. + + +``topic`` +========= + +The ``topic`` element is a nonrecursive section_-like construct which +may occur at the top level of a section_ wherever a body element +(list, table, etc.) is allowed. In other words, ``topic`` elements +cannot nest inside body elements, so you can't have a ``topic`` inside +a ``table`` or a ``list``, or inside another ``topic``. + + +Details +------- + +:Category: + `Structural Elements`_ + +:Parents: + The following elements may contain ``topic``: document_, section_, + sidebar_ + +:Children: + ``topic`` elements begin with a title_ and may contain `body + elements`_. + +:Analogues: + ``topic`` is analogous to the DocBook "simplesect" element. + +:Processing: + A ``topic`` element should be set off from the rest of the + document somehow, such as with indentation or a border. + + +Content Model +------------- + +.. parsed-literal:: + + (title_?, + (`%body.elements;`_)+) + +:Attributes: + The ``topic`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%structure.model;`_ parameter entity directly includes + ``topic``. + + +Examples +-------- + +The `"topic" directive`_ is used to create a ``topic`` element. +reStructuredText_ source:: + + .. topic:: Title + + Body. + +Pseudo-XML_ fragment from simple parsing:: + + <topic> + <title> + Title + <paragraph> + Body. + +.. _"topic" directive: rst/directives.html#topic + + +``transition`` +============== + +The ``transition`` element is 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 body +elements and sections, dividing a section into untitled divisions. A +transition may not begin or end a section [#]_ or document, nor may +two transitions be immediately adjacent. + +See `Doctree Representation of Transitions`__ in `A Record of +reStructuredText Syntax Alternatives`__. + +.. [#] In reStructuredText markup, a transition may appear to fall at + the end of a section immediately before another section. A + transform recognizes this case and moves the transition so it + separates the sections. + +__ ../dev/rst/alternatives.html#doctree-representation-of-transitions +__ ../dev/rst/alternatives.html + + +Details +------- + +:Category: + `Structural Subelements`_ + +:Parents: + The following elements may contain ``transition``: document_, + section_ + +:Children: + ``transition`` is an empty element and has no children. + +:Analogues: + ``transition`` is analogous to the HTML "hr" element. + +:Processing: + The ``transition`` element is typically rendered as vertical + whitespace (more than that separating paragraphs), with or without + a horizontal line or row of asterisks. In novels, transitions are + often represented as a row of three well-spaced asterisks with + vertical space above and below. + + +Content Model +------------- + +:: + + EMPTY + +The ``transition`` element has no content; it is a "point element". + +:Attributes: + The ``transition`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%structure.model;`_ parameter entity directly includes + ``transition``. + + +Examples +-------- + +reStructuredText_ source:: + + Paragraph 1. + + -------- + + Paragraph 2. + +Complete pseudo-XML_ result after parsing:: + + <document> + <paragraph> + Paragraph 1. + <transition> + <paragraph> + Paragraph 2. + + +``version`` +=========== + +The ``version`` element contains the version number of the document. +It can be used alone or in conjunction with revision_. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + Only the docinfo_ element contains ``version``. + +:Children: + ``version`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``version`` may be considered analogous to the DocBook "revision", + "revnumber", or "biblioid" elements. + +:Processing: + Sometimes used with the RCS/CVS keyword "Revision". See docinfo_ + and revision_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``version`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``version``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Version: 1.1 + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <version> + 1.1 + +See docinfo_ for a more complete example, including processing +context. + + +``warning`` +=========== + +The ``warning`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, hint_, important_, note_, tip_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``warning``. + +:Children: + ``warning`` elements contain one or more `body elements`_. + +:Analogues: + ``warning`` is analogous to the DocBook "warning" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Warning" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``warning`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``warning``. The `%structure.model;`_ parameter entity indirectly + includes ``warning``. + + +Examples +-------- + +reStructuredText source:: + + .. WARNING:: Reader discretion is strongly advised. + +Pseudo-XML_ fragment from simple parsing:: + + <warning> + <paragraph> + Reader discretion is strongly advised. + + +--------------------- + Attribute Reference +--------------------- + +.. contents:: :local: + :depth: 1 + +_`Common Attributes`: Through the `%basic.atts;`_ parameter entity, +all elements contain the following attributes: ids_, names_, dupnames_, +source_, and classes_. + +.. _attribute type: + +Attribute types: + +``CDATA`` + Character data. ``CDATA`` attributes may contain arbitrary text. + +``ID`` + Like a ``NMTOKEN``, but it must begin with a letter (a "name + production"). Identical ``ID`` values must not appear more than + once in a document; i.e., ID values must uniquely identify their + elements. + +``IDREF`` + A reference to an ``ID`` value (a name production) of another + element. + +``IDREFS`` + One or more space-separated ``ID`` references (name productions). + +``NMTOKEN`` + A "name token". One or more of letters, digits, ".", "-", and + "_". + +``NMTOKENS`` + One or more space-separated ``NMTOKEN`` names. + +``%yesorno;`` + No if zero ("0"), yes if any other value. This is a parameter + entity which resolves to a ``NMTOKEN`` attribute type. + +``%number;`` + This emphasizes that the attribute value must be a number. This + is a parameter entity which resolves to a ``NMTOKEN`` attribute + type. + +enumeration + The attribute value may be one of a specified list of values. + + +``anonymous`` +============= + +`Attribute type`_: ``%yesorno;``. Default value: none (implies no). + +The ``anonymous`` attribute is used for unnamed hyperlinks in the +target_ and reference_ elements (via the `%anonymous.att;`_ parameter +entity). + + +``auto`` +======== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``auto`` attribute is used to indicate automatically-numbered +footnote_, footnote_reference_ and title_ elements (via the +`%auto.att;`_ parameter entity). + + +``backrefs`` +============ + +`Attribute type`_: ``IDREFS``. Default value: none. + +The ``backrefs`` attribute contains a space-separated list of ids_ +references, used for backlinks from footnote_, citation_, and +system_message_ elements (via the `%backrefs.att;`_ parameter entity). + + +``bullet`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``bullet`` attribute is used in the bullet_list_ element. + + +``classes`` +=========== + +`Attribute type`_: ``NMTOKENS``. Default value: none. + +The ``classes`` attribute is a list containing one or more names used +to classify an element. The purpose of the attribute is to indicate +an "is-a" variant relationship, to allow an extensible way of defining +sub-classes of existing elements. It can be used to carry context +forward between a Docutils Reader and Writer, when a custom structure +is reduced to a standardized document tree. One common use is in +conjunction with stylesheets, to add selection criteria. It should +not be used to carry formatting instructions or arbitrary content. + +The ``classes`` attribute's contents should be ignorable. Writers that +are not familiar with the variant expressed should be able to ignore +the attribute. + +``classes`` is one of the `common attributes`_, shared by all Docutils +elements. + + +``delimiter`` +============= + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``delimiter`` attribute is used in the option_argument_ element. + + +``dupnames`` +============ + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``dupnames`` attribute is a list containing the names of an +element when there has been a naming conflict. The contents of the +``dupnames`` attribute would have been transferred from the `names`_ +attribute. An element may have at most one of the ``names`` or +``dupnames`` attributes, but not both. ``dupnames`` is one of the +`common attributes`_, shared by all Docutils elements. + + +``enumtype`` +============ + +`Attribute type`_: enumeration, one of "arabic", "loweralpha", +"upperalpha", "lowerroman", or "upperroman". Default value: none. + +The ``enumtype`` attribute is used in the enumerated_list_ element. + + +``ids`` +======= + +`Attribute type`_: ``NMTOKENS``. Default value: none. + +The ``ids`` attribute is a list containing one or more unique +identifier keys. ``ids`` is one of the `common attributes`_, shared +by all Docutils elements. + + +``names`` +========= + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``names`` attribute is a list containing the names of an element, +typically originating from the element's title or content. Each name +in ``names`` must be unique; if there are name conflicts (two or more +elements want to the same name), the contents will be transferred to +the `dupnames`_ attribute on the duplicate elements. An element may +have at most one of the ``names`` or ``dupnames`` attributes, but not +both. ``names`` is one of the `common attributes`_, shared by all +Docutils elements. + + +``prefix`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``prefix`` attribute is used in the enumerated_list_ element. + + +``refid`` +========= + +`Attribute type`_: ``IDREF``. Default value: none. + +The ``refid`` attribute contains references to `ids`_ attributes in +other elements. It is used by the target_, reference_, +footnote_reference_, citation_reference_, title_ and problematic_ +elements (via the `%refid.att;`_ and `%reference.atts;`_ parameter +entities). + + +``refname`` +=========== + +`Attribute type`_: ``NMTOKENS``. Default value: none. + +The ``refname`` attribute contains an internal reference to the +`names`_ attribute of another element. On a `target`_ element, +``refname`` indicates an indirect target which may resolve to either +an internal or external reference. ``refname`` is used by the +target_, reference_, footnote_reference_, citation_reference_, and +substitution_reference_ elements (via the `%refname.att;`_ and +`%reference.atts;`_ parameter entities). + + +``refuri`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``refuri`` attribute contains an external reference to a URI/URL. +It is used by the target_, reference_, footnote_reference_, and +citation_reference_ elements (via the `%reference.atts;`_ parameter +entity). + + +``source`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``source`` attribute is used to store the path or URL to the +source text that was used to produce the document tree. It is one of +the `common attributes`_, shared by all Docutils elements. + + +``start`` +========= + +`Attribute type`_: ``%number;``. Default value: none. + +The ``start`` attribute is used in the enumerated_list_ element. + + +``suffix`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``suffix`` attribute is used in the enumerated_list_ element. + + +``xml:space`` +============= + +`Attribute type`_: one of "default" or "preserve". Default value: +"preserve" (fixed). + +The ``xml:space`` attribute is a standard XML attribute for +whitespace-preserving elements. It is used by the literal_block_, +line_block_, doctest_block_, comment_, and raw_ elements (via the +`%fixedspace.att;`_ parameter entity). It is a fixed attribute, meant +to communicate to an XML parser that the element contains significant +whitespace. The attribute value should not be set in a document +instance. + + +.. _title (attribute): + +``title`` +========= + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``title`` attribute stores the title metadata of a document. This +title is typically not part of the rendered document. It may for +example be used in HTML's ``title`` element. + + +---------------------------- + Parameter Entity Reference +---------------------------- + +.. contents:: :local: + :depth: 1 + +Parameter entities are used to simplify the DTD (to share definitions +and reduce duplication) and to allow the DTD to be customized by +wrapper DTDs (external client DTDs that use or import the Docutils +DTD). Parameter entities may be overridden by wrapper DTDs, replacing +the definitions below with custom definitions. Parameter entities +whose names begin with "additional" are meant to allow easy extension +by wrapper DTDs. + + +``%anonymous.att;`` +=================== + +The ``%anonymous.att;`` parameter entity contains the anonymous_ +attribute, used for unnamed hyperlinks. + +Entity definition: + +.. parsed-literal:: + + anonymous_ %yesorno; #IMPLIED + +The reference_ and target_ elements directly employ the +``%anonymous.att;`` parameter entity in their attribute lists. + + +``%auto.att;`` +============== + +The ``%auto.att;`` parameter entity contains the auto_ attribute, used +to indicate an automatically-numbered footnote or title. + +Entity definition: + +.. parsed-literal:: + + auto_ CDATA #IMPLIED + +The footnote_, footnote_reference_, and title_ elements directly +employ the ``%auto.att;`` parameter entity in their attribute lists. + + +``%backrefs.att;`` +================== + +The ``%backrefs.att;`` parameter entity contains the backrefs_ +attribute, a space-separated list of id references, for backlinks. + +Entity definition: + +.. parsed-literal:: + + backrefs_ IDREFS #IMPLIED + +The citation_, footnote_, and system_message_ elements directly employ +the ``%backrefs.att;`` parameter entity in their attribute lists. + + +``%basic.atts;`` +================ + +The ``%basic.atts;`` parameter entity lists attributes common to all +Docutils elements. See `Common Attributes`_. + +Entity definition: + +.. parsed-literal:: + + ids_ NMTOKENS #IMPLIED + names_ CDATA #IMPLIED + dupnames_ CDATA #IMPLIED + source_ CDATA #IMPLIED + classes_ NMTOKENS #IMPLIED + %additional.basic.atts; + +The ``%additional.basic.atts;`` parameter entity can be used by +wrapper DTDs to extend ``%basic.atts;``. + + +``%bibliographic.elements;`` +============================ + +The ``%bibliographic.elements;`` parameter entity contains an OR-list of all +`bibliographic elements`_. + +Entity definition: + +.. parsed-literal:: + + author_ | authors_ | organization_ | contact_ | address_ + | version_ | revision_ | status_ | date_ | copyright_ + | field_ + %additional.bibliographic.elements; + +The ``%additional.bibliographic.elements;`` parameter entity can be used by +wrapper DTDs to extend ``%bibliographic.elements;``. + +Only the docinfo_ element directly employs the +``%bibliographic.elements;`` parameter entity in its content model. + + +``%body.elements;`` +=================== + +The ``%body.elements;`` parameter entity contains an OR-list of all +`body elements`_. ``%body.elements;`` is itself contained within the +`%structure.model;`_ parameter entity. + +Entity definition: + +.. parsed-literal:: + + paragraph_ | compound_ | container_ | literal_block_ | doctest_block_ + | line_block_ | block_quote_ + | table_ | figure_ | image_ | footnote_ | citation_ | rubric_ + | bullet_list_ | enumerated_list_ | definition_list_ | field_list_ + | option_list_ + | attention_ | caution_ | danger_ | error_ | hint_ | important_ | note_ + | tip_ | warning_ | admonition_ + | reference_ | target_ | substitution_definition_ | comment_ | pending_ + | system_message_ | raw_ + %additional.body.elements; + +The ``%additional.body.elements;`` parameter entity can be used by +wrapper DTDs to extend ``%body.elements;``. + +The ``%body.elements;`` parameter entity is directly employed in the +content models of the following elements: admonition_, attention_, +block_quote_, caution_, citation_, compound_, danger_, definition_, +description_, entry_, error_, field_body_, footer_, footnote_, +header_, hint_, important_, legend_, list_item_, note_, sidebar_, +system_message_, tip_, topic_, warning_ + +Via `%structure.model;`_, the ``%body.elements;`` parameter entity is +indirectly employed in the content models of the document_ and +section_ elements. + + +``%fixedspace.att;`` +==================== + +The ``%fixedspace.att;`` parameter entity contains the `xml:space`_ +attribute, a standard XML attribute for whitespace-preserving +elements. + +Entity definition: + +.. parsed-literal:: + + `xml:space`_ (default | preserve) #FIXED 'preserve' + +The ``%fixedspace.att;`` parameter entity is directly employed in the +attribute lists of the following elements: address_, comment_, +doctest_block_, line_block_, literal_block_, raw_ + + +``%inline.elements;`` +===================== + +The ``%inline.elements;`` parameter entity contains an OR-list of all +`inline elements`_. + +Entity definition: + +.. parsed-literal:: + + emphasis_ | strong_ | literal_ + | reference_ | footnote_reference_ | citation_reference_ + | substitution_reference_ | title_reference_ + | abbreviation_ | acronym_ | subscript_ | superscript_ + | inline_ | problematic_ | generated_ + | target_ | image_ | raw_ + %additional.inline.elements; + +The ``%additional.inline.elements;`` parameter entity can be used by +wrapper DTDs to extend ``%inline.elements;``. + +Via `%text.model;`_, the ``%inline.elements;`` parameter entity is +indirectly employed in the content models of the following elements: +abbreviation_, acronym_, address_, attribution_, author_, caption_, +classifier_, contact_, copyright_, date_, doctest_block_, emphasis_, +generated_, inline_, line_block_, literal_block_, organization_, +paragraph_, problematic_, raw_, reference_, revision_, rubric_, +status_, strong_, subscript_, substitution_definition_, +substitution_reference_, subtitle_, superscript_, target_, term_, +title_, title_reference_, version_ + + +``%reference.atts;`` +==================== + +The ``%reference.atts;`` parameter entity groups together the refuri_, +refid_, and refname_ attributes. + +Entity definition: + +.. parsed-literal:: + + `%refuri.att;`_ + `%refid.att;`_ + `%refname.att;`_ + %additional.reference.atts; + +The ``%additional.reference.atts;`` parameter entity can be used by +wrapper DTDs to extend ``%additional.reference.atts;``. + +The citation_reference_, footnote_reference_, reference_, and target_ +elements directly employ the ``%reference.att;`` parameter entity in +their attribute lists. + + +``%refid.att;`` +================ + +The ``%refid.att;`` parameter entity contains the refid_ attribute, an +internal reference to the `ids`_ attribute of another element. + +Entity definition: + +.. parsed-literal:: + + refid_ CDATA #IMPLIED + +The title_ and problematic_ elements directly employ the +``%refid.att;`` parameter entity in their attribute lists. + +Via `%reference.atts;`_, the ``%refid.att;`` parameter entity is +indirectly employed in the attribute lists of the citation_reference_, +footnote_reference_, reference_, and target_ elements. + + +``%refname.att;`` +================= + +The ``%refname.att;`` parameter entity contains the refname_ +attribute, an internal reference to the `names`_ attribute of another +element. On a `target`_ element, ``refname`` indicates an indirect +target which may resolve to either an internal or external +reference. + +Entity definition: + +.. parsed-literal:: + + refname_ NMTOKENS #IMPLIED + +The substitution_reference_ element directly employs the +``%refname.att;`` parameter entity in its attribute list. + +Via `%reference.atts;`_, the ``%refname.att;`` parameter entity is +indirectly employed in the attribute lists of the citation_reference_, +footnote_reference_, reference_, and target_ elements. + + +``%refuri.att;`` +================ + +The ``%refuri.att;`` parameter entity contains the refuri_ attribute, +an external reference to a URI/URL. + +Entity definition: + +.. parsed-literal:: + + refuri_ CDATA #IMPLIED + +Via `%reference.atts;`_, the ``%refuri.att;`` parameter entity is +indirectly employed in the attribute lists of the citation_reference_, +footnote_reference_, reference_, and target_ elements. + + +``%section.elements;`` +====================== + +The ``%section.elements;`` parameter entity contains an OR-list of all +section_-equivalent elements. ``%section.elements;`` is itself +contained within the `%structure.model;`_ parameter entity. + +Entity definition: + +.. parsed-literal:: + + section_ + %additional.section.elements; + +The ``%additional.section.elements;`` parameter entity can be used +by wrapper DTDs to extend ``%section.elements;``. + +Via `%structure.model;`_, the ``%section.elements;`` parameter entity +is indirectly employed in the content models of the document_ and +section_ elements. + + +``%structure.model;`` +===================== + +The ``%structure.model;`` parameter entity encapsulates the +hierarchical structure of a document and of its constituent parts. +See the discussion of the `element hierarchy`_ above. + +Entity definition: + +.. parsed-literal:: + + ( ( (`%body.elements;`_ | topic_ | sidebar_)+, transition_? )*, + ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? ) + +Each document_ or section_ contains zero or more body elements, +topics, and/or sidebars, optionally interspersed with single +transitions, followed by zero or more sections (whose contents are +recursively the same as this model) optionally interspersed with +transitions. + +The following restrictions are imposed by this model: + +* Transitions must be separated by other elements (body elements, + sections, etc.). In other words, a transition may not be + immediately adjacent to another transition. + +* A transition may not occur at the beginning of a document or + section. + +An additional restriction, which cannot be expressed in the language +of DTDs, is imposed by software: + +* A transition may not occur at the end of a document or section. + +The `%structure.model;`_ parameter entity is directly employed in the +content models of the document_ and section_ elements. + + +``%text.model;`` +================ + +The ``%text.model;`` parameter entity is used by many elements to +represent text data mixed with `inline elements`_. + +Entity definition: + +.. parsed-literal:: + + (#PCDATA | `%inline.elements;`_)* + +The ``%text.model;`` parameter entity is directly employed in the +content models of the following elements: abbreviation_, acronym_, +address_, author_, caption_, classifier_, contact_, copyright_, date_, +doctest_block_, emphasis_, field_name_, generated_, line_block_, +literal_block_, organization_, paragraph_, problematic_, raw_, +reference_, revision_, status_, strong_, substitution_definition_, +substitution_reference_, subtitle_, target_, term_, title_, version_ + + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: diff --git a/docs/ref/docutils.dtd b/docs/ref/docutils.dtd new file mode 100644 index 000000000..154566033 --- /dev/null +++ b/docs/ref/docutils.dtd @@ -0,0 +1,606 @@ +<!-- +====================================================================== + Docutils Generic DTD +====================================================================== +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ +:Copyright: This DTD has been placed in the public domain. +:Filename: docutils.dtd + +More information about this DTD (document type definition) and the +Docutils project can be found at http://docutils.sourceforge.net/. +The latest version of this DTD is available from +http://docutils.sourceforge.net/docs/ref/docutils.dtd. + +The formal public identifier for this DTD is:: + + +//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML +--> + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Parameter Entities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Parameter entities are used to simplify the DTD (reduce duplication) +and to allow the DTD to be customized by wrapper DTDs. Parameter +entities beginning with "additional" are meant to allow easy extension +by wrapper DTDs. +--> + +<!-- Attributes +================================================================== --> + +<!-- Boolean: no if zero(s), yes if any other value. --> +<!ENTITY % yesorno "NMTOKEN"> + +<!-- Emphasize that the attribute value must be a number. --> +<!ENTITY % number "NMTOKEN"> + +<!-- A number which may be immediately followed by a unit. --> +<!ENTITY % measure "NMTOKEN"> + +<!ENTITY % additional.basic.atts ""> +<!-- +Attributes shared by all elements in this DTD: + +- `id` is a unique identifier, typically assigned by the system. +- `name` is an identifier assigned in the markup. +- `dupname` is the same as `name`, used when it's a duplicate. +- `source` is the name of the source of this document or fragment. +- `class` is used to transmit individuality information forward. +--> +<!ENTITY % basic.atts + " ids NMTOKENS #IMPLIED + names CDATA #IMPLIED + dupnames CDATA #IMPLIED + source CDATA #IMPLIED + classes NMTOKENS #IMPLIED + %additional.basic.atts; "> + +<!-- External reference to a URI/URL. --> +<!ENTITY % refuri.att + " refuri CDATA #IMPLIED "> + +<!-- Internal reference to the `id` attribute of an element. --> +<!ENTITY % refid.att + " refid IDREF #IMPLIED "> + +<!-- Space-separated list of id references, for backlinks. --> +<!ENTITY % backrefs.att + " backrefs IDREFS #IMPLIED "> + +<!-- +Internal reference to the `name` attribute of an element. On a +'target' element, 'refname' indicates an indirect target which may +resolve to either an internal or external reference. +--> +<!ENTITY % refname.att + " refname NMTOKENS #IMPLIED "> + +<!ENTITY % additional.reference.atts ""> +<!-- Collected hyperlink reference attributes. --> +<!ENTITY % reference.atts + " %refuri.att; + %refid.att; + %refname.att; + %additional.reference.atts; "> + +<!-- Unnamed hyperlink. --> +<!ENTITY % anonymous.att + " anonymous %yesorno; #IMPLIED "> + +<!-- Auto-numbered footnote or title. --> +<!ENTITY % auto.att + " auto CDATA #IMPLIED "> + +<!-- XML standard attribute for whitespace-preserving elements. --> +<!ENTITY % fixedspace.att + " xml:space (default | preserve) #FIXED 'preserve' "> + +<!ENTITY % align-h.att + " align (left | center | right) #IMPLIED "> + +<!ENTITY % align-hv.att + " align (top | middle | bottom | left | center | right) #IMPLIED "> + + +<!-- Element OR-Lists +============================================================= --> + +<!ENTITY % additional.bibliographic.elements ""> +<!ENTITY % bibliographic.elements + " author | authors | organization | address | contact + | version | revision | status | date | copyright + | field + %additional.bibliographic.elements; "> + +<!ENTITY % additional.section.elements ""> +<!ENTITY % section.elements + " section + %additional.section.elements; "> + +<!ENTITY % additional.body.elements ""> +<!ENTITY % body.elements + " paragraph | compound | container | literal_block | doctest_block + | line_block | block_quote + | table | figure | image | footnote | citation | rubric + | bullet_list | enumerated_list | definition_list | field_list + | option_list + | attention | caution | danger | error | hint | important | note + | tip | warning | admonition + | reference | target | substitution_definition | comment | pending + | system_message | raw + %additional.body.elements; "> + +<!ENTITY % additional.inline.elements ""> +<!ENTITY % inline.elements + " emphasis | strong | literal + | reference | footnote_reference | citation_reference + | substitution_reference | title_reference + | abbreviation | acronym | subscript | superscript + | inline | problematic | generated + | target | image | raw + %additional.inline.elements; "> + + +<!-- Element Content Models +================================================================== --> + +<!-- The structure model may not end with a transition. --> +<!ENTITY % structure.model + " ( ( (%body.elements; | topic | sidebar)+, transition? )*, + ( (%section.elements;), (transition?, (%section.elements;) )* )? )"> + +<!ENTITY % text.model + " (#PCDATA | %inline.elements;)* "> + + +<!-- Table Model +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This DTD uses the Exchange subset of the CALS-table model (OASIS +Technical Memorandum 9901:1999 "XML Exchange Table Model DTD", +http://www.oasis-open.org/html/tm9901.htm). +--> + +<!ENTITY % calstblx PUBLIC + "-//OASIS//DTD XML Exchange Table Model 19990315//EN" + "soextblx.dtd"> + +<!-- These parameter entities customize the table model DTD. --> +<!ENTITY % bodyatt " %basic.atts; "> <!-- table elt --> +<!ENTITY % tbl.tgroup.att " %basic.atts; "> +<!ENTITY % tbl.thead.att " %basic.atts; "> +<!ENTITY % tbl.tbody.att " %basic.atts; "> +<!ENTITY % tbl.colspec.att + " %basic.atts; + stub %yesorno; #IMPLIED "> +<!ENTITY % tbl.row.att " %basic.atts; "> +<!ENTITY % tbl.entry.mdl " (%body.elements;)* "> +<!ENTITY % tbl.entry.att + " %basic.atts; + morecols %number; #IMPLIED "> + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Root Element +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!-- Optional elements may be generated by internal processing. --> +<!ELEMENT document + ( (title, subtitle?)?, + decoration?, + (docinfo, transition?)?, + %structure.model; )> +<!ATTLIST document + %basic.atts; + title CDATA #IMPLIED> + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Title Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!ELEMENT title %text.model;> +<!ATTLIST title + %basic.atts; + %refid.att; + %auto.att;> + +<!ELEMENT subtitle %text.model;> +<!ATTLIST subtitle %basic.atts;> + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Bibliographic Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!-- Container for bibliographic elements. May not be empty. --> +<!ELEMENT docinfo (%bibliographic.elements;)+> +<!ATTLIST docinfo %basic.atts;> + +<!-- Container for bibliographic elements. May not be empty. +Eventual replacement for docinfo? --> +<!ELEMENT info (%bibliographic.elements;)+> +<!ATTLIST info %basic.atts;> + +<!ELEMENT author %text.model;> +<!ATTLIST author %basic.atts;> + +<!ELEMENT authors (author, organization?, address?, contact?)+> +<!ATTLIST authors %basic.atts;> + +<!ELEMENT organization %text.model;> +<!ATTLIST organization %basic.atts;> + +<!ELEMENT address %text.model;> +<!ATTLIST address + %basic.atts; + %fixedspace.att;> + +<!ELEMENT contact %text.model;> +<!ATTLIST contact %basic.atts;> + +<!ELEMENT version %text.model;> +<!ATTLIST version %basic.atts;> + +<!ELEMENT revision %text.model;> +<!ATTLIST revision %basic.atts;> + +<!ELEMENT status %text.model;> +<!ATTLIST status %basic.atts;> + +<!ELEMENT date %text.model;> +<!ATTLIST date %basic.atts;> + +<!ELEMENT copyright %text.model;> +<!ATTLIST copyright %basic.atts;> + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Decoration Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!ELEMENT decoration (header?, footer?)> +<!ATTLIST decoration %basic.atts;> + +<!ELEMENT header (%body.elements;)+> +<!ATTLIST header %basic.atts;> + +<!ELEMENT footer (%body.elements;)+> +<!ATTLIST footer %basic.atts;> + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Structural Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!ELEMENT section + (title, subtitle?, info?, decoration?, %structure.model;)> +<!ATTLIST section %basic.atts;> + +<!ELEMENT topic (title?, (%body.elements;)+)> +<!ATTLIST topic %basic.atts;> + +<!ELEMENT sidebar (title, subtitle?, (%body.elements; | topic)+)> +<!ATTLIST sidebar %basic.atts;> + +<!ELEMENT transition EMPTY> +<!ATTLIST transition %basic.atts;> + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Body Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--> + +<!ELEMENT paragraph %text.model;> +<!ATTLIST paragraph %basic.atts;> + +<!ELEMENT compound (%body.elements;)+> +<!ATTLIST compound %basic.atts;> + +<!ELEMENT container (%body.elements;)+> +<!ATTLIST container %basic.atts;> + +<!ELEMENT bullet_list (list_item+)> +<!ATTLIST bullet_list + %basic.atts; + bullet CDATA #IMPLIED> + +<!ELEMENT enumerated_list (list_item+)> +<!ATTLIST enumerated_list + %basic.atts; + enumtype (arabic | loweralpha | upperalpha + | lowerroman | upperroman) + #IMPLIED + prefix CDATA #IMPLIED + suffix CDATA #IMPLIED + start %number; #IMPLIED> + +<!ELEMENT list_item (%body.elements;)*> +<!ATTLIST list_item %basic.atts;> + +<!ELEMENT definition_list (definition_list_item+)> +<!ATTLIST definition_list %basic.atts;> + +<!ELEMENT definition_list_item (term, classifier*, definition)> +<!ATTLIST definition_list_item %basic.atts;> + +<!ELEMENT term %text.model;> +<!ATTLIST term %basic.atts;> + +<!ELEMENT classifier %text.model;> +<!ATTLIST classifier %basic.atts;> + +<!ELEMENT definition (%body.elements;)+> +<!ATTLIST definition %basic.atts;> + +<!ELEMENT field_list (field+)> +<!ATTLIST field_list %basic.atts;> + +<!ELEMENT field (field_name, field_body)> +<!ATTLIST field %basic.atts;> + +<!ELEMENT field_name %text.model;> +<!ATTLIST field_name %basic.atts;> + +<!-- May be empty. --> +<!ELEMENT field_body (%body.elements;)*> +<!ATTLIST field_body %basic.atts;> + +<!ELEMENT option_list (option_list_item+)> +<!ATTLIST option_list %basic.atts;> + +<!ELEMENT option_list_item (option_group, description)> +<!ATTLIST option_list_item %basic.atts;> + +<!ELEMENT option_group (option+)> +<!ATTLIST option_group %basic.atts;> + +<!ELEMENT option (option_string, option_argument*)> +<!ATTLIST option %basic.atts;> + +<!ELEMENT option_string (#PCDATA)> +<!ATTLIST option_string %basic.atts;> + +<!-- +`delimiter` contains the text preceding the `option_argument`: either +the text separating it from the `option_string` (typically either "=" +or " ") or the text between option arguments (typically either "," or +" "). +--> +<!ELEMENT option_argument (#PCDATA)> +<!ATTLIST option_argument + %basic.atts; + delimiter CDATA #IMPLIED> + +<!ELEMENT description (%body.elements;)+> +<!ATTLIST description %basic.atts;> + +<!ELEMENT literal_block %text.model;> +<!ATTLIST literal_block + %basic.atts; + %fixedspace.att;> + +<!ELEMENT line_block (line | line_block)+> +<!ATTLIST line_block %basic.atts;> + +<!ELEMENT line %text.model;> +<!ATTLIST line %basic.atts;> + +<!ELEMENT block_quote ((%body.elements;)+, attribution?)> +<!ATTLIST block_quote %basic.atts;> + +<!ELEMENT attribution %text.model;> +<!ATTLIST attribution %basic.atts;> + +<!ELEMENT doctest_block %text.model;> +<!ATTLIST doctest_block + %basic.atts; + %fixedspace.att;> + +<!ELEMENT attention (%body.elements;)+> +<!ATTLIST attention %basic.atts;> + +<!ELEMENT caution (%body.elements;)+> +<!ATTLIST caution %basic.atts;> + +<!ELEMENT danger (%body.elements;)+> +<!ATTLIST danger %basic.atts;> + +<!ELEMENT error (%body.elements;)+> +<!ATTLIST error %basic.atts;> + +<!ELEMENT hint (%body.elements;)+> +<!ATTLIST hint %basic.atts;> + +<!ELEMENT important (%body.elements;)+> +<!ATTLIST important %basic.atts;> + +<!ELEMENT note (%body.elements;)+> +<!ATTLIST note %basic.atts;> + +<!ELEMENT tip (%body.elements;)+> +<!ATTLIST tip %basic.atts;> + +<!ELEMENT warning (%body.elements;)+> +<!ATTLIST warning %basic.atts;> + +<!ELEMENT admonition (title, (%body.elements;)+)> +<!ATTLIST admonition %basic.atts;> + +<!ELEMENT footnote (label?, (%body.elements;)+)> +<!ATTLIST footnote + %basic.atts; + %backrefs.att; + %auto.att;> + +<!ELEMENT citation (label, (%body.elements;)+)> +<!ATTLIST citation + %basic.atts; + %backrefs.att;> + +<!ELEMENT label (#PCDATA)> +<!ATTLIST label %basic.atts;> + +<!ELEMENT rubric %text.model;> +<!ATTLIST rubric %basic.atts;> + +<!-- Empty except when used as an inline element. --> +<!ELEMENT target %text.model;> +<!ATTLIST target + %basic.atts; + %reference.atts; + %anonymous.att;> + +<!ELEMENT substitution_definition %text.model;> +<!ATTLIST substitution_definition + %basic.atts; + ltrim %yesorno; #IMPLIED + rtrim %yesorno; #IMPLIED> + +<!ELEMENT comment (#PCDATA)> +<!ATTLIST comment + %basic.atts; + %fixedspace.att;> + +<!ELEMENT pending EMPTY> +<!ATTLIST pending %basic.atts;> + +<!ELEMENT figure (image, ((caption, legend?) | legend)) > +<!ATTLIST figure + %basic.atts; + %align-h.att; + width %number; #IMPLIED> + +<!-- Also an inline element. --> +<!ELEMENT image EMPTY> +<!ATTLIST image + %basic.atts; + %align-hv.att; + uri CDATA #REQUIRED + alt CDATA #IMPLIED + height %measure; #IMPLIED + width %measure; #IMPLIED + scale %number; #IMPLIED> + +<!ELEMENT caption %text.model;> +<!ATTLIST caption %basic.atts;> + +<!ELEMENT legend (%body.elements;)+> +<!ATTLIST legend %basic.atts;> + +<!-- +Table elements: table, tgroup, colspec, thead, tbody, row, entry. +--> +%calstblx; + +<!-- Used to record processing information. --> +<!ELEMENT system_message (%body.elements;)+> +<!ATTLIST system_message + %basic.atts; + %backrefs.att; + level %number; #IMPLIED + line %number; #IMPLIED + type NMTOKEN #IMPLIED> + +<!-- Used to pass raw data through the system. Also inline. --> +<!ELEMENT raw %text.model;> +<!ATTLIST raw + %basic.atts; + %fixedspace.att; + format NMTOKENS #IMPLIED> + +<!-- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Inline Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Inline elements occur within the text contents of body elements. Some +nesting of inline elements is allowed by these definitions, with the +following caveats: + +- An inline element may not contain a nested element of the same type + (e.g. <strong> may not contain another <strong>). +- Nested inline elements may or may not be supported by individual + applications using this DTD. +- The inline elements <footnote_reference>, <citation_reference>, + <literal>, and <image> do not support nesting. +--> + +<!ELEMENT emphasis %text.model;> +<!ATTLIST emphasis %basic.atts;> + +<!ELEMENT strong %text.model;> +<!ATTLIST strong %basic.atts;> + +<!ELEMENT literal (#PCDATA)> +<!ATTLIST literal %basic.atts;> + +<!-- Can also be a body element, when it contains an "image" element. --> +<!ELEMENT reference %text.model;> +<!ATTLIST reference + %basic.atts; + %reference.atts; + %anonymous.att;> + +<!ELEMENT footnote_reference (#PCDATA)> +<!ATTLIST footnote_reference + %basic.atts; + %refid.att; + %refname.att; + %auto.att;> + +<!ELEMENT citation_reference (#PCDATA)> +<!ATTLIST citation_reference + %basic.atts; + %refid.att; + %refname.att;> + +<!ELEMENT substitution_reference %text.model;> +<!ATTLIST substitution_reference + %basic.atts; + %refname.att;> + +<!ELEMENT title_reference %text.model;> +<!ATTLIST title_reference %basic.atts;> + +<!ELEMENT abbreviation %text.model;> +<!ATTLIST abbreviation %basic.atts;> + +<!ELEMENT acronym %text.model;> +<!ATTLIST acronym %basic.atts;> + +<!ELEMENT superscript %text.model;> +<!ATTLIST superscript %basic.atts;> + +<!ELEMENT subscript %text.model;> +<!ATTLIST subscript %basic.atts;> + +<!ELEMENT inline %text.model;> +<!ATTLIST inline %basic.atts;> + +<!ELEMENT problematic %text.model;> +<!ATTLIST problematic + %basic.atts; + %refid.att;> + +<!ELEMENT generated %text.model;> +<!ATTLIST generated %basic.atts;> + +<!-- +Local Variables: +mode: sgml +indent-tabs-mode: nil +fill-column: 70 +End: +--> diff --git a/docs/ref/rst/definitions.txt b/docs/ref/rst/definitions.txt new file mode 100644 index 000000000..78a2bf8da --- /dev/null +++ b/docs/ref/rst/definitions.txt @@ -0,0 +1,180 @@ +============================================ + 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/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt new file mode 100644 index 000000000..af88a3d4e --- /dev/null +++ b/docs/ref/rst/directives.txt @@ -0,0 +1,1727 @@ +============================= + 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/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt new file mode 100644 index 000000000..b7829816e --- /dev/null +++ b/docs/ref/rst/introduction.txt @@ -0,0 +1,314 @@ +===================================== + 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/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt new file mode 100644 index 000000000..1445619b3 --- /dev/null +++ b/docs/ref/rst/restructuredtext.txt @@ -0,0 +1,2879 @@ +======================================= + 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/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt new file mode 100644 index 000000000..3b8b114bc --- /dev/null +++ b/docs/ref/rst/roles.txt @@ -0,0 +1,318 @@ +========================================= + 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). diff --git a/docs/ref/soextblx.dtd b/docs/ref/soextblx.dtd new file mode 100644 index 000000000..56ba311ba --- /dev/null +++ b/docs/ref/soextblx.dtd @@ -0,0 +1,312 @@ +<!-- +=========================================================================== + OASIS XML Exchange Table Model Declaration Module +=========================================================================== +:Date: 1999-03-15 +--> + +<!-- This set of declarations defines the XML version of the Exchange + Table Model as of the date shown in the Formal Public Identifier + (FPI) for this entity. + + This set of declarations may be referred to using a public external + entity declaration and reference as shown in the following three + lines: + + <!ENTITY % calstblx + PUBLIC "-//OASIS//DTD XML Exchange Table Model 19990315//EN"> + %calstblx; + + If various parameter entities used within this set of declarations + are to be given non-default values, the appropriate declarations + should be given before calling in this package (i.e., before the + "%calstblx;" reference). +--> + +<!-- The motivation for this XML version of the Exchange Table Model + is simply to create an XML version of the SGML Exchange Table + Model. By design, no effort has been made to "improve" the model. + + This XML version incorporates the logical bare minimum changes + necessary to make the Exchange Table Model a valid XML DTD. +--> + +<!-- The XML version of the Exchange Table Model differs from + the SGML version in the following ways: + + The following parameter entities have been removed: + + - tbl.table.excep, tbl.hdft.excep, tbl.row.excep, tbl.entry.excep + There are no exceptions in XML. The following normative statement + is made in lieu of exceptions: the exchange table model explicitly + forbids a table from occurring within another table. If the + content model of an entry includes a table element, then this + cannot be enforced by the DTD, but it is a deviation from the + exchange table model to include a table within a table. + + - tbl.hdft.name, tbl.hdft.mdl, tbl.hdft.excep, tbl.hdft.att + The motivation for these elements was to change the table + header/footer elements. Since XML does not allow element declarations + to contain name groups, and the exchange table model does not + allow a table to contain footers, the continued presence of these + attributes seems unnecessary. + + The following parameter entity has been added: + + - tbl.thead.att + This entity parameterizes the attributes on thead. It replaces + the tbl.hdft.att parameter entity. + + Other miscellaneous changes: + + - Tag ommission indicators have been removed + - Comments have been removed from declarations + - NUMBER attributes have been changed to NMTOKEN + - NUTOKEN attributes have been to changed to NMTOKEN + - Removed the grouping characters around the content model + parameter entry for the 'entry' element. This is necessary + so that an entry can contain #PCDATA and be defined as an + optional, repeatable OR group beginning with #PCDATA. +--> + +<!-- This entity includes a set of element and attribute declarations + that partially defines the Exchange table model. However, the model + is not well-defined without the accompanying natural language + description of the semantics (meanings) of these various elements, + attributes, and attribute values. The semantic writeup, also available + from SGML Open, should be used in conjunction with this entity. +--> + +<!-- In order to use the Exchange table model, various parameter entity + declarations are required. A brief description is as follows: + + ENTITY NAME WHERE USED WHAT IT IS + + %yesorno In ATTLIST of: An attribute declared value + almost all elements for a "boolean" attribute + + %paracon In content model of: The "text" (logical content) + <entry> of the model group for <entry> + + %titles In content model of: The "title" part of the model + table element group for the table element + + %tbl.table.name In declaration of: The name of the "table" + table element element + + %tbl.table-titles.mdl In content model of: The model group for the title + table elements part of the content model for + table element + + %tbl.table.mdl In content model of: The model group for the content + table elements model for table element, + often (and by default) defined + in terms of %tbl.table-titles.mdl + and tgroup + + %tbl.table.att In ATTLIST of: Additional attributes on the + table element table element + + %bodyatt In ATTLIST of: Additional attributes on the + table element table element (for backward + compatibility with the SGML + model) + + %tbl.tgroup.mdl In content model of: The model group for the content + <tgroup> model for <tgroup> + + %tbl.tgroup.att In ATTLIST of: Additional attributes on the +4 <tgroup> <tgroup> element + + %tbl.thead.att In ATTLIST of: Additional attributes on the + <thead> <thead> element + + %tbl.tbody.att In ATTLIST of: Additional attributes on the + <tbody> <tbody> element + + %tbl.colspec.att In ATTLIST of: Additional attributes on the + <colspec> <colspec> element + + %tbl.row.mdl In content model of: The model group for the content + <row> model for <row> + + %tbl.row.att In ATTLIST of: Additional attributes on the + <row> <row> element + + %tbl.entry.mdl In content model of: The model group for the content + <entry> model for <entry> + + %tbl.entry.att In ATTLIST of: Additional attributes on the + <entry> <entry> element + + This set of declarations will use the default definitions shown below + for any of these parameter entities that are not declared before this + set of declarations is referenced. +--> + +<!-- These definitions are not directly related to the table model, but are + used in the default CALS table model and may be defined elsewhere (and + prior to the inclusion of this table module) in the referencing DTD. --> + +<!ENTITY % yesorno 'NMTOKEN'> <!-- no if zero(s), yes if any other value --> +<!ENTITY % titles 'title?'> +<!ENTITY % paracon '#PCDATA'> <!-- default for use in entry content --> + +<!-- +The parameter entities as defined below change and simplify the CALS table +model as published (as part of the Example DTD) in MIL-HDBK-28001. The +resulting simplified DTD has support from the SGML Open vendors and is +therefore more interoperable among different systems. + +These following declarations provide the Exchange default definitions +for these entities. However, these entities can be redefined (by giving +the appropriate parameter entity declaration(s) prior to the reference +to this Table Model declaration set entity) to fit the needs of the +current application. + +Note, however, that changes may have significant effect on the ability to +interchange table information. These changes may manifest themselves +in useability, presentation, and possible structure information degradation. +--> + +<!ENTITY % tbl.table.name "table"> +<!ENTITY % tbl.table-titles.mdl "%titles;,"> +<!ENTITY % tbl.table-main.mdl "tgroup+"> +<!ENTITY % tbl.table.mdl "%tbl.table-titles.mdl; %tbl.table-main.mdl;"> +<!ENTITY % tbl.table.att " + pgwide %yesorno; #IMPLIED "> +<!ENTITY % bodyatt ""> +<!ENTITY % tbl.tgroup.mdl "colspec*,thead?,tbody"> +<!ENTITY % tbl.tgroup.att ""> +<!ENTITY % tbl.thead.att ""> +<!ENTITY % tbl.tbody.att ""> +<!ENTITY % tbl.colspec.att ""> +<!ENTITY % tbl.row.mdl "entry+"> +<!ENTITY % tbl.row.att ""> +<!ENTITY % tbl.entry.mdl "(%paracon;)*"> +<!ENTITY % tbl.entry.att ""> + +<!-- ===== Element and attribute declarations follow. ===== --> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.table.name "table" + ENTITY % tbl.table-titles.mdl "%titles;," + ENTITY % tbl.table.mdl "%tbl.table-titles; tgroup+" + ENTITY % tbl.table.att " + pgwide %yesorno; #IMPLIED " +--> + +<!ELEMENT %tbl.table.name; (%tbl.table.mdl;)> + +<!ATTLIST %tbl.table.name; + frame (top|bottom|topbot|all|sides|none) #IMPLIED + colsep %yesorno; #IMPLIED + rowsep %yesorno; #IMPLIED + %tbl.table.att; + %bodyatt; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.tgroup.mdl "colspec*,thead?,tbody" + ENTITY % tbl.tgroup.att "" +--> + +<!ELEMENT tgroup (%tbl.tgroup.mdl;) > + +<!ATTLIST tgroup + cols NMTOKEN #REQUIRED + colsep %yesorno; #IMPLIED + rowsep %yesorno; #IMPLIED + align (left|right|center|justify|char) #IMPLIED + %tbl.tgroup.att; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.colspec.att "" +--> + +<!ELEMENT colspec EMPTY > + +<!ATTLIST colspec + colnum NMTOKEN #IMPLIED + colname NMTOKEN #IMPLIED + colwidth CDATA #IMPLIED + colsep %yesorno; #IMPLIED + rowsep %yesorno; #IMPLIED + align (left|right|center|justify|char) #IMPLIED + char CDATA #IMPLIED + charoff NMTOKEN #IMPLIED + %tbl.colspec.att; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.thead.att "" +--> + +<!ELEMENT thead (row+)> + +<!ATTLIST thead + valign (top|middle|bottom) #IMPLIED + %tbl.thead.att; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.tbody.att "" +--> + +<!ELEMENT tbody (row+)> + +<!ATTLIST tbody + valign (top|middle|bottom) #IMPLIED + %tbl.tbody.att; +> + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % tbl.row.mdl "entry+" + ENTITY % tbl.row.att "" +--> + +<!ELEMENT row (%tbl.row.mdl;)> + +<!ATTLIST row + rowsep %yesorno; #IMPLIED + valign (top|middle|bottom) #IMPLIED + %tbl.row.att; +> + + +<!-- + Default declarations previously defined in this entity and + referenced below include: + ENTITY % paracon "#PCDATA" + ENTITY % tbl.entry.mdl "(%paracon;)*" + ENTITY % tbl.entry.att "" +--> + +<!ELEMENT entry %tbl.entry.mdl;> + +<!ATTLIST entry + colname NMTOKEN #IMPLIED + namest NMTOKEN #IMPLIED + nameend NMTOKEN #IMPLIED + morerows NMTOKEN #IMPLIED + colsep %yesorno; #IMPLIED + rowsep %yesorno; #IMPLIED + align (left|right|center|justify|char) #IMPLIED + char CDATA #IMPLIED + charoff NMTOKEN #IMPLIED + valign (top|middle|bottom) #IMPLIED + %tbl.entry.att; +> diff --git a/docs/ref/transforms.txt b/docs/ref/transforms.txt new file mode 100644 index 000000000..54446f8dd --- /dev/null +++ b/docs/ref/transforms.txt @@ -0,0 +1,116 @@ +===================== + Docutils Transforms +===================== + +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ +:Copyright: This document has been placed in the public domain. + + +.. contents:: + + +For background about transforms and the Transformer object, see `PEP +258`_. + +.. _PEP 258: ../peps/pep-0258.html#transformer + + +Transforms Listed in Priority Order +=================================== + +============================== ============================ ======== +Transform: module.Class Added By Priority +============================== ============================ ======== +misc.class "class" (d/p) 210 + +references.Substitutions standalone (r), pep (r) 220 + +references.PropagateTargets standalone (r), pep (r) 260 + +frontmatter.DocTitle standalone (r) 320 + +frontmatter.DocInfo standalone (r) 340 + +frontmatter.SectSubTitle standalone (r) 350 + +peps.Headers pep (r) 360 + +peps.Contents pep (r) 380 + +references.AnonymousHyperlinks standalone (r), pep (r) 440 + +references.IndirectHyperlinks standalone (r), pep (r) 460 + +peps.TargetNotes pep (r) 520 + +references.TargetNotes peps.TargetNotes (t/p) 0 + +misc.CallBack peps.TargetNotes (t/p) 1 + +references.TargetNotes "target-notes" (d/p) 540 + +references.Footnotes standalone (r), pep (r) 620 + +references.ExternalTargets standalone (r), pep (r) 640 + +references.InternalTargets standalone (r), pep (r) 660 + +parts.SectNum "sectnum" (d/p) 710 + +parts.Contents "contents" (d/p), 720 + peps.Contents (t/p) + +universal.StripComments Reader (r) 740 + +peps.PEPZero peps.Headers (t/p) 760 + +components.Filter "meta" (d/p) 780 + +writer_aux.Compound newlatex2e (w) 810 + +universal.Decorations Reader (r) 820 + +misc.Transitions standalone (r), pep (r) 830 + +universal.ExposeInternals Reader (r) 840 + +references.DanglingReferences standalone (r), pep (r) 850 + +universal.Messages Writer (w) 860 + +universal.FilterMessages Writer (w) 870 + +universal.TestMessages DocutilsTestSupport 880 + +misc.CallBack n/a 990 +============================== ============================ ======== + +Key: + +* (r): Reader +* (w): Writer +* (d): Directive +* (t): Transform +* (/p): Via a "pending" node + + +Transform Priority Range Categories +=================================== + +==== ==== ================================================ + Priority +---------- ------------------------------------------------ +From To Category +==== ==== ================================================ + 0 99 immediate execution (added by another transform) + 100 199 very early (non-standard) + 200 299 very early + 300 399 early + 400 699 main + 700 799 late + 800 899 very late + 900 999 very late (non-standard) +==== ==== ================================================ |