diff options
Diffstat (limited to 'docs/ref/doctree.txt')
| -rw-r--r-- | docs/ref/doctree.txt | 4970 |
1 files changed, 4970 insertions, 0 deletions
diff --git a/docs/ref/doctree.txt b/docs/ref/doctree.txt new file mode 100644 index 000000000..25e5f9594 --- /dev/null +++ b/docs/ref/doctree.txt @@ -0,0 +1,4970 @@ +============================ + The Docutils Document Tree +============================ + +A Guide to the Docutils DTD +*************************** + +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ +:Copyright: This document has been placed in the public domain. + + +.. contents:: :depth: 1 + + +This document describes the XML data structure of Docutils_ documents: +the relationships and semantics of elements and attributes. The +Docutils document structure is formally defined by the `Docutils +Generic DTD`_ XML document type definition, docutils.dtd_, which is +the definitive source for details of element structural relationships. + +This document does not discuss implementation details. Those can be +found in internal documentation (docstrings) for the +``docutils.nodes`` module, where the document tree data structure is +implemented in a class library. + +The reader is assumed to have some familiarity with XML or SGML, and +an understanding of the data structure meaning of "tree". For a list +of introductory articles, see `Introducing the Extensible Markup +Language (XML)`_. + +The reStructuredText_ markup is used for illustrative examples +throughout this document. For a gentle introduction, see `A +ReStructuredText Primer`_. For complete technical details, see the +`reStructuredText Markup Specification`_. + + +.. _Docutils: http://docutils.sourceforge.net/ +.. _Docutils Generic DTD: +.. _Docutils DTD: +.. _docutils.dtd: docutils.dtd +.. _Introducing the Extensible Markup Language (XML): + http://xml.coverpages.org/xmlIntro.html +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _A ReStructuredText Primer: ../user/rst/quickstart.html +.. _reStructuredText Markup Specification: rst/restructuredtext.html + + +------------------- + Element Hierarchy +------------------- + +.. contents:: :local: + +Below is a simplified diagram of the hierarchy of elements in the +Docutils document tree structure. An element may contain any other +elements immediately below it in the diagram. Notes are written in +square brackets. Element types in parentheses indicate recursive or +one-to-many relationships; sections may contain (sub)sections, tables +contain further body elements, etc. :: + + +--------------------------------------------------------------------+ + | document [may begin with a title, subtitle, decoration, docinfo] | + | +--------------------------------------+ + | | sections [each begins with a title] | + +-----------------------------+-------------------------+------------+ + | [body elements:] | (sections) | + | | - literal | - lists | | - hyperlink +------------+ + | | blocks | - tables | | targets | + | para- | - doctest | - block | foot- | - sub. defs | + | graphs | blocks | quotes | notes | - comments | + +---------+-----------+----------+-------+--------------+ + | [text]+ | [text] | (body elements) | [text] | + | (inline +-----------+------------------+--------------+ + | markup) | + +---------+ + +The Docutils document model uses a simple, recursive model for section +structure. A document_ node may contain body elements and section_ +elements. Sections in turn may contain body elements and sections. +The level (depth) of a section element is determined from its physical +nesting level; unlike other document models (``<h1>`` in HTML_, +``<sect1>`` in DocBook_, ``<div1>`` in XMLSpec_) the level is not +incorporated into the element name. + +The Docutils document model uses strict element content models. Every +element has a unique structure and semantics, but elements may be +classified into general categories (below). Only elements which are +meant to directly contain text data have a mixed content model, where +text data and inline elements may be intermixed. This is unlike the +much looser HTML_ document model, where paragraphs and text data may +occur at the same level. + + +Structural Elements +=================== + +Structural elements may only contain child elements; they do not +directly contain text data. Structural elements may contain body +elements or further structural elements. Structural elements can only +be child elements of other structural elements. + +Category members: document_, section_, topic_, sidebar_ + + +Structural Subelements +---------------------- + +Structural subelements are child elements of structural elements. +Simple structuctural subelements (title_, subtitle_) contain text +data; the others are compound and do not directly contain text data. + +Category members: title_, subtitle_, decoration_, docinfo_, +transition_ + + +Bibliographic Elements +`````````````````````` + +The docinfo_ element is an optional child of document_. It groups +bibliographic elements together. All bibliographic elements except +authors_ and field_ contain text data. authors_ contains further +bibliographic elements (most notably author_). field_ contains +field_name_ and field_body_ body subelements. + +Category members: address_, author_, authors_, contact_, copyright_, +date_, field_, organization_, revision_, status_, version_ + + +Decorative Elements +``````````````````` + +The decoration_ element is also an optional child of document_. It +groups together elements used to generate page headers and footers. + +Category members: footer_, header_ + + +Body Elements +============= + +Body elements are contained within structural elements and compound +body elements. There are two subcategories of body elements: simple +and compound. + +Category members: admonition_, attention_, block_quote_, bullet_list_, +caution_, citation_, comment_, compound_, container_, danger_, +definition_list_, doctest_block_, enumerated_list_, error_, +field_list_, figure_, footnote_, hint_, image_, important_, +line_block_, literal_block_, note_, option_list_, paragraph_, +pending_, raw_, rubric_, substitution_definition_, system_message_, +table_, target_, tip_, warning_ + + +Simple Body Elements +-------------------- + +Simple body elements are empty or directly contain text data. Those +that contain text data may also contain inline elements. Such +elements therefore have a "mixed content model". + +Category members: comment_, doctest_block_, image_, literal_block_, +paragraph_, pending_, raw_, rubric_, substitution_definition_, target_ + + +Compound Body Elements +---------------------- + +Compound body elements contain local substructure (body subelements) +and further body elements. They do not directly contain text data. + +Category members: admonition_, attention_, block_quote_, bullet_list_, +caution_, citation_, compound_, container_, danger_, definition_list_, +enumerated_list_, error_, field_list_, figure_, footnote_, hint_, +important_, line_block, note_, option_list_, system_message_, table_, +tip_, warning_ + + +Body Subelements +```````````````` + +Compound body elements contain specific subelements (e.g. bullet_list_ +contains list_item_). Subelements may themselves be compound elements +(containing further child elements, like field_) or simple data +elements (containing text data, like field_name_). These subelements +always occur within specific parent elements, never at the body +element level (beside paragraphs, etc.). + +Category members (simple): attribution_, caption_, classifier_, +colspec_, field_name_, label_, line_, option_argument_, +option_string_, term_ + +Category members (compound): definition_, definition_list_item_, +description_, entry_, field_, field_body_, legend_, list_item_, +option_, option_group_, option_list_item_, row_, tbody_, tgroup_, +thead_ + + +Inline Elements +=============== + +Inline elements directly contain text data, and may also contain +further inline elements. Inline elements are contained within simple +body elements. Most inline elements have a "mixed content model". + +Category members: abbreviation_, acronym_, citation_reference_, +emphasis_, footnote_reference_, generated_, image_, inline_, literal_, +problematic_, reference_, strong_, subscript_, +substitution_reference_, superscript_, target_, title_reference_, raw_ + + +.. _HTML: http://www.w3.org/MarkUp/ +.. _DocBook: http://docbook.org/tdg/en/html/docbook.html +.. _XMLSpec: http://www.w3.org/XML/1998/06/xmlspec-report.htm + + +------------------- + Element Reference +------------------- + +.. contents:: :local: + :depth: 1 + +Each element in the DTD (document type definition) is described in its +own section below. Each section contains an introduction plus the +following subsections: + +* Details (of element relationships and semantics): + + - Category: One or more references to the element categories in + `Element Hierarchy`_ above. Some elements belong to more than one + category. + + - Parents: A list of elements which may contain the element. + + - Children: A list of elements which may occur within the element. + + - Analogues: Describes analogous elements in well-known document + models such as HTML_ or DocBook_. Lists similarities and + differences. + + - Processing: Lists formatting or rendering recommendations for the + element. + +* Content Model: + + The formal XML content model from the `Docutils DTD`_, followed by: + + - Attributes: Describes (or refers to descriptions of) the possible + values and semantics of each attribute. + + - Parameter Entities: Lists the parameter entities which directly or + indirectly include the element. + +* Examples: reStructuredText_ examples are shown along with + fragments of the document trees resulting from parsing. + _`Pseudo-XML` is used for the results of parsing and processing. + Pseudo-XML is a representation of XML where nesting is indicated by + indentation and end-tags are not shown. Some of the precision of + real XML is given up in exchange for easier readability. For + example, the following are equivalent: + + - Real XML:: + + <document> + <section ids="a-title" names="a title"> + <title>A Title</title> + <paragraph>A paragraph.</paragraph> + </section> + </document> + + - Pseudo-XML:: + + <document> + <section ids="a-title" names="a title"> + <title> + A Title + <paragraph> + A paragraph. + +-------------------- + +Many of the element reference sections below are marked "_`to be +completed`". Please help complete this document by contributing to +its writing. + + +``abbreviation`` +================ + +`To be completed`_. + + +``acronym`` +=========== + +`To be completed`_. + + +``address`` +=========== + +The ``address`` element holds the surface mailing address information +for the author (individual or group) of the document, or a third-party +contact address. Its structure is identical to that of the +literal_block_ element: whitespace is significant, especially +newlines. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + The following elements may contain ``address``: docinfo_, authors_ + +:Children: + ``address`` elements contain text data plus `inline elements`_. + +:Analogues: + ``address`` is analogous to the DocBook "address" element. + +:Processing: + As with the literal_block_ element, newlines and other whitespace + is significant and must be preserved. However, a monospaced + typeface need not be used. + + See also docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``address`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus `xml:space`_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``address``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Address: 123 Example Ave. + Example, EX + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <address> + 123 Example Ave. + Example, EX + +See docinfo_ for a more complete example, including processing +context. + + +``admonition`` +============== + +This element is a generic, titled admonition. Also see the specific +admonition elements Docutils offers (in alphabetical order): caution_, +danger_, error_, hint_, important_, note_, tip_, warning_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``admonition``. + +:Children: + ``admonition`` elements begin with a title_ and may contain one or + more `body elements`_. + +:Analogues: + ``admonition`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.). + + +Content Model +------------- + +.. parsed-literal:: + + (title_, (`%body.elements;`_)+) + +:Attributes: + The ``admonition`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``admonition``. The `%structure.model;`_ parameter entity + indirectly includes ``admonition``. + + +Examples +-------- + +reStructuredText source:: + + .. admonition:: And, by the way... + + You can make up your own admonition too. + +Pseudo-XML_ fragment from simple parsing:: + + <admonition class="admonition-and-by-the-way"> + <title> + And, by the way... + <paragraph> + You can make up your own admonition too. + + +``attention`` +============= + +The ``attention`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): caution_, danger_, error_, +hint_, important_, note_, tip_, warning_, and the generic admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``attention``. + +:Children: + ``attention`` elements contain one or more `body elements`_. + +:Analogues: + ``attention`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Attention!" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``attention`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``attention``. The `%structure.model;`_ parameter entity + indirectly includes ``attention``. + + +Examples +-------- + +reStructuredText source:: + + .. Attention:: All your base are belong to us. + +Pseudo-XML_ fragment from simple parsing:: + + <attention> + <paragraph> + All your base are belong to us. + + +``attribution`` +=============== + +`To be completed`_. + + +``author`` +========== + +The ``author`` element holds the name of the author of the document. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + The following elements may contain ``author``: docinfo_, authors_ + +:Children: + ``author`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``author`` is analogous to the DocBook "author" element. + +:Processing: + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``author`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``author``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Author: J. Random Hacker + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <author> + J. Random Hacker + +See docinfo_ for a more complete example, including processing +context. + + +``authors`` +=========== + +The ``authors`` element is a container for author information for +documents with multiple authors. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + Only the docinfo_ element contains ``authors``. + +:Children: + ``authors`` elements may contain the following elements: author_, + organization_, address_, contact_ + +:Analogues: + ``authors`` is analogous to the DocBook "authors" element. + +:Processing: + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + ((author_, organization_?, address_?, contact_?)+) + +:Attributes: + The ``authors`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``authors``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Authors: J. Random Hacker; Jane Doe + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <authors> + <author> + J. Random Hacker + <author> + Jane Doe + +In reStructuredText, multiple author's names are separated with +semicolons (";") or commas (","); semicolons take precedence. There +is currently no way to represent the author's organization, address, +or contact in a reStructuredText "Authors" field. + +See docinfo_ for a more complete example, including processing +context. + + +``block_quote`` +=============== + +The ``block_quote`` element is used for quotations set off from the +main text (standalone). + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``block_quote``. + +:Children: + ``block_quote`` elements contain `body elements`_ followed by an + optional attribution_ element. + +:Analogues: + ``block_quote`` is analogous to the "blockquote" element in both + HTML and DocBook. + +:Processing: + ``block_quote`` elements serve to set their contents off from the + main text, typically with indentation and/or other decoration. + + +Content Model +------------- + +.. parsed-literal:: + + ((`%body.elements;`_)+, attribution_?) + +:Attributes: + The ``block_quote`` element contains only the `common + attributes`_: ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``block_quote``. The `%structure.model;`_ parameter entity + indirectly includes ``block_quote``. + + +Examples +-------- + +reStructuredText source:: + + As a great paleontologist once said, + + This theory, that is mine, is mine. + + -- Anne Elk (Miss) + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + As a great paleontologist once said, + <block_quote> + <paragraph> + This theory, that is mine, is mine. + <attribution> + Anne Elk (Miss) + + +``bullet_list`` +=============== + +The ``bullet_list`` element contains list_item_ elements which are +uniformly marked with bullets. Bullets are typically simple dingbats +(symbols) such as circles and squares. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``bullet_list``. + +:Children: + ``bullet_list`` elements contain one or more list_item_ elements. + +:Analogues: + ``bullet_list`` is analogous to the HTML "ul" element and to the + DocBook "itemizedlist" element. HTML's "ul" is short for + "unordered list", which we consider to be a misnomer. "Unordered" + implies that the list items may be randomly rearranged without + affecting the meaning of the list. Bullet lists *are* often + ordered; the ordering is simply left implicit. + +:Processing: + Each list item should begin a new vertical block, prefaced by a + bullet/dingbat. + + +Content Model +------------- + +.. parsed-literal:: + + (list_item_ +) + +:Attributes: + The ``bullet_list`` element contains the `common attributes`_ + (ids_, names_, dupnames_, source_, and classes_), plus bullet_. + + ``bullet`` is used to record the style of bullet from the input + data. In documents processed from reStructuredText_, it contains + one of "-", "+", or "*". It may be ignored in processing. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``bullet_list``. The `%structure.model;`_ parameter entity + indirectly includes ``bullet_list``. + + +Examples +-------- + +reStructuredText_ source:: + + - Item 1, paragraph 1. + + Item 1, paragraph 2. + + - Item 2. + +Pseudo-XML_ fragment from simple parsing:: + + <bullet_list bullet="-"> + <list_item> + <paragraph> + Item 1, paragraph 1. + <paragraph> + Item 1, paragraph 2. + <list_item> + <paragraph> + Item 2. + +See list_item_ for another example. + + +``caption`` +=========== + +`To be completed`_. + + +``caution`` +=========== + +The ``caution`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, danger_, error_, +hint_, important_, note_, tip_, warning_, and the generic admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``caution``. + +:Children: + ``caution`` elements contain one or more `body elements`_. + +:Analogues: + ``caution`` is analogous to the DocBook "caution" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Caution" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``caution`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``caution``. The `%structure.model;`_ parameter entity + indirectly includes ``caution``. + + +Examples +-------- + +reStructuredText source:: + + .. Caution:: Don't take any wooden nickels. + +Pseudo-XML_ fragment from simple parsing:: + + <caution> + <paragraph> + Don't take any wooden nickels. + + +``citation`` +============ + +`To be completed`_. + + +``citation_reference`` +====================== + +`To be completed`_. + + +``classifier`` +============== + +The ``classifier`` element contains the classification or type of the +term_ being defined in a definition_list_. For example, it can be +used to indicate the type of a variable. + + +Details +------- + +:Category: + `Body Subelements`_ (simple) + +:Parents: + Only the definition_list_item_ element contains ``classifier``. + +:Children: + ``classifier`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``classifier`` has no direct analogues in common DTDs. It can be + emulated with primitives or type effects. + +:Processing: + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``classifier`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +Here is a hypothetical data dictionary. reStructuredText_ source:: + + name : string + Customer name. + i : int + Temporary index variable. + +Pseudo-XML_ fragment from simple parsing:: + + <definition_list> + <definition_list_item> + <term> + name + <classifier> + string + <definition> + <paragraph> + Customer name. + <definition_list_item> + <term> + i + <classifier> + int + <definition> + <paragraph> + Temporary index variable. + + +``colspec`` +=========== + +`To be completed`_. + + +``comment`` +=========== + +`To be completed`_. + + +``compound`` +============ + +`To be completed`_. + + +``contact`` +=========== + +The ``contact`` element holds contact information for the author +(individual or group) of the document, or a third-party contact. It +is typically used for an email or web address. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + The following elements may contain ``contact``: docinfo_, authors_ + +:Children: + ``contact`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``contact`` is analogous to the DocBook "email" element. The HTML + "address" element serves a similar purpose. + +:Processing: + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``contact`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``contact``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Contact: jrh@example.com + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <contact> + <reference refuri="mailto:jrh@example.com"> + jrh@example.com + +See docinfo_ for a more complete example, including processing +context. + + +``container`` +============= + +`To be completed`_. + + +``copyright`` +============= + +The ``copyright`` element contains the document's copyright statement. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + Only the docinfo_ element contains ``copyright``. + +:Children: + ``copyright`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``copyright`` is analogous to the DocBook "copyright" element. + +:Processing: + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``copyright`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``copyright``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Copyright: This document has been placed in the public domain. + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <copyright> + This document has been placed in the public domain. + +See docinfo_ for a more complete example, including processing +context. + + +``danger`` +========== + +The ``danger`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, error_, +hint_, important_, note_, tip_, warning_, and the generic admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``danger``. + +:Children: + ``danger`` elements contain one or more `body elements`_. + +:Analogues: + ``danger`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "!DANGER!" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``danger`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``danger``. The `%structure.model;`_ parameter entity + indirectly includes ``danger``. + + +Examples +-------- + +reStructuredText source:: + + .. DANGER:: Mad scientist at work! + +Pseudo-XML_ fragment from simple parsing:: + + <danger> + <paragraph> + Mad scientist at work! + + +``date`` +======== + +The ``date`` element contains the date of publication, release, or +last modification of the document. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + Only the docinfo_ element contains ``date``. + +:Children: + ``date`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``date`` is analogous to the DocBook "date" element. + +:Processing: + Often used with the RCS/CVS keyword "Date". See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``date`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``date``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Date: 2002-08-20 + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <date> + 2002-08-20 + +See docinfo_ for a more complete example, including processing +context. + + +``decoration`` +============== + +The ``decoration`` element is a container for header_ and footer_ +elements and potential future extensions. These elements are used for +notes, time/datestamp, processing information, etc. + + +Details +------- + +:Category: + `Structural Subelements`_ + +:Parents: + Only the document_ element contains ``decoration``. + +:Children: + ``decoration`` elements may contain `decorative elements`_. + +:Analogues: + There are no direct analogies to ``decoration`` in HTML or in + DocBook. Equivalents are typically constructed from primitives + and/or generated by the processing system. + +:Processing: + See the individual `decorative elements`_. + + +Content Model +------------- + +.. parsed-literal:: + + (header_?, footer_?) + +Although the content model doesn't specifically require contents, no +empty ``decoration`` elements are ever created. + +:Attributes: + The ``decoration`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +reStructuredText_ source:: + + A paragraph. + +Complete pseudo-XML_ result after parsing and applying transforms, +assuming that the datestamp command-line option or configuration +setting has been supplied:: + + <document> + <decoration> + <footer> + <paragraph> + Generated on: 2002-08-20. + <paragraph> + A paragraph. + + +``definition`` +============== + +The ``definition`` element is a container for the body elements used +to define a term_ in a definition_list_. + + +Details +------- + +:Category: + `Body Subelements`_ (compound) + +:Parents: + Only definition_list_item_ elements contain ``definition``. + +:Children: + ``definition`` elements may contain `body elements`_. + +:Analogues: + ``definition`` is analogous to the HTML "dd" element and to the + DocBook "listitem" element (inside a "variablelistentry" element). + +:Processing: + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``definition`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the definition_list_, definition_list_item_, and +classifier_ elements. + + +``definition_list`` +=================== + +The ``definition_list`` element contains a list of terms and their +definitions. It can be used for glossaries or dictionaries, to +describe or classify things, for dialogues, or to itemize subtopics +(such as in this reference). + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``definition_list``. + +:Children: + ``definition_list`` elements contain one or more + definition_list_item_ elements. + +:Analogues: + ``definition_list`` is analogous to the HTML "dl" element and to + the DocBook "variablelist" element. + +:Processing: + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + (definition_list_item_ +) + +:Attributes: + The ``definition_list`` element contains only the `common + attributes`_: ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``definition_list``. The `%structure.model;`_ parameter entity + indirectly includes ``definition_list``. + + +Examples +-------- + +reStructuredText_ source:: + + Term + Definition. + + Term : classifier + The ' : ' indicates a classifier in + definition list item terms only. + +Pseudo-XML_ fragment from simple parsing:: + + <definition_list> + <definition_list_item> + <term> + Term + <definition> + <paragraph> + Definition. + <definition_list_item> + <term> + Term + <classifier> + classifier + <definition> + <paragraph> + The ' : ' indicates a classifier in + definition list item terms only. + +See definition_list_item_ and classifier_ for further examples. + + +``definition_list_item`` +======================== + +The ``definition_list_item`` element contains a single +term_/definition_ pair (with optional classifier_). + + +Details +------- + +:Category: + `Body Subelements`_ (compound) + +:Parents: + Only the definition_list_ element contains + ``definition_list_item``. + +:Children: + ``definition_list_item`` elements each contain a single term_, + an optional classifier_, and a definition_. + +:Analogues: + ``definition_list_item`` is analogous to the DocBook + "variablelistentry" element. + +:Processing: + The optional classifier_ can be rendered differently from the + term_. They should be separated visually, typically by spaces + plus a colon or dash. + + +Content Model +------------- + +.. parsed-literal:: + + (term_, classifier_?, definition_) + +:Attributes: + The ``definition_list_item`` element contains only the `common + attributes`_: ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +reStructuredText_ source:: + + Tyrannosaurus Rex : carnivore + Big and scary; the "Tyrant King". + + Brontosaurus : herbivore + All brontosauruses are thin at one end, + much much thicker in the middle + and then thin again at the far end. + + -- Anne Elk (Miss) + +Pseudo-XML_ fragment from simple parsing:: + + <definition_list> + <definition_list_item> + <term> + Tyrannosaurus Rex + <classifier> + carnivore + <definition> + <paragraph> + Big and scary; the "Tyrant King". + <definition_list_item> + <term> + Brontosaurus + <classifier> + herbivore + <definition> + <paragraph> + All brontosauruses are thin at one end, + much much thicker in the middle + and then thin again at the far end. + <paragraph> + -- Anne Elk (Miss) + +See definition_list_ and classifier_ for further examples. + + +``description`` +=============== + +The ``description`` element contains body elements, describing the +purpose or effect of a command-line option or group of options. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_list_item_ element contains ``description``. + +:Children: + ``description`` elements may contain `body elements`_. + +:Analogues: + ``description`` has no direct analogues in common DTDs. + +:Processing: + See option_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``description`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the option_list_ element. + + +``docinfo`` +=========== + +The ``docinfo`` element is a container for document bibliographic +data, or meta-data (data about the document). It corresponds to the +front matter of a book, such as the title page and copyright page. + + +Details +------- + +:Category: + `Structural Subelements`_ + +:Parents: + Only the document_ element contains ``docinfo``. + +:Children: + ``docinfo`` elements contain `bibliographic elements`_. + +:Analogues: + ``docinfo`` is analogous to DocBook "info" elements ("bookinfo" + etc.). There are no directly analogous HTML elements; the "meta" + element carries some of the same information, albeit invisibly. + +:Processing: + The ``docinfo`` element may be rendered as a two-column table or + in other styles. It may even be invisible or omitted from the + processed output. Meta-data may be extracted from ``docinfo`` + children; for example, HTML ``<meta>`` tags may be constructed. + + When Docutils_ transforms a reStructuredText_ field_list_ into a + ``docinfo`` element (see the examples below), RCS/CVS keywords are + normally stripped from simple (one paragraph) field bodies. For + complete details, please see `RCS Keywords`_ in the + `reStructuredText Markup Specification`_. + + .. _RCS Keywords: rst/restructuredtext.html#rcs-keywords + + +Content Model +------------- + +.. parsed-literal:: + + (`%bibliographic.elements;`_)+ + +:Attributes: + The ``docinfo`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +Docinfo is represented in reStructuredText_ by a field_list_ in a +bibliographic context: the first non-comment element of a document_, +after any document title_/subtitle_. The field list is transformed +into a ``docinfo`` element and its children by a transform. Source:: + + Docinfo Example + =============== + + :Author: J. Random Hacker + :Contact: jrh@example.com + :Date: 2002-08-18 + :Status: Work In Progress + :Version: 1 + :Filename: $RCSfile$ + :Copyright: This document has been placed in the public domain. + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="docinfo-example" names="docinfo example"> + <title> + Docinfo Example + <docinfo> + <author> + J. Random Hacker + <contact> + <reference refuri="mailto:jrh@example.com"> + jrh@example.com + <date> + 2002-08-18 + <status> + Work In Progress + <version> + 1 + <field> + <field_name> + Filename + <field_body> + <paragraph> + doctree.txt + <copyright> + This document has been placed in the public domain. + +Note that "Filename" is a non-standard ``docinfo`` field, so becomes a +generic ``field`` element. Also note that the "RCSfile" keyword +syntax has been stripped from the "Filename" data. + +See field_list_ for an example in a non-bibliographic context. Also +see the individual examples for the various `bibliographic elements`_. + + +``doctest_block`` +================= + +The ``doctest_block`` element is a Python-specific variant of +literal_block_. It is a block of text where line breaks and +whitespace are significant and must be preserved. ``doctest_block`` +elements are used for interactive Python interpreter sessions, which +are distinguished by their input prompt: ``>>>``. They are meant to +illustrate usage by example, and provide an elegant and powerful +testing environment via the `doctest module`_ in the Python standard +library. + +.. _doctest module: + http://www.python.org/doc/current/lib/module-doctest.html + + +Details +------- + +:Category: + `Simple Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``doctest_block``. + +:Children: + ``doctest_block`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``doctest_block`` is analogous to the HTML "pre" element and to + the DocBook "programlisting" and "screen" elements. + +:Processing: + As with literal_block_, ``doctest_block`` elements are typically + rendered in a monospaced typeface. It is crucial that all + whitespace and line breaks are preserved in the rendered form. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``doctest_block`` element contains the `common attributes`_ + (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``doctest_block``. The `%structure.model;`_ parameter entity + indirectly includes ``doctest_block``. + + +Examples +-------- + +reStructuredText source:: + + This is an ordinary paragraph. + + >>> print 'this is a Doctest block' + this is a Doctest block + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + This is an ordinary paragraph. + <doctest_block xml:space="preserve"> + >>> print 'this is a Doctest block' + this is a Doctest block + + +``document`` +============ + +The ``document`` element is the root (topmost) element of the Docutils +document tree. ``document`` is the direct or indirect ancestor of +every other element in the tree. It encloses the entire document +tree. It is the starting point for a document. + + +Details +------- + +:Category: + `Structural Elements`_ + +:Parents: + The ``document`` element has no parents. + +:Children: + ``document`` elements may contain `structural subelements`_, + `structural elements`_, and `body elements`_. + +:Analogues: + ``document`` is analogous to the HTML "html" element and to + several DocBook elements such as "book". + + +Content Model +------------- + +.. parsed-literal:: + + ( (title_, subtitle_?)?, + decoration_?, + (docinfo_, transition_?)?, + `%structure.model;`_ ) + +Depending on the source of the data and the stage of processing, the +"document" may not initially contain a "title". A document title is +not directly representable in reStructuredText_. Instead, a lone +top-level section may have its title promoted to become the document +title_, and similarly for a lone second-level (sub)section's title to +become the document subtitle_. + +The contents of "decoration_" may be specified in a document, +constructed programmatically, or both. The "docinfo_" may be +transformed from an initial field_list_. + +See the `%structure.model;`_ parameter entity for details of the body +of a ``document``. + +:Attributes: + The ``document`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus an optional title__ + attribute which stores the document title metadata. + + __ `title (attribute)`_ + + +Examples +-------- + +reStructuredText_ source:: + + A Title + ======= + + A paragraph. + +Complete pseudo-XML_ result from simple parsing:: + + <document> + <section ids="a-title" names="a title"> + <title> + A Title + <paragraph> + A paragraph. + +After applying transforms, the section title is promoted to become the +document title:: + + <document ids="a-title" names="a title"> + <title> + A Title + <paragraph> + A paragraph. + + +``emphasis`` +============ + +`To be completed`_. + + +``entry`` +========= + +`To be completed`_. + + +``enumerated_list`` +=================== + +The ``enumerated_list`` element contains list_item_ elements which are +uniformly marked with enumerator labels. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``enumerated_list``. + +:Children: + ``enumerated_list`` elements contain one or more list_item_ + elements. + +:Analogues: + ``enumerated_list`` is analogous to the HTML "ol" element and to + the DocBook "orderedlist" element. + +:Processing: + Each list item should begin a new vertical block, prefaced by a + enumeration marker (such as "1."). + + +Content Model +------------- + +.. parsed-literal:: + + (list_item_ +) + +:Attributes: + The ``enumerated_list`` element contains the `common attributes`_ + (ids_, names_, dupnames_, source_, and classes_), plus enumtype_, + prefix_, suffix_, and start_. + + ``enumtype`` is used to record the intended enumeration sequence, + one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z), + "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ..., + mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ..., + MMMMCMXCIX [4999]). + + ``prefix`` stores the formatting characters used before the + enumerator. In documents originating from reStructuredText_ data, + it will contain either "" (empty string) or "(" (left + parenthesis). It may or may not affect processing. + + ``suffix`` stores the formatting characters used after the + enumerator. In documents originating from reStructuredText_ data, + it will contain either "." (period) or ")" (right parenthesis). + Depending on the capabilities of the output format, this attribute + may or may not affect processing. + + ``start`` contains the ordinal value of the first item in the + list, in decimal. For lists beginning at value 1 ("1", "a", "A", + "i", or "I"), this attribute may be omitted. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``enumerated_list``. The `%structure.model;`_ parameter entity + indirectly includes ``enumerated_list``. + + +Examples +-------- + +reStructuredText_ source:: + + 1. Item 1. + + (A) Item A. + (B) Item B. + (C) Item C. + + 2. Item 2. + +Pseudo-XML_ fragment from simple parsing:: + + <enumerated_list enumtype="arabic" prefix="" suffix="."> + <list_item> + <paragraph> + Item 1. + <enumerated_list enumtype="upperalpha" prefix="(" suffix=")"> + <list_item> + <paragraph> + Item A. + <list_item> + <paragraph> + Item B. + <list_item> + <paragraph> + Item C. + <list_item> + <paragraph> + Item 2. + +See list_item_ for another example. + + +``error`` +========= + +The ``error`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, hint_, important_, note_, tip_, warning_, and the generic +admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``error``. + +:Children: + ``error`` elements contain one or more `body elements`_. + +:Analogues: + ``error`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Error" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``error`` element contains only the `common attributes`_: ids_, + names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``error``. The `%structure.model;`_ parameter entity indirectly + includes ``error``. + + +Examples +-------- + +reStructuredText source:: + + .. Error:: Does not compute. + +Pseudo-XML_ fragment from simple parsing:: + + <error> + <paragraph> + Does not compute. + + +``field`` +========= + +The ``field`` element contains a pair of field_name_ and field_body_ +elements. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + The following elements may contain ``field``: docinfo_, + field_list_ + +:Children: + Each ``field`` element contains one field_name_ and one + field_body_ element. + +:Analogues: + ``field`` has no direct analogues in common DTDs. + +:Processing: + See field_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (field_name_, field_body_) + +:Attributes: + The ``field`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``field``. + + +Examples +-------- + +See the examples for the field_list_ and docinfo_ elements. + + +``field_body`` +============== + +The ``field_body`` element contains body elements. It is analogous to +a database field's data. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the field_ element contains ``field_body``. + +:Children: + ``field_body`` elements may contain `body elements`_. + +:Analogues: + ``field_body`` has no direct analogues in common DTDs. + +:Processing: + See field_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)* + +:Attributes: + The ``field_body`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the field_list_ and docinfo_ elements. + + +``field_list`` +============== + +The ``field_list`` element contains two-column table-like structures +resembling database records (label & data pairs). Field lists are +often meant for further processing. In reStructuredText_, field lists +are used to represent bibliographic fields (contents of the docinfo_ +element) and directive options. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``field_list``. + +:Children: + ``field_list`` elements contain one or more field_ elements. + +:Analogues: + ``field_list`` has no direct analogues in common DTDs. It can be + emulated with primitives such as tables. + +:Processing: + A ``field_list`` is typically rendered as a two-column list, where + the first column contains "labels" (usually with a colon suffix). + However, field lists are often used for extension syntax or + special processing. Such structures do not survive as field lists + to be rendered. + + +Content Model +------------- + +.. parsed-literal:: + + (field_ +) + +:Attributes: + The ``field_list`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``field_list``. The `%structure.model;`_ parameter entity + indirectly includes ``field_list``. + + +Examples +-------- + +reStructuredText_ source:: + + :Author: Me + :Version: 1 + :Date: 2001-08-11 + :Parameter i: integer + +Pseudo-XML_ fragment from simple parsing:: + + <field_list> + <field> + <field_name> + Author + <field_body> + <paragraph> + Me + <field> + <field_name> + Version + <field_body> + <paragraph> + 1 + <field> + <field_name> + Date + <field_body> + <paragraph> + 2001-08-11 + <field> + <field_name> + Parameter i + <field_body> + <paragraph> + integer + + +``field_name`` +============== + +The ``field_name`` element contains text; it is analogous to a +database field's name. + + +Details +------- + +:Category: + `Body Subelements`_ (simple) + +:Parents: + Only the field_ element contains ``field_name``. + +:Children: + ``field_name`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``field_name`` has no direct analogues in common DTDs. + +:Processing: + See field_list_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``field_name`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the field_list_ and docinfo_ elements. + + +``figure`` +========== + +`To be completed`_. + + +``footer`` +========== + +The ``footer`` element is a container element whose contents are meant +to appear at the bottom of a web page, or repeated at the bottom of +every printed page. The ``footer`` element may contain processing +information (datestamp, a link to Docutils_, etc.) as well as custom +content. + + +Details +------- + +:Category: + `Decorative Elements`_ + +:Parents: + Only the decoration_ element contains ``footer``. + +:Children: + ``footer`` elements may contain `body elements`_. + +:Analogues: + There are no direct analogies to ``footer`` in HTML or DocBook. + Equivalents are typically constructed from primitives and/or + generated by the processing system. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``footer`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +reStructuredText_ source:: + + A paragraph. + +Complete pseudo-XML_ result after parsing and applying transforms, +assuming that the datestamp command-line option or configuration +setting has been supplied:: + + <document> + <decoration> + <footer> + <paragraph> + Generated on: 2002-08-20. + <paragraph> + A paragraph. + + +``footnote`` +============ + +`To be completed`_. + + +``footnote_reference`` +====================== + +`To be completed`_. + + +``generated`` +============= + +Docutils wraps ``generated`` elements around text that is inserted +(generated) by Docutils; i.e., text that was not in the document, like +section numbers inserted by the "sectnum" directive. + +`To be completed`_. + + +``header`` +========== + +The ``header`` element is a container element whose contents are meant +to appear at the top of a web page, or at the top of every printed +page. + + +Details +------- + +:Category: + `Decorative Elements`_ + +:Parents: + Only the decoration_ element contains ``header``. + +:Children: + ``header`` elements may contain `body elements`_. + +:Analogues: + There are no direct analogies to ``header`` in HTML or DocBook. + Equivalents are typically constructed from primitives and/or + generated by the processing system. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``header`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +reStructuredText source fragment:: + + .. header:: This space for rent. + +Pseudo-XML_ fragment from simple parsing:: + + <document> + <decoration> + <header> + <paragraph> + This space for rent. + + +``hint`` +======== + +The ``hint`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, important_, note_, tip_, warning_, and the generic +admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``hint``. + +:Children: + ``hint`` elements contain one or more `body elements`_. + +:Analogues: + ``hint`` has no direct analogues in common DTDs. It can be + emulated with primitives and type effects. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Hint" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``hint`` element contains only the `common attributes`_: ids_, + names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``hint``. The `%structure.model;`_ parameter entity indirectly + includes ``hint``. + + +Examples +-------- + +reStructuredText source:: + + .. Hint:: It's bigger than a bread box. + +Pseudo-XML_ fragment from simple parsing:: + + <hint> + <paragraph> + It's bigger than a bread box. + + +``image`` +========= + +`To be completed`_. + + +``important`` +============= + +The ``important`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, hint_, note_, tip_, warning_, and the generic +admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``important``. + +:Children: + ``important`` elements contain one or more `body elements`_. + +:Analogues: + ``important`` is analogous to the DocBook "important" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Important" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``important`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``important``. The `%structure.model;`_ parameter entity + indirectly includes ``important``. + + +Examples +-------- + +reStructuredText source:: + + .. Important:: + + * Wash behind your ears. + * Clean up your room. + * Back up your data. + * Call your mother. + +Pseudo-XML_ fragment from simple parsing:: + + <important> + <bullet_list> + <list_item> + <paragraph> + Wash behind your ears. + <list_item> + <paragraph> + Clean up your room. + <list_item> + <paragraph> + Back up your data. + <list_item> + <paragraph> + Call your mother. + + +``inline`` +========== + +`To be completed`_. + + +``label`` +========= + +`To be completed`_. + + +``legend`` +========== + +`To be completed`_. + + +``line`` +======== + +The ``line`` element contains a single line of text, part of a +`line_block`_. + + +Details +------- + +:Category: + `Body Subelements`_ (simple) + +:Parents: + Only the `line_block`_ element contains ``line``. + +:Children: + ``line`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``line`` has no direct analogues in common DTDs. It can be + emulated with primitives or type effects. + +:Processing: + See `line_block`_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``line`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus `xml:space`_. + + +Examples +-------- + +See `line_block`_. + + +``line_block`` +============== + +The ``line_block`` element contains a sequence of lines and nested +line blocks. Line breaks (implied between elements) and leading +whitespace (indicated by nesting) is significant and must be +preserved. ``line_block`` elements are commonly used for verse and +addresses. See `literal_block`_ for an alternative useful for program +listings and interactive computer sessions. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``line_block``. + +:Children: + ``line_block`` elements may contain line_ elements and nested + ``line_block`` elements. + +:Analogues: + ``line_block`` is analogous to the DocBook "literallayout" element + and to the HTML "pre" element (with modifications to typeface + styles). + +:Processing: + Unline ``literal_block``, ``line_block`` elements are typically + rendered in an ordinary text typeface. It is crucial that leading + whitespace and line breaks are preserved in the rendered form. + + +Content Model +------------- + +.. parsed-literal:: + + (line_ | line_block_)+ + +:Attributes: + The ``line_block`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus `xml:space`_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``line_block``. The `%structure.model;`_ parameter entity + indirectly includes ``line_block``. + + +Examples +-------- + +reStructuredText uses a directive to indicate a ``line_block``. +Example source:: + + Take it away, Eric the Orchestra Leader! + + | A one, two, a one two three four + | + | Half a bee, philosophically, + | must, *ipso facto*, half not be. + | But half the bee has got to be, + | *vis a vis* its entity. D'you see? + | + | But can a bee be said to be + | or not to be an entire bee, + | when half the bee is not a bee, + | due to some ancient injury? + | + | Singing... + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + Take it away, Eric the Orchestra Leader! + <line_block> + <line> + A one, two, a one two three four + <line> + <line> + Half a bee, philosophically, + <line_block> + <line> + must, + <emphasis> + ipso facto + , half not be. + <line> + But half the bee has got to be, + <line_block> + <line> + <emphasis> + vis a vis + its entity. D'you see? + <line> + <line> + But can a bee be said to be + <line_block> + <line> + or not to be an entire bee, + <line_block> + <line> + when half the bee is not a bee, + <line_block> + <line> + due to some ancient injury? + <line> + <line> + Singing... + + +``list_item`` +============= + +The ``list_item`` element is a container for the elements of a list +item. + + +Details +------- + +:Category: + `Body Subelements`_ (compound) + +:Parents: + The bullet_list_ and enumerated_list_ elements contain + ``list_item``. + +:Children: + ``list_item`` elements may contain `body elements`_. + +:Analogues: + ``list_item`` is analogous to the HTML "li" element and to the + DocBook "listitem" element. + +:Processing: + See bullet_list_ or enumerated_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)* + +:Attributes: + The ``list_item`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +reStructuredText_ source:: + + 1. Outer list, item 1. + + * Inner list, item 1. + * Inner list, item 2. + + 2. Outer list, item 2. + +Pseudo-XML_ fragment from simple parsing:: + + <enumerated_list enumtype="arabic" prefix="" suffix="."> + <list_item> + <paragraph> + Outer list, item 1. + <bullet_list bullet="*"> + <list_item> + <paragraph> + Inner list, item 1. + <list_item> + <paragraph> + Inner list, item 2. + <list_item> + <paragraph> + Outer list, item 2. + +See bullet_list_ or enumerated_list_ for further examples. + + +``literal`` +=========== + +`To be completed`_. + + +``literal_block`` +================= + +The ``literal_block`` element contains a block of text where line +breaks and whitespace are significant and must be preserved. +``literal_block`` elements are commonly used for program listings and +interactive computer sessions. See `line_block`_ for an alternative +useful for verse and addresses. + + +Details +------- + +:Category: + `Simple Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``literal_block``. + +:Children: + ``literal_block`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``literal_block`` is analogous to the HTML "pre" element and to + the DocBook "programlisting" and "screen" elements. + +:Processing: + ``literal_block`` elements are typically rendered in a monospaced + typeface. It is crucial that all whitespace and line breaks are + preserved in the rendered form. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``literal_block`` element contains the `common attributes`_ + (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``literal_block``. The `%structure.model;`_ parameter entity + indirectly includes ``literal_block``. + + +Examples +-------- + +reStructuredText source:: + + Here is a literal block:: + + if literal_block: + text = 'is left as-is' + spaces_and_linebreaks = 'are preserved' + markup_processing = None + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + Here is a literal block: + <literal_block xml:space="preserve"> + if literal_block: + text = 'is left as-is' + spaces_and_linebreaks = 'are preserved' + markup_processing = None + + +``note`` +======== + +The ``note`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, hint_, important_, tip_, warning_, and the generic +admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``note``. + +:Children: + ``note`` elements contain one or more `body elements`_. + +:Analogues: + ``note`` is analogous to the DocBook "note" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Note" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``note`` element contains only the `common attributes`_: ids_, + names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``note``. The `%structure.model;`_ parameter entity indirectly + includes ``note``. + + +Examples +-------- + +reStructuredText source:: + + .. Note:: Admonitions can be handy to break up a + long boring technical document. + +Pseudo-XML_ fragment from simple parsing:: + + <note> + <paragraph> + Admonitions can be handy to break up a + long boring technical document. + +``option`` +========== + +The ``option`` element groups an option string together with zero or +more option argument placeholders. Note that reStructuredText_ +currently supports only one argument per option. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_group_ element contains ``option``. + +:Children: + Each ``option`` element contains one option_string_ and zero or + more option_argument_ elements. + +:Analogues: + ``option`` has no direct analogues in common DTDs. + +:Processing: + See option_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (option_string_, option_argument_ \*) + +:Attributes: + The ``option`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the option_list_ element. + + +``option_argument`` +=================== + +The ``option_argument`` element contains placeholder text for option +arguments. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_ element contains ``option_argument``. + +:Children: + ``option_argument`` elements contain text data only. + +:Analogues: + ``option_argument`` has no direct analogues in common DTDs. + +:Processing: + The value of the "delimiter" attribute is prefixed to the + ``option_argument``, separating it from its option_string_ or a + preceding ``option_argument``. The ``option_argument`` text is + typically rendered in a monospaced typeface, possibly italicized + or otherwise altered to indicate its placeholder nature. + + +Content Model +------------- + +.. parsed-literal:: + + (#PCDATA) + +:Attributes: + The ``option_argument`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus delimiter_. + + ``delimiter`` contains the text preceding the ``option_argument``: + either the text separating it from the option_string_ (typically + either "=" or " ") or the text between option arguments (typically + either "," or " "). + + +Examples +-------- + +See the examples for the option_list_ element. + + +``option_group`` +================ + +The ``option_group`` element groups together one or more option_ +elements, all synonyms. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_list_item_ element contains ``option_group``. + +:Children: + ``option_group`` elements contain one or more option_ elements. + + ``option_group`` is an empty element and has no children. + + Each ``option_group`` element contains one _ and + one _ element. + +:Analogues: + ``option_group`` has no direct analogues in common DTDs. + +:Processing: + Typically option_ elements within an ``option_group`` are joined + together in a comma-separated list. + + +Content Model +------------- + +.. parsed-literal:: + + (option_group_, description_) + +:Attributes: + The ``option_group`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the option_list_ element. + + +``option_list`` +=============== + +Each ``option_list`` element contains a two-column list of +command-line options and descriptions, documenting a program's +options. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``option_list``. + +:Children: + ``option_list`` elements contain one or more option_list_item_ + elements. + +:Analogues: + ``option_list`` has no direct analogues in common DTDs. It can be + emulated with primitives such as tables. + +:Processing: + An ``option_list`` is typically rendered as a two-column list, + where the first column contains option strings and arguments, and + the second column contains descriptions. + + +Content Model +------------- + +.. parsed-literal:: + + (option_list_item_ +) + +:Attributes: + The ``option_list`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``option_list``. The `%structure.model;`_ parameter entity + indirectly includes ``option_list``. + + +Examples +-------- + +reStructuredText_ source:: + + -a command-line option "a" + -1 file, --one=file, --two file + Multiple options with arguments. + +Pseudo-XML_ fragment from simple parsing:: + + <option_list> + <option_list_item> + <option_group> + <option> + <option_string> + -a + <description> + <paragraph> + command-line option "a" + <option_list_item> + <option_group> + <option> + <option_string> + -1 + <option_argument delimiter=" "> + file + <option> + <option_string> + --one + <option_argument delimiter="="> + file + <option> + <option_string> + --two + <option_argument delimiter=" "> + file + <description> + <paragraph> + Multiple options with arguments. + + +``option_list_item`` +==================== + +The ``option_list_item`` element is a container for a pair of +option_group_ and description_ elements. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_list_ element contains ``option_list_item``. + +:Children: + Each ``option_list_item`` element contains one option_group_ and + one description_ element. + +:Analogues: + ``option_list_item`` has no direct analogues in common DTDs. + +:Processing: + See option_list_. + + +Content Model +------------- + +.. parsed-literal:: + + (option_group_, description_) + +:Attributes: + The ``option_list_item`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the option_list_ element. + + +``option_string`` +================= + +The ``option_string`` element contains the text of a command-line +option. + + +Details +------- + +:Category: + `Body Subelements`_ + +:Parents: + Only the option_ element contains ``option_string``. + +:Children: + ``option_string`` elements contain text data only. + +:Analogues: + ``option_string`` has no direct analogues in common DTDs. + +:Processing: + The ``option_string`` text is typically rendered in a monospaced + typeface. + + +Content Model +------------- + +.. parsed-literal:: + + (#PCDATA) + +:Attributes: + The ``option_string`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the option_list_ element. + + +``organization`` +================ + +The ``organization`` element contains the name of document author's +organization, or the organization responsible for the document. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + Only the docinfo_ element contains ``organization``. + +:Children: + ``organization`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``organization`` is analogous to the DocBook "orgname", + "corpname", or "publishername" elements. + +:Processing: + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``organization`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``organization``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Organization: Humankind + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <organization> + Humankind + +See docinfo_ for a more complete example, including processing +context. + + +``paragraph`` +============= + +The ``paragraph`` element contains the text and inline elements of a +single paragraph, a fundamental building block of documents. + + +Details +------- + +:Category: + `Simple Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``paragraph``. + +:Children: + ``paragraph`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``paragraph`` is analogous to the HTML "p" element and to the + DocBook "para" elements. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``paragraph`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``paragraph``. The `%structure.model;`_ parameter entity + indirectly includes ``paragraph``. + + +Examples +-------- + +reStructuredText_ source:: + + A paragraph. + +Pseudo-XML_ fragment from simple parsing:: + + <paragraph> + A paragraph. + + +``pending`` +=========== + +`To be completed`_. + + +``problematic`` +=============== + +`To be completed`_. + + +``raw`` +======= + +`To be completed`_. + + +``reference`` +============= + +`To be completed`_. + + +``revision`` +============ + +The ``revision`` element contains the revision number of the document. +It can be used alone or in conjunction with version_. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + Only the docinfo_ element contains ``revision``. + +:Children: + ``revision`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``revision`` is analogous to but simpler than the DocBook + "revision" element. It closely matches the DocBook "revnumber" + element, but in a simpler context. + +:Processing: + Often used with the RCS/CVS keyword "Revision". See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``revision`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``revision``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Version: 1 + :Revision: b + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <version> + 1 + <revision> + b + +See docinfo_ for a more complete example, including processing +context. + + +``row`` +======= + +`To be completed`_. + + +``rubric`` +========== + + rubric n. 1. a title, heading, or the like, in a manuscript, + book, statute, etc., written or printed in red or otherwise + distinguished from the rest of the text. ... + + -- Random House Webster's College Dictionary, 1991 + +A rubric is like an informal heading that doesn't correspond to the +document's structure. + +`To be completed`_. + + +``section`` +=========== + +The ``section`` element is the main unit of hierarchy for Docutils +documents. Docutils ``section`` elements are a recursive structure; a +``section`` may contain other ``section`` elements, without limit. +Paragraphs and other body elements may occur before a ``section``, but +not after it. + + +Details +------- + +:Category: + `Structural Elements`_ + +:Parents: + The following elements may contain ``section``: document_, + section_ + +:Children: + ``section`` elements begin with a title_, and may contain `body + elements`_ as well as transition_, topic_, and sidebar_ elements. + +:Analogues: + ``section`` is analogous to DocBook recursive "section" elements, + and to HTML "div" elements combined with "h1" etc. title elements. + + +Content Model +------------- + +.. parsed-literal:: + + (title_, + `%structure.model;`_) + +See the `%structure.model;`_ parameter entity for details of the body +of a ``section``. + +:Attributes: + The ``section`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%section.elements;`_ parameter entity directly includes + ``section``. The `%structure.model;`_ parameter entity indirectly + includes ``section``. + + +Examples +-------- + +reStructuredText_ source:: + + Title 1 + ======= + Paragraph 1. + + Title 2 + ------- + Paragraph 2. + + Title 3 + ======= + Paragraph 3. + + Title 4 + ------- + Paragraph 4. + +Complete pseudo-XML_ result after parsing:: + + <document> + <section ids="title-1" names="title 1"> + <title> + Title 1 + <paragraph> + Paragraph 1. + <section ids="title-2" names="title 2"> + <title> + Title 2 + <paragraph> + Paragraph 2. + <section ids="title-3" names="title 3"> + <title> + Title 3 + <paragraph> + Paragraph 3. + <section ids="title-4" names="title 4"> + <title> + Title 4 + <paragraph> + Paragraph 4. + + +``sidebar`` +=========== + +Sidebars are like miniature, parallel documents that occur inside +other documents, providing related or reference material. A +``sidebar`` is typically offset by a border and "floats" to the side +of the page; the document's main text may flow around it. Sidebars +can also be likened to super-footnotes; their content is outside of +the flow of the document's main text. + +The ``sidebar`` element is a nonrecursive section_-like construct +which may occur at the top level of a section_ wherever a body element +(list, table, etc.) is allowed. In other words, ``sidebar`` elements +cannot nest inside body elements, so you can't have a ``sidebar`` +inside a ``table`` or a ``list``, or inside another ``sidebar`` (or +topic_). + + +Details +------- + +:Category: + `Structural Elements`_ + +:Parents: + The following elements may contain ``sidebar``: document_, + section_ + +:Children: + ``sidebar`` elements begin with a title_ and an optional subtitle_ + and contain `body elements`_ and topic_ elements. + +:Analogues: + ``sidebar`` is analogous to the DocBook "sidebar" element. + +:Processing: + A ``sidebar`` element should be set off from the rest of the + document somehow, typically with a border. Sidebars typically + "float" to the side of the page and the document's main text flows + around them. + + +Content Model +------------- + +.. parsed-literal:: + + (title_, subtitle_?, + (`%body.elements;`_ | topic_)+) + +:Attributes: + The ``sidebar`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%structure.model;`_ parameter entity directly includes + ``sidebar``. + + +Examples +-------- + +The `"sidebar" directive`_ is used to create a ``sidebar`` element. +reStructuredText_ source:: + + .. sidebar:: Title + :subtitle: If Desired + + Body. + +Pseudo-XML_ fragment from simple parsing:: + + <sidebar> + <title> + Title + <subtitle> + If Desired + <paragraph> + Body. + +.. _"sidebar" directive: rst/directives.html#sidebar + + +``status`` +========== + +The ``status`` element contains a status statement for the document, +such as "Draft", "Final", "Work In Progress", etc. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + Only the docinfo_ element contains ``status``. + +:Children: + ``status`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``status`` is analogous to the DocBook "status" element. + +:Processing: + See docinfo_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``status`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``status``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Status: Work In Progress + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <status> + Work In Progress + +See docinfo_ for a more complete example, including processing +context. + + +``strong`` +========== + +`To be completed`_. + + +``subscript`` +============= + +`To be completed`_. + + +``substitution_definition`` +=========================== + +`To be completed`_. + + +``substitution_reference`` +========================== + +`To be completed`_. + + +``subtitle`` +============ + +The ``subtitle`` element stores the subtitle of a document_. + + +Details +------- + +:Category: + `Structural Subelements`_ + +:Parents: + The document_ and sidebar_ elements may contain ``subtitle``. + +:Children: + ``subtitle`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``subtitle`` is analogous to HTML header elements ("h2" etc.) and + to the DocBook "subtitle" element. + +:Processing: + A document's subtitle is usually rendered smaller than its title_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``subtitle`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +reStructuredText_ source:: + + ======= + Title + ======= + ---------- + Subtitle + ---------- + + A paragraph. + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="title" names="title"> + <title> + Title + <subtitle ids="subtitle" names="subtitle"> + Subtitle + <paragraph> + A paragraph. + +Note how two section levels have collapsed, promoting their titles to +become the document's title and subtitle. Since there is only one +structural element (document), the subsection's ``ids`` and ``names`` +attributes are stored in the ``subtitle`` element. + + +``superscript`` +=============== + +`To be completed`_. + + +``system_message`` +================== + +`To be completed`_. + + +``table`` +========= + +`To be completed`_. + + +``target`` +========== + +`To be completed`_. + + +``tbody`` +========= + +`To be completed`_. + + +``term`` +======== + +The ``term`` element contains a word or phrase being defined in a +definition_list_. + + +Details +------- + +:Category: + `Body Subelements`_ (simple) + +:Parents: + Only the definition_list_item_ element contains ``term``. + +:Children: + ``term`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``term`` is analogous to the HTML "dt" element and to the DocBook + "term" element. + +:Processing: + See definition_list_item_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``term`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + + +Examples +-------- + +See the examples for the definition_list_, definition_list_item_, and +classifier_ elements. + + +``tgroup`` +========== + +`To be completed`_. + + +``thead`` +========= + +`To be completed`_. + + +``tip`` +======= + +The ``tip`` element is an admonition, a distinctive and self-contained +notice. Also see the other admonition elements Docutils offers (in +alphabetical order): attention_, caution_, danger_, error_, hint_, +important_, note_, warning_, and the generic admonition_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``tip``. + +:Children: + ``tip`` elements contain one or more `body elements`_. + +:Analogues: + ``tip`` is analogous to the DocBook "tip" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Tip" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``tip`` element contains only the `common attributes`_: ids_, + names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes ``tip``. + The `%structure.model;`_ parameter entity indirectly includes + ``tip``. + + +Examples +-------- + +reStructuredText source:: + + .. Tip:: 15% if the service is good. + +Pseudo-XML_ fragment from simple parsing:: + + <tip> + <paragraph> + 15% if the service is good. + + +.. _title: + +``title`` +========= + +The ``title`` element stores the title of a document_, section_, +topic_, sidebar_, or generic admonition_. + + +Details +------- + +:Category: + `Structural Subelements`_ + +:Parents: + The following elements may contain ``title``: document_, section_, + topic_, sidebar_, admonition_ + +:Children: + ``title`` elements may contain text data plus `inline elements`_. + +:Analogues: + ``title`` is analogous to HTML "title" and header ("h1" etc.) + elements, and to the DocBook "title" element. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``title`` element contains the `common attributes`_ (ids_, + names_, dupnames_, source_, and classes_), plus refid_ and auto_. + + ``refid`` is used as a backlink to a table of contents entry. + + ``auto`` is used to indicate (with value "1") that the ``title`` + has been numbered automatically. + + +Examples +-------- + +reStructuredText_ source:: + + A Title + ======= + + A paragraph. + +Pseudo-XML_ fragment from simple parsing:: + + <section ids="a-title" names="a title"> + <title> + A Title + <paragraph> + A paragraph. + + +``title_reference`` +=================== + +`To be completed`_. + + +``topic`` +========= + +The ``topic`` element is a nonrecursive section_-like construct which +may occur at the top level of a section_ wherever a body element +(list, table, etc.) is allowed. In other words, ``topic`` elements +cannot nest inside body elements, so you can't have a ``topic`` inside +a ``table`` or a ``list``, or inside another ``topic``. + + +Details +------- + +:Category: + `Structural Elements`_ + +:Parents: + The following elements may contain ``topic``: document_, section_, + sidebar_ + +:Children: + ``topic`` elements begin with a title_ and may contain `body + elements`_. + +:Analogues: + ``topic`` is analogous to the DocBook "simplesect" element. + +:Processing: + A ``topic`` element should be set off from the rest of the + document somehow, such as with indentation or a border. + + +Content Model +------------- + +.. parsed-literal:: + + (title_?, + (`%body.elements;`_)+) + +:Attributes: + The ``topic`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%structure.model;`_ parameter entity directly includes + ``topic``. + + +Examples +-------- + +The `"topic" directive`_ is used to create a ``topic`` element. +reStructuredText_ source:: + + .. topic:: Title + + Body. + +Pseudo-XML_ fragment from simple parsing:: + + <topic> + <title> + Title + <paragraph> + Body. + +.. _"topic" directive: rst/directives.html#topic + + +``transition`` +============== + +The ``transition`` element is commonly seen in novels and short +fiction, as a gap spanning one or more lines, with or without a type +ornament such as a row of asterisks. Transitions separate body +elements and sections, dividing a section into untitled divisions. A +transition may not begin or end a section [#]_ or document, nor may +two transitions be immediately adjacent. + +See `Doctree Representation of Transitions`__ in `A Record of +reStructuredText Syntax Alternatives`__. + +.. [#] In reStructuredText markup, a transition may appear to fall at + the end of a section immediately before another section. A + transform recognizes this case and moves the transition so it + separates the sections. + +__ ../dev/rst/alternatives.html#doctree-representation-of-transitions +__ ../dev/rst/alternatives.html + + +Details +------- + +:Category: + `Structural Subelements`_ + +:Parents: + The following elements may contain ``transition``: document_, + section_ + +:Children: + ``transition`` is an empty element and has no children. + +:Analogues: + ``transition`` is analogous to the HTML "hr" element. + +:Processing: + The ``transition`` element is typically rendered as vertical + whitespace (more than that separating paragraphs), with or without + a horizontal line or row of asterisks. In novels, transitions are + often represented as a row of three well-spaced asterisks with + vertical space above and below. + + +Content Model +------------- + +:: + + EMPTY + +The ``transition`` element has no content; it is a "point element". + +:Attributes: + The ``transition`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%structure.model;`_ parameter entity directly includes + ``transition``. + + +Examples +-------- + +reStructuredText_ source:: + + Paragraph 1. + + -------- + + Paragraph 2. + +Complete pseudo-XML_ result after parsing:: + + <document> + <paragraph> + Paragraph 1. + <transition> + <paragraph> + Paragraph 2. + + +``version`` +=========== + +The ``version`` element contains the version number of the document. +It can be used alone or in conjunction with revision_. + + +Details +------- + +:Category: + `Bibliographic Elements`_ + +:Parents: + Only the docinfo_ element contains ``version``. + +:Children: + ``version`` elements may contain text data plus `inline + elements`_. + +:Analogues: + ``version`` may be considered analogous to the DocBook "revision", + "revnumber", or "biblioid" elements. + +:Processing: + Sometimes used with the RCS/CVS keyword "Revision". See docinfo_ + and revision_. + + +Content Model +------------- + +.. parsed-literal:: + + `%text.model;`_ + +:Attributes: + The ``version`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%bibliographic.elements;`_ parameter entity directly includes + ``version``. + + +Examples +-------- + +reStructuredText_ source:: + + Document Title + ============== + + :Version: 1.1 + +Complete pseudo-XML_ result after parsing and applying transforms:: + + <document ids="document-title" names="document title"> + <title> + Document Title + <docinfo> + <version> + 1.1 + +See docinfo_ for a more complete example, including processing +context. + + +``warning`` +=========== + +The ``warning`` element is an admonition, a distinctive and +self-contained notice. Also see the other admonition elements +Docutils offers (in alphabetical order): attention_, caution_, +danger_, error_, hint_, important_, note_, tip_. + + +Details +------- + +:Category: + `Compound Body Elements`_ + +:Parents: + All elements employing the `%body.elements;`_ or + `%structure.model;`_ parameter entities in their content models + may contain ``warning``. + +:Children: + ``warning`` elements contain one or more `body elements`_. + +:Analogues: + ``warning`` is analogous to the DocBook "warning" element. + +:Processing: + Rendered distinctly (inset and/or in a box, etc.), with the + generated title "Warning" (or similar). + + +Content Model +------------- + +.. parsed-literal:: + + (`%body.elements;`_)+ + +:Attributes: + The ``warning`` element contains only the `common attributes`_: + ids_, names_, dupnames_, source_, and classes_. + +:Parameter Entities: + The `%body.elements;`_ parameter entity directly includes + ``warning``. The `%structure.model;`_ parameter entity indirectly + includes ``warning``. + + +Examples +-------- + +reStructuredText source:: + + .. WARNING:: Reader discretion is strongly advised. + +Pseudo-XML_ fragment from simple parsing:: + + <warning> + <paragraph> + Reader discretion is strongly advised. + + +--------------------- + Attribute Reference +--------------------- + +.. contents:: :local: + :depth: 1 + +_`Common Attributes`: Through the `%basic.atts;`_ parameter entity, +all elements contain the following attributes: ids_, names_, dupnames_, +source_, and classes_. + +.. _attribute type: + +Attribute types: + +``CDATA`` + Character data. ``CDATA`` attributes may contain arbitrary text. + +``ID`` + Like a ``NMTOKEN``, but it must begin with a letter (a "name + production"). Identical ``ID`` values must not appear more than + once in a document; i.e., ID values must uniquely identify their + elements. + +``IDREF`` + A reference to an ``ID`` value (a name production) of another + element. + +``IDREFS`` + One or more space-separated ``ID`` references (name productions). + +``NMTOKEN`` + A "name token". One or more of letters, digits, ".", "-", and + "_". + +``NMTOKENS`` + One or more space-separated ``NMTOKEN`` names. + +``%yesorno;`` + No if zero ("0"), yes if any other value. This is a parameter + entity which resolves to a ``NMTOKEN`` attribute type. + +``%number;`` + This emphasizes that the attribute value must be a number. This + is a parameter entity which resolves to a ``NMTOKEN`` attribute + type. + +enumeration + The attribute value may be one of a specified list of values. + + +``anonymous`` +============= + +`Attribute type`_: ``%yesorno;``. Default value: none (implies no). + +The ``anonymous`` attribute is used for unnamed hyperlinks in the +target_ and reference_ elements (via the `%anonymous.att;`_ parameter +entity). + + +``auto`` +======== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``auto`` attribute is used to indicate automatically-numbered +footnote_, footnote_reference_ and title_ elements (via the +`%auto.att;`_ parameter entity). + + +``backrefs`` +============ + +`Attribute type`_: ``IDREFS``. Default value: none. + +The ``backrefs`` attribute contains a space-separated list of ids_ +references, used for backlinks from footnote_, citation_, and +system_message_ elements (via the `%backrefs.att;`_ parameter entity). + + +``bullet`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``bullet`` attribute is used in the bullet_list_ element. + + +``classes`` +=========== + +`Attribute type`_: ``NMTOKENS``. Default value: none. + +The ``classes`` attribute is a list containing one or more names used +to classify an element. The purpose of the attribute is to indicate +an "is-a" variant relationship, to allow an extensible way of defining +sub-classes of existing elements. It can be used to carry context +forward between a Docutils Reader and Writer, when a custom structure +is reduced to a standardized document tree. One common use is in +conjunction with stylesheets, to add selection criteria. It should +not be used to carry formatting instructions or arbitrary content. + +The ``classes`` attribute's contents should be ignorable. Writers that +are not familiar with the variant expressed should be able to ignore +the attribute. + +``classes`` is one of the `common attributes`_, shared by all Docutils +elements. + + +``delimiter`` +============= + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``delimiter`` attribute is used in the option_argument_ element. + + +``dupnames`` +============ + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``dupnames`` attribute is a list containing the names of an +element when there has been a naming conflict. The contents of the +``dupnames`` attribute would have been transferred from the `names`_ +attribute. An element may have at most one of the ``names`` or +``dupnames`` attributes, but not both. ``dupnames`` is one of the +`common attributes`_, shared by all Docutils elements. + + +``enumtype`` +============ + +`Attribute type`_: enumeration, one of "arabic", "loweralpha", +"upperalpha", "lowerroman", or "upperroman". Default value: none. + +The ``enumtype`` attribute is used in the enumerated_list_ element. + + +``ids`` +======= + +`Attribute type`_: ``NMTOKENS``. Default value: none. + +The ``ids`` attribute is a list containing one or more unique +identifier keys. ``ids`` is one of the `common attributes`_, shared +by all Docutils elements. + + +``names`` +========= + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``names`` attribute is a list containing the names of an element, +typically originating from the element's title or content. Each name +in ``names`` must be unique; if there are name conflicts (two or more +elements want to the same name), the contents will be transferred to +the `dupnames`_ attribute on the duplicate elements. An element may +have at most one of the ``names`` or ``dupnames`` attributes, but not +both. ``names`` is one of the `common attributes`_, shared by all +Docutils elements. + + +``prefix`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``prefix`` attribute is used in the enumerated_list_ element. + + +``refid`` +========= + +`Attribute type`_: ``IDREF``. Default value: none. + +The ``refid`` attribute contains references to `ids`_ attributes in +other elements. It is used by the target_, reference_, +footnote_reference_, citation_reference_, title_ and problematic_ +elements (via the `%refid.att;`_ and `%reference.atts;`_ parameter +entities). + + +``refname`` +=========== + +`Attribute type`_: ``NMTOKENS``. Default value: none. + +The ``refname`` attribute contains an internal reference to the +`names`_ attribute of another element. On a `target`_ element, +``refname`` indicates an indirect target which may resolve to either +an internal or external reference. ``refname`` is used by the +target_, reference_, footnote_reference_, citation_reference_, and +substitution_reference_ elements (via the `%refname.att;`_ and +`%reference.atts;`_ parameter entities). + + +``refuri`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``refuri`` attribute contains an external reference to a URI/URL. +It is used by the target_, reference_, footnote_reference_, and +citation_reference_ elements (via the `%reference.atts;`_ parameter +entity). + + +``source`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``source`` attribute is used to store the path or URL to the +source text that was used to produce the document tree. It is one of +the `common attributes`_, shared by all Docutils elements. + + +``start`` +========= + +`Attribute type`_: ``%number;``. Default value: none. + +The ``start`` attribute is used in the enumerated_list_ element. + + +``suffix`` +========== + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``suffix`` attribute is used in the enumerated_list_ element. + + +``xml:space`` +============= + +`Attribute type`_: one of "default" or "preserve". Default value: +"preserve" (fixed). + +The ``xml:space`` attribute is a standard XML attribute for +whitespace-preserving elements. It is used by the literal_block_, +line_block_, doctest_block_, comment_, and raw_ elements (via the +`%fixedspace.att;`_ parameter entity). It is a fixed attribute, meant +to communicate to an XML parser that the element contains significant +whitespace. The attribute value should not be set in a document +instance. + + +.. _title (attribute): + +``title`` +========= + +`Attribute type`_: ``CDATA``. Default value: none. + +The ``title`` attribute stores the title metadata of a document. This +title is typically not part of the rendered document. It may for +example be used in HTML's ``title`` element. + + +---------------------------- + Parameter Entity Reference +---------------------------- + +.. contents:: :local: + :depth: 1 + +Parameter entities are used to simplify the DTD (to share definitions +and reduce duplication) and to allow the DTD to be customized by +wrapper DTDs (external client DTDs that use or import the Docutils +DTD). Parameter entities may be overridden by wrapper DTDs, replacing +the definitions below with custom definitions. Parameter entities +whose names begin with "additional" are meant to allow easy extension +by wrapper DTDs. + + +``%anonymous.att;`` +=================== + +The ``%anonymous.att;`` parameter entity contains the anonymous_ +attribute, used for unnamed hyperlinks. + +Entity definition: + +.. parsed-literal:: + + anonymous_ %yesorno; #IMPLIED + +The reference_ and target_ elements directly employ the +``%anonymous.att;`` parameter entity in their attribute lists. + + +``%auto.att;`` +============== + +The ``%auto.att;`` parameter entity contains the auto_ attribute, used +to indicate an automatically-numbered footnote or title. + +Entity definition: + +.. parsed-literal:: + + auto_ CDATA #IMPLIED + +The footnote_, footnote_reference_, and title_ elements directly +employ the ``%auto.att;`` parameter entity in their attribute lists. + + +``%backrefs.att;`` +================== + +The ``%backrefs.att;`` parameter entity contains the backrefs_ +attribute, a space-separated list of id references, for backlinks. + +Entity definition: + +.. parsed-literal:: + + backrefs_ IDREFS #IMPLIED + +The citation_, footnote_, and system_message_ elements directly employ +the ``%backrefs.att;`` parameter entity in their attribute lists. + + +``%basic.atts;`` +================ + +The ``%basic.atts;`` parameter entity lists attributes common to all +Docutils elements. See `Common Attributes`_. + +Entity definition: + +.. parsed-literal:: + + ids_ NMTOKENS #IMPLIED + names_ CDATA #IMPLIED + dupnames_ CDATA #IMPLIED + source_ CDATA #IMPLIED + classes_ NMTOKENS #IMPLIED + %additional.basic.atts; + +The ``%additional.basic.atts;`` parameter entity can be used by +wrapper DTDs to extend ``%basic.atts;``. + + +``%bibliographic.elements;`` +============================ + +The ``%bibliographic.elements;`` parameter entity contains an OR-list of all +`bibliographic elements`_. + +Entity definition: + +.. parsed-literal:: + + author_ | authors_ | organization_ | contact_ | address_ + | version_ | revision_ | status_ | date_ | copyright_ + | field_ + %additional.bibliographic.elements; + +The ``%additional.bibliographic.elements;`` parameter entity can be used by +wrapper DTDs to extend ``%bibliographic.elements;``. + +Only the docinfo_ element directly employs the +``%bibliographic.elements;`` parameter entity in its content model. + + +``%body.elements;`` +=================== + +The ``%body.elements;`` parameter entity contains an OR-list of all +`body elements`_. ``%body.elements;`` is itself contained within the +`%structure.model;`_ parameter entity. + +Entity definition: + +.. parsed-literal:: + + paragraph_ | compound_ | container_ | literal_block_ | doctest_block_ + | line_block_ | block_quote_ + | table_ | figure_ | image_ | footnote_ | citation_ | rubric_ + | bullet_list_ | enumerated_list_ | definition_list_ | field_list_ + | option_list_ + | attention_ | caution_ | danger_ | error_ | hint_ | important_ | note_ + | tip_ | warning_ | admonition_ + | reference_ | target_ | substitution_definition_ | comment_ | pending_ + | system_message_ | raw_ + %additional.body.elements; + +The ``%additional.body.elements;`` parameter entity can be used by +wrapper DTDs to extend ``%body.elements;``. + +The ``%body.elements;`` parameter entity is directly employed in the +content models of the following elements: admonition_, attention_, +block_quote_, caution_, citation_, compound_, danger_, definition_, +description_, entry_, error_, field_body_, footer_, footnote_, +header_, hint_, important_, legend_, list_item_, note_, sidebar_, +system_message_, tip_, topic_, warning_ + +Via `%structure.model;`_, the ``%body.elements;`` parameter entity is +indirectly employed in the content models of the document_ and +section_ elements. + + +``%fixedspace.att;`` +==================== + +The ``%fixedspace.att;`` parameter entity contains the `xml:space`_ +attribute, a standard XML attribute for whitespace-preserving +elements. + +Entity definition: + +.. parsed-literal:: + + `xml:space`_ (default | preserve) #FIXED 'preserve' + +The ``%fixedspace.att;`` parameter entity is directly employed in the +attribute lists of the following elements: address_, comment_, +doctest_block_, line_block_, literal_block_, raw_ + + +``%inline.elements;`` +===================== + +The ``%inline.elements;`` parameter entity contains an OR-list of all +`inline elements`_. + +Entity definition: + +.. parsed-literal:: + + emphasis_ | strong_ | literal_ + | reference_ | footnote_reference_ | citation_reference_ + | substitution_reference_ | title_reference_ + | abbreviation_ | acronym_ | subscript_ | superscript_ + | inline_ | problematic_ | generated_ + | target_ | image_ | raw_ + %additional.inline.elements; + +The ``%additional.inline.elements;`` parameter entity can be used by +wrapper DTDs to extend ``%inline.elements;``. + +Via `%text.model;`_, the ``%inline.elements;`` parameter entity is +indirectly employed in the content models of the following elements: +abbreviation_, acronym_, address_, attribution_, author_, caption_, +classifier_, contact_, copyright_, date_, doctest_block_, emphasis_, +generated_, inline_, line_block_, literal_block_, organization_, +paragraph_, problematic_, raw_, reference_, revision_, rubric_, +status_, strong_, subscript_, substitution_definition_, +substitution_reference_, subtitle_, superscript_, target_, term_, +title_, title_reference_, version_ + + +``%reference.atts;`` +==================== + +The ``%reference.atts;`` parameter entity groups together the refuri_, +refid_, and refname_ attributes. + +Entity definition: + +.. parsed-literal:: + + `%refuri.att;`_ + `%refid.att;`_ + `%refname.att;`_ + %additional.reference.atts; + +The ``%additional.reference.atts;`` parameter entity can be used by +wrapper DTDs to extend ``%additional.reference.atts;``. + +The citation_reference_, footnote_reference_, reference_, and target_ +elements directly employ the ``%reference.att;`` parameter entity in +their attribute lists. + + +``%refid.att;`` +================ + +The ``%refid.att;`` parameter entity contains the refid_ attribute, an +internal reference to the `ids`_ attribute of another element. + +Entity definition: + +.. parsed-literal:: + + refid_ CDATA #IMPLIED + +The title_ and problematic_ elements directly employ the +``%refid.att;`` parameter entity in their attribute lists. + +Via `%reference.atts;`_, the ``%refid.att;`` parameter entity is +indirectly employed in the attribute lists of the citation_reference_, +footnote_reference_, reference_, and target_ elements. + + +``%refname.att;`` +================= + +The ``%refname.att;`` parameter entity contains the refname_ +attribute, an internal reference to the `names`_ attribute of another +element. On a `target`_ element, ``refname`` indicates an indirect +target which may resolve to either an internal or external +reference. + +Entity definition: + +.. parsed-literal:: + + refname_ NMTOKENS #IMPLIED + +The substitution_reference_ element directly employs the +``%refname.att;`` parameter entity in its attribute list. + +Via `%reference.atts;`_, the ``%refname.att;`` parameter entity is +indirectly employed in the attribute lists of the citation_reference_, +footnote_reference_, reference_, and target_ elements. + + +``%refuri.att;`` +================ + +The ``%refuri.att;`` parameter entity contains the refuri_ attribute, +an external reference to a URI/URL. + +Entity definition: + +.. parsed-literal:: + + refuri_ CDATA #IMPLIED + +Via `%reference.atts;`_, the ``%refuri.att;`` parameter entity is +indirectly employed in the attribute lists of the citation_reference_, +footnote_reference_, reference_, and target_ elements. + + +``%section.elements;`` +====================== + +The ``%section.elements;`` parameter entity contains an OR-list of all +section_-equivalent elements. ``%section.elements;`` is itself +contained within the `%structure.model;`_ parameter entity. + +Entity definition: + +.. parsed-literal:: + + section_ + %additional.section.elements; + +The ``%additional.section.elements;`` parameter entity can be used +by wrapper DTDs to extend ``%section.elements;``. + +Via `%structure.model;`_, the ``%section.elements;`` parameter entity +is indirectly employed in the content models of the document_ and +section_ elements. + + +``%structure.model;`` +===================== + +The ``%structure.model;`` parameter entity encapsulates the +hierarchical structure of a document and of its constituent parts. +See the discussion of the `element hierarchy`_ above. + +Entity definition: + +.. parsed-literal:: + + ( ( (`%body.elements;`_ | topic_ | sidebar_)+, transition_? )*, + ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? ) + +Each document_ or section_ contains zero or more body elements, +topics, and/or sidebars, optionally interspersed with single +transitions, followed by zero or more sections (whose contents are +recursively the same as this model) optionally interspersed with +transitions. + +The following restrictions are imposed by this model: + +* Transitions must be separated by other elements (body elements, + sections, etc.). In other words, a transition may not be + immediately adjacent to another transition. + +* A transition may not occur at the beginning of a document or + section. + +An additional restriction, which cannot be expressed in the language +of DTDs, is imposed by software: + +* A transition may not occur at the end of a document or section. + +The `%structure.model;`_ parameter entity is directly employed in the +content models of the document_ and section_ elements. + + +``%text.model;`` +================ + +The ``%text.model;`` parameter entity is used by many elements to +represent text data mixed with `inline elements`_. + +Entity definition: + +.. parsed-literal:: + + (#PCDATA | `%inline.elements;`_)* + +The ``%text.model;`` parameter entity is directly employed in the +content models of the following elements: abbreviation_, acronym_, +address_, author_, caption_, classifier_, contact_, copyright_, date_, +doctest_block_, emphasis_, field_name_, generated_, line_block_, +literal_block_, organization_, paragraph_, problematic_, raw_, +reference_, revision_, status_, strong_, substitution_definition_, +substitution_reference_, subtitle_, target_, term_, title_, version_ + + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: |