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