diff options
Diffstat (limited to 'docutils/docs/ref/doctree.txt')
| -rw-r--r-- | docutils/docs/ref/doctree.txt | 4970 |
1 files changed, 0 insertions, 4970 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: |