The Docutils Document Tree
A Guide to the Docutils DTD
- Contact:
- docutils-develop@lists.sourceforge.net
- Revision:
- $Revision$
- Date:
- $Date$
- Copyright:
- This document has been placed in the public domain.
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.
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, e.g., Introducing the Extensible Markup Language (XML).
Docutils implements the Document tree data structure in the Python module docutils.nodes. For details, see its internal API documentation ("docstrings").
The reStructuredText markup language 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.
Element Hierarchy
The Docutils document model uses strict element content models.
Below is a simplified diagram of the hierarchy of elements in the Docutils document tree structure. An element may contain elements immediately below it in the diagram. Element types in square brackets indicate recursive or one-to-many relationships: structural elements (sections) may contain sub-sections, some body elements may contain other body elements, etc. The element reference details valid parents and children for each element.
text |
|||
Every element has a unique structure and semantics, but elements may be classified into general categories according to their place and role in the document. Some elements belong to more than one category.
Alternatively, we may classify elements by their content model:
- Compound elements
- may contain child elements but no text data.
- Simple elements
- may contain text data.Most simple elements have a mixed content model (%text.model). However, only inline elements may be intermixed with text. [1]Examples: <paragraph> (mixed), <literal_block> (text-only)
- Empty elements
- contain neither child elements nor text.
Element Categories
Root Element
Every Docutils document contains exactly one root element. The root element has no parent. It may contain structural elements, all structural subelements, and body elements. It does not directly contain text.
- Category members:
- Docutils class:
nodes.Root
Structural Elements
Structural elements group other elements to provide a document structure. They are child elements of the root element or other structural elements. Structural elements may contain specific structural elements, structural subelements, or body elements.
Structural Subelements
Structural subelements are child elements of the root element or specific structural elements. Their content model varies (see the respective element reference section for details).
- Category members:
- empty:
- simple:
- compound:
- Docutils class:
nodes.SubStructural
Decorative Elements
Decorative elements are used to generate page headers and footers. They are child elements of <decoration> and contain body elements.
Bibliographic Elements
Bibliographic elements store document meta-data like title or author. They are child elements of <docinfo>. The elements <authors> and <field> are compound elements, the others are simple elements containing text and inline elements.
- Category members:
<address>, <author>, <authors>, <contact>, <copyright>, <date>, <field>, <organization>, <revision>, <status>, <version>
- Docutils class:
nodes.Bibliographic
- Parameter entity:
Body Elements
Body elements are children of the root element, structural elements, or compound body elements. Compound body elements may contain body subelements or further body elements.
- Category members:
- empty:
- simple:
<comment>, <doctest_block>, <literal_block>, <math_block>, <paragraph>, <raw>, <reference>, <rubric>, <substitution_definition>, <target>
- compound:
<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>
- Docutils class:
nodes.Body
- Parameter entity:
Body Subelements
Body subelements always occur within specific parent elements (e.g. <bullet_list> contains <list_item>), never at the body element level (beside paragraphs, etc.). Body subelements may be compound elements (containing body elements or further body subelements) or simple elements.
- Category members:
- empty:
- simple:
<attribution>, <caption>, <classifier>, <field_name>, <label>, <line>, <option_argument>, <option_string>, <term>, <title>
- compound:
<definition>, <definition_list_item>, <description>, <entry>, <field>, <field_body>, <legend>, <list_item>, <option>, <option_group>, <option_list_item>, <row>, <tbody>, <tgroup>, <thead>
- Docutils class:
nodes.Part
Inline Elements
Inline elements are contained within simple body elements or other inline elements. Inline elements are simple elements: All inline elements may contain text data, most inline elements may also contain further inline elements.
- Category members:
<abbreviation>, <acronym>, <citation_reference>, <emphasis>, <footnote_reference>, <generated>, <image>, <inline>, <literal>, <math>, <problematic>, <raw>, <reference>, <strong>, <subscript>, <substitution_reference>, <superscript>, <target>, <title_reference>
- Docutils class:
nodes.Inline
- Parameter entity:
Element Reference
Each element in the DTD (document type definition) is described in its own section below. Each section contains the following items:
Summary description (up to two sentences).
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.
- 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.
- Parents:
A list of elements which may contain the element.
- Children:
A list of elements which may occur within the element followed by the formal XML content model from the Docutils DTD.
- 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 (if applicable).
Additional free text description and explanations (optional).
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>
The <abbreviation> element is an inline element representing an abbreviation, a shortened or contracted form of a word or phrase used to represent the whole.
- Category:
- Analogues:
<abbreviation> is analogous to the DocBook <abbrev> element and similar to the HTML <abbr> element. (In HTML 5, the <abbr> element is also used for acronyms.)
- Processing:
May be used to semantically mark the presence of an abbreviation in the text for styling or scripting purposes. Writers may ignore the element and just render its contents.
- Parents:
All elements employing the %text.model parameter entity in their content models may contain <abbreviation>.
- Children:
<abbreviation> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <abbreviation> element contains only the common attributes.
Examples
The reStructuredText "abbreviation" role creates an <abbreviation> element:
:abbreviation:`St` is a common abbreviation for "street".
Pseudo-XML fragment from simple parsing:
<paragraph>
<abbreviation>
St
is a common abbreviation for "street".
<acronym>
The <acronym> element is an inline element used to represent an acronym (abbreviation formed by the initial letters of other words).
- Category:
- Analogues:
<acronym> is analogous to the DocBook <acronym> element. In HTML, the <abbr> element is used for both, abbreviations and acronyms.
- Processing:
May be used to semantically mark the presence of an acronym in the text for styling or scripting purposes. Writers may ignore the element and just render its contents.
- Parents:
All elements employing the %text.model parameter entity in their content models may contain <acronym>.
- Children:
<acronym> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <acronym> element contains only the common attributes.
Examples
The reStructuredText "acronym" role creates an <acronym> element:
`WWW`:acronym: is the acronym for the world wide web.
Pseudo-XML fragment from simple parsing:
<paragraph>
<acronym>
WWW
is the acronym for the world wide web.
<address>
The <address> element holds the surface mailing address information for the author(s) (individual or group) of the document, or a third-party contact address.
- Category:
- 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>.
- Parents:
The following elements may contain <address>: <docinfo>, <authors>.
- Children:
<address> elements contain text data plus inline elements (%text.model).
- Attributes:
The <address> element contains the common attributes plus xml:space.
- Parameter Entities:
The %bibliographic.elements parameter entity directly includes <address>.
Examples
In reStructuredText, "address" is one of the registered bibliographic fields:
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>
The <admonition> element is a generic, titled admonition, a distinctive and self-contained notice.
- Category:
- Analogues:
The generic <admonition> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. The specific admonitions <caution>, <note>, <tip>, and <warning> are analogous to the respective DocBook elements.
- Processing:
Rendered distinctly (inset and/or in a box, etc.).
- 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.
- Attributes:
The <admonition> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <admonition>. The %structure.model parameter entity indirectly includes <admonition>.
See also the specific admonition elements <attention> <caution>, <danger>, <error>, <hint>, <important>, <note>, <tip>, and <warning>.
Examples
The reStructuredText "admonition" directive creates a generic <admonition> element:
.. admonition:: By the way... You can make up your own admonition too.
Pseudo-XML fragment from simple parsing:
<admonition class="admonition-by-the-way">
<title>
By the way...
<paragraph>
You can make up your own admonition too.
<attention>
The <attention> element is a specific admonition, a distinctive and self-contained notice.
- Category:
- 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).
- 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.
- Attributes:
The <attention> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <attention>. The %structure.model parameter entity indirectly includes <attention>.
See also the generic <admonition> and the other specific admonition elements.
Examples
A reStructuredText "attention" directive:
.. Attention:: All your base are belong to us.
Pseudo-XML fragment from simple parsing:
<attention>
<paragraph>
All your base are belong to us.
<attribution>
<block_quote>
The <block_quote> element is used for quotations set off from the main text (standalone).
- Category:
- 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.
- 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.
- Attributes:
The <block_quote> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <block_quote>. The %structure.model parameter entity indirectly includes <block_quote>.
Examples
In reStructuredText, an indented text block without preceding markup is a block quote:
As a great palaeontologist once said,
This theory, that is mine, is mine.
-- Anne Elk (Miss)
Pseudo-XML fragment from simple parsing:
<paragraph>
As a great palaeontologist 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.
- Category:
- Analogues:
<bullet_list> is analogous to the HTML<ul> element [2] and to the DocBook <itemizedlist> element.
- Processing:
Each list item should begin a new vertical block, prefaced by a bullet/dingbat.
- 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.
- Attributes:
The <bullet_list> element contains the common attributes plus bullet.
- Parameter Entities:
The %body.elements parameter entity directly includes <bullet_list>. The %structure.model parameter entity indirectly includes <bullet_list>.
Examples
A reStructuredText bullet list:
- 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>
<caution>
The <caution> element is a specific admonition, a distinctive and self-contained notice. See also the generic <admonition> and the other specific admonition elements.
- Category:
- 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).
- 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.
- Attributes:
The <caution> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <caution>. The %structure.model parameter entity indirectly includes <caution>.
Examples
A reStructuredText "caution" directive:
.. Caution:: Don't take any wooden nickels.
Pseudo-XML fragment from simple parsing:
<caution>
<paragraph>
Don't take any wooden nickels.
<citation>
<citation_reference>
<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.
- Category:
Body Subelements (simple)
- Analogues:
<classifier> has no direct analogues in common DTDs. It can be emulated with primitives or type effects.
- Processing:
- Parents:
Only the <definition_list_item> element contains <classifier>.
- Children:
<classifier> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <classifier> element contains only the common attributes.
Examples
A reStructuredText definition list with classifiers:
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>
The <colspec> element contains specifications for a column in a <table>.
- Category:
- Analogues:
<colspec> is defined in the XML Exchange Table Model DTD. [8] It is analogous to the DocBook <colspec> element. The HTML <col> element is related but has different semantics.
- Processing:
See the Exchange Table Model.
- Parents:
Only the <tgroup> element contains <colspec>.
- Children:
The <colspec> element has no content.
- Attributes:
<colspec> elements accept the colnum, colname, colwidth, colsep, rowsep, align, char, and charoff attributes. However, of these only colwidth is used by Docutils -- currently with a different interpretation (see below). Via the %tbl.colspec.att parameter entity, <colspec> supports also the common attributes and stub.
Examples
See <table>.
<comment>
<compound>
The <compound> element combines multiple body elements to a single logical paragraph.
- Category:
- Analogues:
The <compound> element has no direct analogues in common DTDs. In HTML, it can be emulated with <div> and CSS styling. [3]
- Processing:
Typically rendered as multiple distinct text blocks, with the possibility of variations to emphasize their logical unity (cf. the "compound" directive).
- Parents:
All elements employing the %body.elements or %structure.model parameter entities in their content models may contain <compound>.
- Children:
<compound> elements contain one or more body elements.
- Attributes:
The <compound> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <compound>. The %structure.model parameter entity indirectly includes <compound>.
Examples
The reStructuredText "compound" directive creates a <compound> element:
.. compound::
The 'rm' command is very dangerous. If you are logged
in as root and enter ::
cd /
rm -rf *
you will erase the entire contents of your file system.
Pseudo-XML fragment from simple parsing:
<compound>
<paragraph>
The 'rm' command is very dangerous. If you are logged
in as root and enter
<literal_block xml:space="preserve">
cd /
rm -rf *
<paragraph>
you will erase the entire contents of your file system.
<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.
- Category:
- Analogues:
<contact> is analogous to the DocBook <email> element. The HTML <address> element serves a similar purpose.
- Processing:
See <docinfo>.
- Parents:
The following elements may contain <contact>: <docinfo>, <authors>.
- Children:
<contact> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <contact> element contains only the common attributes.
- Parameter Entities:
The %bibliographic.elements parameter entity directly includes <contact>.
Examples
In reStructuredText, "contact" is one of the registered bibliographic fields:
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>
The <container> element groups multiple body elements for user- or application-specific purposes.
- Category:
- Analogues:
The <container> element is analogous to the HTML <div> element or the SVG <g> element.
- Processing:
Can be used for styling or scripting purposes. An example is a frame or background colour) based on the value of the classes attribute.
- Parents:
All elements employing the %body.elements or %structure.model parameter entities in their content models may contain <container>.
- Children:
<container> elements contain one or more body elements.
- Attributes:
The <container> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <container>. The %structure.model parameter entity indirectly includes <container>.
Examples
The reStructuredText "container" directive creates a <container> element:
.. container:: green boxed-equation .. math:: -1^2 = 1 This paragraph is in the box, too.
Pseudo-XML fragment from simple parsing:
<container classes="framed square">
<math_block xml:space="preserve">
-1^2 = 1
<paragraph>
This paragraph is in the box, too.
The HTML output can be placed in a common box with the custom CSS rule
div.framed {border: solid;
padding: 1em;}
<copyright>
The <copyright> element contains the document's copyright statement.
- Category:
- Analogues:
<copyright> is analogous to the DocBook <copyright> element.
- Processing:
See <docinfo>.
- Parents:
Only the <docinfo> element contains <copyright>.
- Children:
<copyright> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <copyright> element contains only the common attributes.
- Parameter Entities:
The %bibliographic.elements parameter entity directly includes <copyright>.
Examples
In reStructuredText, "copyright" is one of the registered bibliographic fields:
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 a specific admonition, a distinctive and self-contained notice.
- Category:
- 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).
- 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.
- Attributes:
The <danger> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <danger>. The %structure.model parameter entity indirectly includes <danger>.
See also the generic <admonition> and the other specific admonition elements.
Examples
A reStructuredText "danger" directive:
.. 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.
- Category:
- Analogues:
<date> is analogous to the DocBook <date> element.
- Processing:
Often used with the RCS/CVS keyword "Date". See <docinfo>.
- Parents:
Only the <docinfo> element contains <date>.
- Children:
<date> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <date> element contains only the common attributes.
- Parameter Entities:
The %bibliographic.elements parameter entity directly includes <date>.
Examples
In reStructuredText, "date" is one of the registered bibliographic fields:
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.
- Category:
- Analogues:
There are no direct analogies to <decoration> in HTML or in DocBook.
- Processing:
See the individual decorative elements.
- Parents:
Only the <document> element contains <decoration>.
- Children:
<decoration> elements may contain the decorative elements <header> and/or <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.
Examples
<definition>
The <definition> element is a container for the body elements used to define a <term> in a <definition_list>.
- Category:
Body Subelements (compound)
- Analogues:
<definition> is analogous to the HTML <dd> element and to the DocBook <listitem> element (inside a <variablelistentry> element).
- Processing:
- Parents:
Only <definition_list_item> elements contain <definition>.
- Children:
<definition> elements contain body elements.
- Attributes:
The <definition> element contains only the common attributes.
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.
- Category:
- Analogues:
<definition_list> is analogous to the HTML <dl> element and to the DocBook <variablelist> element.
- Processing:
- 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.
- Attributes:
The <definition_list> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <definition_list>. The %structure.model parameter entity indirectly includes <definition_list>.
See also <field_list>.
Examples
A reStructuredText definition list. The classifier is optional.
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>
A wrapper for a set of terms (with optional classifiers) and the associated definition in a <definition_list>.
- Category:
Body Subelements (compound)
- Analogues:
<definition_list_item> is analogous to the DocBook <variablelistentry> element.
- Processing:
The optional <classifier>s can be rendered differently from the <term>. They should be separated visually, typically by spaces plus a colon or dash.
- Parents:
Only the <definition_list> element contains <definition_list_item>.
- Children:
<definition_list_item> elements each contain one or more <term> elements, zero or more <classifier> elements, and a <definition>:
((term, classifier*)+, definition)
Changed in Docutils 0.22: allow multiple terms.
- Attributes:
The <definition_list_item> element contains only the common attributes.
Examples
A complex reStructuredText definition list:
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>
<comment xml:space="preserve">
<block_quote>
<paragraph>
All brontosauruses are thin at one end,
much much thicker in the middle
and then thin again at the far end.
<attribution>
Anne Elk (Miss)
See <definition_list> and <classifier> for further examples.
<description>
The <description> element is the part of an <option_list> item that contains the description of a command-line option or group of options.
- Category:
- Analogues:
<description> has no direct analogues in common DTDs.
- Processing:
See <option_list>.
- Parents:
Only the <option_list_item> element contains <description>.
- Children:
<description> elements may contain body elements.
- Attributes:
The <description> element contains only the common attributes.
Examples
See the examples for the <option_list> element.
<docinfo>
The <docinfo> element is a container for displayed 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.
- Category:
- Analogues:
<docinfo> is analogous to DocBook <info> elements. 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.
- Parents:
Only the <document> element contains <docinfo>.
- Children:
<docinfo> elements contain bibliographic elements.
- Attributes:
The <docinfo> element contains only the common attributes.
See also the <meta> element (for hidden meta-data).
Examples
Bibliographic data is represented in reStructuredText by a field list as the first visible element of a document (after optional document title and subtitle). The field list is transformed into a <docinfo> element and its children by the DocInfo transform. [4]
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 classes="filename">
<field_name>
Filename
<field_body>
<paragraph>
doctree.rst
<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 a reStructuredText field list 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 a <literal_block>.
- Category:
- 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.
- 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 (%text.model):
- Attributes:
The <doctest_block> element contains the common attributes plus xml:space.
- Parameter Entities:
The %body.elements parameter entity directly includes <doctest_block>. The %structure.model parameter entity indirectly includes <doctest_block>.
<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.
Examples
A reStructuredText doctest block:
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.
- Category:
- Analogues:
<document> is analogous to the HTML <html> element and to several DocBook elements such as <book>.
- Parents:
The <document> element has no parents.
- Children:
<document> elements may contain structural elements, structural subelements, and body elements
( (title, subtitle?)?, meta*, decoration?, (docinfo, transition?)?, %structure.model; )
See the %structure.model parameter entity for details of the body of a <document>.
- Attributes:
The <document> element contains the common attributes plus an optional title attribute which stores the document title metadata.
<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.
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, the DocTitle transform may promote a lone top-level section title to become the document <title>, and similarly 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>.
Examples
A minimal reStructuredText document with title:
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>
The <emphasis> element is an inline element representing text that has stress emphasis.
- Category:
- Analogues:
<emphasis> is analogous to the HTML <em> element and the DocBook <emphasis> element.
- Processing:
Typically displayed in italic type.
- Parents:
All elements employing the %text.model parameter entity in their content models may contain <emphasis>.
- Children:
<emphasis> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <emphasis> element contains only the common attributes.
Examples
The reStructuredText there are two emphasis markup alternatives:
There are :emphasis:`two` ways to *emphasize* text.
Pseudo-XML fragment from simple parsing:
<paragraph>
There are
<emphasis>
two
ways to
<emphasis>
emphasize
text.
<entry>
The <entry> element represents one cell of a <table>.
- Category:
- Analogues:
<entry> is defined in the XML Exchange Table Model DTD. [8] It is analogous to the DocBook <entry> element. HTML differentiates between header entries <td> and data entries <td>.
- Processing:
Render content in a table cell. The morecols and morerows attributes may be used to define an entry spanning several table cells. See the Exchange Table Model for details.
- Parents:
- Children:
<entry> elements may contain body elements (via the %tbl.entry.mdl parameter entity).
- Attributes:
The <entry> element accepts the colname, namest, nameend, morerows, colsep, rowsep, align, char, charoff, and valign attributes (ignored by Docutils) and (via the %tbl.entry.att parameter entity) the common attributes and morecols.
Examples
See <table>.
<enumerated_list>
The <enumerated_list> element contains <list_item> elements which are uniformly marked with enumerator labels.
- Category:
- 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.").
- 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.
- Attributes:
The <enumerated_list> element contains the common attributes plus enumtype, prefix, suffix, and start.
- Parameter Entities:
The %body.elements parameter entity directly includes <enumerated_list>. The %structure.model parameter entity indirectly includes <enumerated_list>.
Examples
A reStructuredText enumerated list:
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 a specific admonition, a distinctive and self-contained notice.
- Category:
- 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).
- 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.
- Attributes:
The <error> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <error>. The %structure.model parameter entity indirectly includes <error>.
See also the generic <admonition> and the other specific admonition elements.
Examples
A reStructuredText "error" directive:
.. Error:: Does not compute.
Pseudo-XML fragment from simple parsing:
<error>
<paragraph>
Does not compute.
<field>
The <field> element contains one item of a <field_list>, a pair of <field_name> and <field_body> elements.
- Category:
- Analogues:
<field> has no direct analogues in common DTDs. HTML5 uses <div> elements inside <dl> lists for grouping <dt>/<dd> pairs.
- Processing:
See <field_list>.
- Parents:
The following elements may contain <field>: <docinfo>, <field_list>
- Children:
Each <field> element contains one <field_name> and one <field_body> element.
- Attributes:
The <field> element contains only the common attributes.
- 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 is analogous to a database field's data.
- Category:
- Analogues:
<field_body> is analogous to the HTML <dd> element.
- Processing:
See <field_list>.
- Parents:
Only the <field> element contains <field_body>.
- Children:
<field_body> elements may contain body elements.
- Attributes:
The <field_body> element contains only the common attributes.
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).
- Category:
- Analogues:
<field_list> is analogue to the HTML <dl> element.
- 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.
- 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.
- Attributes:
The <field_list> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <field_list>. The %structure.model parameter entity indirectly includes <field_list>.
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.
Examples
A reStructuredText field list:
: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 is analogous to a database field's name.
- Category:
Body Subelements (simple)
- Analogues:
<field_name> is analogous to the HTML <dt> element.
- Processing:
See <field_list>.
- Parents:
Only the <field> element contains <field_name>.
- Children:
<field_name> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <field_name> element contains only the common attributes.
Examples
See the examples for the <field_list> and <docinfo> elements.
<figure>
<footnote>
The <footnote> element is used for labelled notes that provide additional context to a passage of text (footnotes or endnotes). The corresponding footnote mark in running text is set by the <footnote_reference> element.
- Category:
- Analogues:
<footnote> has no direct analogues in DocBook or HTML.
The DocBook <footnote> element combines features of <footnote> and <footnote_reference>.
The DPub ARIA role "doc-footnote" may be used to mark a (conforming) HTML emulation as "ancillary information, such as a citation or commentary, that provides additional context to a referenced passage of text".
For collections of notes that occur at the end of a section, the DPub ARIA role "doc-endnotes" is more appropriate.
The corresponding types in the EPUB 3 Structural Semantics Vocabulary are "footnote" and "endnote".
- Processing:
A <footnote> element should be set off from the rest of the document, e.g. with a border or using a smaller font size.
Footnotes may "float" to the bottom or margin of a page or a dedicated section.
- Parents:
All elements employing the %body.elements or %structure.model parameter entities in their content models may contain <footnote>.
- Children:
<footnote> elements begin with an optional [5] <label> and contain body elements.
(label?, (%body.elements;)+)
- Attributes:
The <footnote> element contains the common attributes plus auto and backrefs.
- Parameter Entities:
The %body.elements parameter entity directly includes <footnote>. The %structure.model parameter entity indirectly includes <footnote>.
Examples
reStructuredText uses explicit markup blocks for footnotes:
.. [1] This is a footnote.
Pseudo-XML fragment from simple parsing:
<footnote ids="id1" names="1">
<label>
1
<paragraph>
This is a footnote.
<footnote_reference>
The <footnote_reference> element is an inline element representing a cross reference to a <footnote> (a footnote mark).
- Category:
- Analogues:
The <footnote_reference> element resembles the DocBook <footnoteref> element or the LaTeX \footnotemark command. There is no equivalent in HTML. The <a> element can be used to provide a link to the corresponding footnote.
- Processing:
A <footnote_reference> should generate a mark matching the <label> of the referenced footnote. The mark is typically formatted as superscript or enclosed in square brackets.
- Parents:
All elements employing the %text.model parameter entity in their content models may contain <footnote-reference>.
- Children:
<footnote_reference> elements contain text data only.
- Attributes:
The <footnote_reference> element contains the common attributes plus auto, refid, and refname.
Examples
A reStructuredText footnote reference and footnote:
[#]_ is an auto-numbered footnote reference. .. [#] Auto-numbered footnote 1.
Pseudo-XML fragment from simple parsing:
<paragraph>
<footnote_reference auto="1" ids="id1">
is an auto-numbered footnote reference.
<footnote auto="1" ids="id3">
<paragraph>
Auto-numbered footnote 1.
The references.Footnotes Docutils transform resolves this to:
<paragraph>
<footnote_reference auto="1" ids="id1" refid="id2">
1
is an auto-numbered footnote reference.
<footnote auto="1" backrefs="id1" ids="id2" names="1">
<label>
1
<paragraph>
Auto-numbered footnote 1.
<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.
<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.
- Category:
- Analogues:
<header> is analogous to the HTML5 <header> element. There are no direct analogies to <header> in HTML4 or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system.
- Parents:
Only the <decoration> element contains <header>.
- Children:
<header> elements may contain body elements.
- Attributes:
The <header> element contains only the common attributes.
Examples
A reStructuredText "header" directive:
.. header:: This space for rent.
Pseudo-XML fragment from simple parsing:
<document>
<decoration>
<header>
<paragraph>
This space for rent.
<hint>
The <hint> element is a specific admonition, a distinctive and self-contained notice.
- Category:
- 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).
- 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.
- Attributes:
The <hint> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <hint>. The %structure.model parameter entity indirectly includes <hint>.
See also the generic <admonition> and the other specific admonition elements.
Examples
A reStructuredText "hint" directive:
.. Hint:: It's bigger than a bread box.
Pseudo-XML fragment from simple parsing:
<hint>
<paragraph>
It's bigger than a bread box.
<image>
The <image> element refers to an image resource that should be included in the document.
- Categories:
- Analogues:
<image> is analogous to the HTML <img>, DocBook <imagedata>, and SVG <image> elements.
- Processing:
The specified image is included into the output document. Depending on the output format, this is done by referring to the image URI or by embedding the image data.
- Parents:
All elements employing the %body.elements, %text.model, or %structure.model parameter entities in their content models may contain <image>.
- Children:
The <image> element has no content.
- Attributes:
The <image> element contains the common attributes plus uri, alt, align, height, width, scale, and loading.
- Parameter Entities:
The %body.elements and %inline.elements parameter entities directly include <image>. The %structure.model and %text.model parameter entities indirectly include <image>.
It is up to the author to ensure compatibility of the image data format with the output format or user agent (LaTeX engine, HTML browser, ...). The reStructuredText Directives documentation contains a non exhaustive table of compatible image formats.
Examples
A reStructuredText "image" directive:
.. image:: picture.jpeg :width: 20 mm :alt: alternate text
Pseudo-XML fragment from simple parsing:
<image alt="alternate text" uri="picture.jpeg" width="20mm">
<important>
The <important> element is a specific admonition, a distinctive and self-contained notice.
- Category:
- 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).
- 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.
- Attributes:
The <important> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <important>. The %structure.model parameter entity indirectly includes <important>.
See also the generic <admonition> and the other specific admonition elements.
Examples
A reStructuredText "important" directive:
.. Important:: * Wash behind your ears. * Clean up your room. * Back up your data.
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.
<inline>
The <inline> element is a generic inline container.
- Category:
- Analogues:
<inline> is analogous to the HTML <span> element and the Docbook <phrase> element.
- Processing:
Writers typically pass the classes attribute to the output document and leave styling to the backend or a custom stylesheet. They may also process the classes attribute and convert the <inline> element to a specific element or render the content distinctly for specific class values. Moreover, writers may ignore the element and just render the content.
- Parents:
All elements employing the %text.model parameter entity in their content models may contain <inline>.
- Children:
<inline> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <inline> element contains only the common attributes.
Examples
Custom interpreted text roles create <inline> elements (unless they are based on a standard role).
This reStructuredText source fragment creates and uses a custom role:
.. role:: custom An example of using :custom:`interpreted text`
Pseudo-XML fragment from simple parsing:
<paragraph>
An example of using
<inline classes="custom">
interpreted text
<label>
<legend>
<line>
The <line> element contains a single line of text, part of a <line_block>.
- Category:
Body Subelements (simple)
- Analogues:
<line> has no direct analogues in common DTDs. It can be emulated with primitives or type effects.
- Processing:
See <line_block>.
- Parents:
Only the <line_block> element contains <line>.
- Children:
<line> elements may contain text data plus inline elements.
- Attributes:
The <line> element contains only the common attributes.
Examples
See <line_block>.
<line_block>
The <line_block> element contains a sequence of lines and nested line blocks.
- Category:
- Analogues:
<line_block> is analogous to the DocBook <literallayout> element and to the HTML <pre> element (with modifications to typeface styles).
- Processing:
Line breaks (implied between elements) and leading whitespace (indicated by nesting) is significant and must be preserved. Unlike <literal_block>, <line_block> elements are typically rendered in an ordinary text typeface.
- 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.
(line | line_block)+
- Attributes:
The <line_block> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <line_block>. The %structure.model parameter entity indirectly includes <line_block>.
<line_block> elements are commonly used for verse and addresses. See <literal_block> for an alternative useful for program listings and interactive computer sessions.
Examples
A reStructuredText line block:
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.
- Category:
Body Subelements (compound)
- Analogues:
<list_item> is analogous to the HTML <li> element and to the DocBook <listitem> element.
- Processing:
See <bullet_list> or <enumerated_list>.
- Parents:
The <bullet_list> and <enumerated_list> elements contain <list_item>.
- Children:
<list_item> elements may contain body elements.
- Attributes:
The <list_item> element contains only the common attributes.
Examples
A reStructuredText enumerated list with a nested bullet list:
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>
<literal_block>
The <literal_block> element contains a block of text where line breaks and whitespace are significant and must be preserved.
Details
- Category:
- 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.
- 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 (%text.model).
- Attributes:
The <literal_block> element contains the common attributes plus xml:space.
- Parameter Entities:
The %body.elements parameter entity directly includes <literal_block>. The %structure.model parameter entity indirectly includes <literal_block>.
<literal_block> elements are commonly used for program listings and interactive computer sessions. See <line_block> for an alternative useful for verse and addresses.
Examples
A reStructuredText "parsed-literal" directive:
.. parsed-literal::
if parsed_literal:
text = 'is parsed for reStructuredText_ markup'
spaces_and_linebreaks = 'are preserved'
markup_processing = **True**
Pseudo-XML fragment from simple parsing:
<literal_block xml:space="preserve">
if parsed_literal:
text = 'is parsed for
<reference name="reStructuredText" refid="restructuredtext">
reStructuredText
markup'
spaces_and_linebreaks = 'are preserved'
markup_processing =
<strong>
True
<literal-block> elements are also generated by a literal block and the "code" directive.
<math>
The <math> element contains text in LaTeX math format [6] that is typeset as mathematical notation (inline formula).
- Category:
- Analogues:
<math> is analogous to a HTML/MathML <math> element or the LaTeX ($ math $) mode.
- Processing:
Rendered as mathematical notation. If the output format does not support math typesetting, the content may be inserted verbatim.
- Parents:
All elements employing the %text.model parameter entitiy in their content models may contain <math>.
- Children:
<math> elements contain text data only.
- Attributes:
The <math> element contains only the common attributes.
Example
reStructuredText source:
Euler's identity is the equality :math:`e^{i\pi + 1 = 0`.
Pseudo-XML fragment from simple parsing:
<paragraph>
Euler’s identity is the equality
<math>
e^{\mathrm{i}\pi + 1 = 0
.
<math_block>
The <math_block> element contains a block of text in LaTeX math format [6] that is typeset as mathematical notation (display formula).
- Category:
- Analogues:
<math_block> is analogous to a HTML/MathML <math> element displayed as block-level element or a LaTeX equation* environment.
- Processing:
Rendered in a block as mathematical notation, typically centered or with indentation If the output format does not support math typesetting, the content may be inserted verbatim.
- Parents:
All elements employing the %body.elements or %structure.model parameter entities in their content models may contain <math_block>.
- Children:
<math_block> elements contain text data only.
- Attributes:
The <math_block> element contains the common attributes plus xml:space.
Example
The reStructuredText "math" directive generates a <math_block> element:
Euler's identity is the equality
.. math:: e^{i\pi + 1 = 0
Pseudo-XML fragment from simple parsing:
<paragraph>
Euler’s identity is the equality
<math_block xml:space="preserve">
e^{i\pi + 1 = 0
<meta>
The <meta> element is a container for "hidden" document bibliographic data, or meta-data (data about the document).
- Category:
- Analogues:
<meta> is analogous to the HTML <meta> element or the file properties in ODT or PDF documents.
- Processing:
The <meta> element is stored as metadata if the export format supports this. It is typically invisible and may be omitted from the processed output.
Meta-data may also be extracted from <docinfo> children or the <document> attributes (title).
- Parents:
Only the <document> element contains <meta>.
- Children:
The <meta> element has no content.
- Attributes:
The <meta> element contains the attributes content, dir, http-equiv, lang, media, name, and scheme that correspond to the respective attributes of the HTML <meta> element.
See also the <docinfo> element for displayed meta-data. The document's title attribute stores the metadata document title.
Example
A reStructuredText "meta" directive:
.. meta:: :description lang=en: An amusing story :description lang=fr: Un histoire amusant
Pseudo-XML fragment from simple parsing:
<meta content="An amusing story" lang="en" name="description"> <meta content="Un histoire amusant" lang="fr" name="description">
<note>
The <note> element is a specific admonition, a distinctive and self-contained notice.
- Category:
- 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).
- 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.
- Attributes:
The <note> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <note>. The %structure.model parameter entity indirectly includes <note>.
See also the generic <admonition> and the other specific admonition elements.
Examples
A reStructuredText "note" directive:
.. 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.
- Category:
- Analogues:
<option> has no direct analogues in common DTDs.
- Processing:
See <option_list>.
- Parents:
Only the <option_group> element contains <option>.
- Children:
<option> elements start with an <option_string> and may contain <option_argument> elements:
(option_string, option_argument*)
- Attributes:
The <option> element contains only the common attributes.
Note that reStructuredText currently supports only one argument per option.
Examples
See the examples for the <option_list> element.
<option_argument>
The <option_argument> element contains placeholder text for option arguments.
- Category:
- 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.
- Parents:
Only the <option> element contains <option_argument>.
- Children:
<option_argument> elements contain text data only.
- Attributes:
The <option_argument> element contains the common attributes plus delimiter.
Examples
See the examples for the <option_list> element.
<option_group>
The <option_group> element groups together one or more <option> elements, all synonyms.
- Category:
- 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.
- Parents:
Only the <option_list_item> element contains <option_group>.
- Children:
<option_group> elements contain one or more <option> elements.
- Attributes:
The <option_group> element contains only the common attributes.
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.
- Category:
- 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.
- 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.
- Attributes:
The <option_list> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <option_list>. The %structure.model parameter entity indirectly includes <option_list>.
Examples
A reStructuredText option list:
-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.
- Category:
- Analogues:
<option_list_item> has no direct analogues in common DTDs.
- Processing:
See <option_list>.
- Parents:
Only the <option_list> element contains <option_list_item>.
- Children:
Each <option_list_item> element contains one <option_group> and one <description> element.
- Attributes:
The <option_list_item> element contains only the common attributes.
Examples
See the examples for the <option_list> element.
<option_string>
The <option_string> element contains the text of a command-line option.
- Category:
- Analogues:
<option_string> has no direct analogues in common DTDs.
- Processing:
The <option_string> text is typically rendered in a monospaced typeface.
- Parents:
Only the <option> element contains <option_string>.
- Children:
<option_string> elements contain text data only.
- Attributes:
The <option_string> element contains only the common attributes.
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.
- Category:
- Analogues:
<organization> is analogous to the DocBook <orgname>, <corpname>, or <publishername> elements.
- Processing:
See <docinfo>.
- Parents:
Only the <docinfo> element contains <organization>.
- Children:
<organization> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <organization> element contains only the common attributes.
- Parameter Entities:
The %bibliographic.elements parameter entity directly includes <organization>.
Examples
In reStructuredText, "organization" is one of the registered bibliographic fields:
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.
- Category:
- Analogues:
<paragraph> is analogous to the HTML <p> element and to the DocBook <para> 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 (%text.model).
- Attributes:
The <paragraph> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <paragraph>. The %structure.model parameter entity indirectly includes <paragraph>.
Examples
In reStructuredText, blocks of left-aligned text are paragraphs unless marked up as another body element:
A paragraph must be left-aligned.
Pseudo-XML fragment from simple parsing:
<paragraph>
A paragraph must be
left-aligned.
<pending>
<problematic>
The <problematic> element highlights a source part that caused a parsing problem.
- Category:
- Analogues:
<problematic> has no direct analogues in common DTDs.
- Processing:
Typically displayed in red colour. If the refid attribute is present, the element should point to the referenced element.
- Parents:
All elements employing the %text.model parameter entity in their content models may contain <problematic>.
- Children:
<problematic> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <problematic> element contains the common attributes and refid.
Examples
The reStructuredText parser marks ambiguous or invalid inline syntax as <problematic> and adds a reference to the associated <system_message>. The behaviour can be configured with the report_level setting.
The following paragraph contains unbalanced inline markup:
a single *star
Pseudo-XML fragment from simple parsing:
<paragraph>
a single
<problematic ids="problematic-1" refid="system-message-1">
*
star
<system_message backrefs="problematic-1" ids="system-message-1"
level="2" line="1" source="example.rst" type="WARNING">
<paragraph>
Inline emphasis start-string without end-string.
<raw>
The <raw> element contains non-reStructuredText data that is to be passed untouched to the Writer.
- Category:
- Analogues:
The <raw> element has no direct analogues in common DTDs.
- Processing:
Passed untouched to the Writer. The interpretation is up to the Writer. A Writer may ignore <raw> elements not matching its format.
- Parents:
All elements employing the %body.elements, %structure.model, or %text.model parameter entities in their content models may contain <raw>.
- Children:
<raw> elements contain text data only.
- Attributes:
The <raw> element contains the common attributes plus format and xml:space.
- Parameter Entities:
The %body.elements and %inline.elements parameter entities directly include <raw>. The %structure.model and %text.model parameter entities indirectly include <raw>.
Examples
The reStructuredText "raw" directive [7] creates a <raw> element:
.. raw:: html <hr width=50 size=10>
Pseudo-XML fragment from simple parsing:
<raw format="html" xml:space="preserve">
<hr width=50 size=10>
<reference>
<revision>
The <revision> element contains the revision number of the document. It can be used alone or in conjunction with <version>.
- Category:
- 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>.
- Parents:
Only the <docinfo> element contains <revision>.
- Children:
<revision> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <revision> element contains only the common attributes.
- Parameter Entities:
The %bibliographic.elements parameter entity directly includes <revision>.
Examples
In reStructuredText, "revision" is one of the registered bibliographic fields:
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>
The <row> element represents one row of a <table>.
- Category:
- Analogues:
<row> is defined in the XML Exchange Table Model DTD. [8] It is analogous to the HTML <tr> element and the DocBook <row> element.
- Processing:
Render content as a table row. See the Exchange Table Model for details.
- Parents:
- Children:
A <row> element contains one or more <entry> elements.
- Attributes:
The <row> element may contain the rowsep and valign attributes (ignored by Docutils) and (via the %tbl.row.att parameter entity) the common attributes.
Examples
See <table>.
<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.
<section>
The <section> element is the main unit of hierarchy for Docutils documents.
- Category:
- Analogues:
<section> is analogous to the section elements in DocBook and HTML. However, unlike <h1> … <h6> in HTML and <sect1> … <sect5> in DocBook, the level is not incorporated into the element name.
- Parents:
The following elements may contain <section>: <document>, <section>
- Children:
<section> elements begin with a <title>, followed by an optional <subtitle>. They may contain structural elements, body elements, and <transition> elements:
(title, subtitle?, %structure.model;)
- Attributes:
The <section> element contains only the common attributes.
- Parameter Entities:
The %section.elements parameter entity directly includes <section>. The %structure.model parameter entity indirectly includes <section>.
The Docutils document model uses a simple, recursive model for section structure. A <document> node may contain <section> elements. Sections in turn may contain other <section> elements, without limit. The level (depth) of a section element is determined from its physical nesting level.
Paragraphs and other body elements may occur before a <section>, but not after it.
Examples
reStructuredText does not impose a fixed number and order of section title adornment styles. The order enforced will be the order as encountered.
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.
<status>
The <status> element contains a status statement for the document, such as "Draft", "Final", "Work In Progress", etc.
- Category:
- Analogues:
<status> is analogous to the DocBook <status> element.
- Processing:
See <docinfo>.
- Parents:
Only the <docinfo> element contains <status>.
- Children:
<status> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <status> element contains only the common attributes.
- Parameter Entities:
The %bibliographic.elements parameter entity directly includes <status>.
Examples
In reStructuredText, "status" is one of the registered bibliographic fields:
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>
The <strong> element is an inline element representing text that has strong importance, seriousness, or urgency.
- Category:
- Analogues:
<strong> is analogous to the HTML <strong> element.
- Processing:
Typically displayed in boldface.
- Parents:
All elements employing the %text.model parameter entity in their content models may contain <strong>.
- Children:
<strong> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <strong> element contains only the common attributes.
Examples
The reStructuredText there are two alternatives to mark text with strong emphasis:
There are :strong:`two` ways to **strongly emphasize** text.
Pseudo-XML fragment from simple parsing:
<paragraph>
There are
<strong>
two
ways to
<strong>
strongly emphasize
text.
<subscript>
The <subscript> element is an inline element representing text which should be displayed as subscript.
- Category:
- Analogues:
<subscript> is analogous to the HTML <sub> element and the DocBook <subscript> element.
- Processing:
Typically rendered with a lowered baseline using smaller text.
- Parents:
All elements employing the %text.model parameter entity in their content models may contain <subscript>.
- Children:
<subscript> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <subscript> element contains only the common attributes.
Examples
The reStructuredText "subscript" role creates a <subscript> element:
The chemical formula for water is H\ :sub:`2`\ O.
Pseudo-XML fragment from simple parsing:
<paragraph>
The chemical formula for water is H
<subscript>
2
O.
<substitution_definition>
The <substitution_definition> element stores a reStructuredText substitution definition.
<substitution_reference>
<subtitle>
The <subtitle> element stores the subtitle of a <document>, <section>, or <sidebar>.
- Category:
- Analogues:
<subtitle> is analogous to the DocBook <subtitle> element. In HTML, subtitles are represented by a <p> element inside a <hgroup> element.
- Processing:
A document's subtitle is usually rendered smaller than its <title>.
- Parents:
The <document>, <section>, and <sidebar> elements may contain <subtitle>.
- Children:
<subtitle> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <subtitle> element contains only the common attributes.
Examples
In reStructuredText, a lone second-level section title immediately after the “document title” can become the document subtitle:
======= Title ======= ---------- Subtitle ---------- A paragraph.
Complete pseudo-XML result after parsing and applying the DocTitle transform:
<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>
The <superscript> element is an inline element representing text which should be displayed as superscript.
- Category:
- Analogues:
<superscript> is analogous to the HTML <sup> element and the DocBook <superscript> element.
- Processing:
Typically rendered with a raised baseline using smaller text.
- Parents:
All elements employing the %text.model parameter entity in their content models may contain <superscript>.
- Children:
<superscript> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <superscript> element contains only the common attributes.
Examples
The reStructuredText "superscript" role creates a <superscript> element:
Key events of the 20\ :sup:`th` century.
Pseudo-XML fragment from simple parsing:
<paragraph>
Key events of the 20
<superscript>
th
century.
<system_message>
The <system_message> element is used for feedback from the processing system.
- Category:
- Analogues:
<system_message> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.
- Processing:
Rendered similar to an <admonition>, with the generated title "System Message", its type/level and, if available, source and line.
- Parents:
All elements employing the %body.elements or %structure.model parameter entities in their content models may contain <system_message>.
- Children:
<system_message> elements contain one or more body elements.
- Attributes:
The <system_message> element accepts the common attributes plus backrefs, level, line, and type.
- Parameter Entities:
The %body.elements parameter entity directly includes <system_message>. The %structure.model parameter entity indirectly includes <system_message>.
In Docutils, the generation of system messages can be configured with the report_level setting.
Examples
An undefined or misspelled directive generates an error message:
.. contants::
Pseudo-XML fragment from simple parsing:
<system_message level="3" line="8" source="example.rst" type="ERROR">
<paragraph>
Unknown directive type "contants".
<literal_block xml:space="preserve">
.. contants::
See also <problematic>.
<table>
The <table> element represents a data arrangement with rows and columns.
- Category:
- Analogues:
<table> is defined in the XML Exchange Table Model DTD. [8] It is analogous to the HTML and DocBook <table> elements.
- Processing:
Content is arranged in rows and columns forming a grid. See the Exchange Table Model for details.
- Parents:
<document>, <section> and all body elements may contain <table>.
- Children:
<table> elements begin with an optional <title> (caption) and may contain one or more <tgroup> elements:
(title?, tgroup+)
- Attributes:
The <table> element may contain the frame, colsep, rowsep, and pgwide attributes (ignored by Docutils) and (via the %bodyatt parameter entity) the common attributes, align, and width.
- Parameter Entities:
The %body.elements parameter entity directly includes <table>. The %structure.model parameter entity indirectly includes <table>.
Examples
In reStructuredText, tables can be specified via the "table", "csv-table", or "list-table" directives or directly as grid table or simple table, e.g.
======== ==== bread £2 butter £30 ======== ====
Pseudo-XML fragment from simple parsing:
<table>
<tgroup cols="2">
<colspec colwidth="8">
<colspec colwidth="4">
<tbody>
<row>
<entry>
<paragraph>
bread
<entry>
<paragraph>
£2
<row>
<entry>
<paragraph>
butter
<entry>
<paragraph>
£30
<target>
<tbody>
The <tbody> element identifies the rows that form the body of a <table> (as distinct from the header rows).
- Category:
- Analogues:
<tbody> is defined in the XML Exchange Table Model DTD. [8] It is analogous to the HTML <tbody> and the DocBook <tbody> (db.cals.tbody) elements.
- Processing:
Render content as table body.
- Parents:
Only the <tgroup> element contains <tbody>.
- Children:
A <tbody> element contains one or more <row> elements.
- Attributes:
The <tbody> element may contain valign (ignored by Docutils) and (via the %tbl.tbody.att parameter entity) the common attributes.
Examples
See <table>.
<term>
The <term> element contains a word or phrase being defined in a <definition_list>.
- Category:
Body Subelements (simple)
- Analogues:
<term> is analogous to the HTML <dt> element and to the DocBook <term> element.
- Processing:
- Parents:
Only the <definition_list_item> element contains <term>.
- Children:
<term> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <term> element contains only the common attributes.
Examples
See the examples for the <definition_list>, <definition_list_item>, and <classifier> elements.
<tgroup>
The <tgroup> element identifies a logically complete portion of a <table>.
- Category:
- Analogues:
<tgroup> is defined in the XML Exchange Table Model DTD. [8] It is analogous to the DocBook <tgroup> element. There is no corresponding HTML element (the <colgroup> element has a different purpose and semantics).
- Processing:
See the Exchange Table Model.
- Parents:
Only the <table> element contains <tgroup>.
- Children:
<tgroup> elements contain one or more <colspec> elements, followed by an optional <thead> and a <tbody> (cf. the %tbl.tgroup.mdl parameter entity). The number of <colspec>s, must not exceed the value of the cols attribute. Docutils expects one <colspec> per column.
- Attributes:
The <tgroup> element must contain a cols attribute and may contain colsep, rowsep, and align (ignored by Docutils). Via the %tbl.tgroup.att parameter entity, <tgroup> supports the common attributes.
Tables usually consist of a single <tgroup>. Complex tables with widely varying column specifications may be easier to code using multiple <tgroup>s. However, this is not supported by table markup in reStructuredText and Docutils table handling routines.
Examples
See <table>.
<thead>
The <thead> element identifies the row(s) that form the head of a <table> (as distinct from the body rows).
- Category:
- Analogues:
<thead> is defined in the XML Exchange Table Model DTD. [8] It is analogous to the HTML and DocBook <thead> elements.
- Processing:
Header rows are always rendered at the beginning of the table and often presented in an alternate typographic style, such as boldface. In paged media, if a table spans across multiple pages, header rows are printed at the top of each new page.
- Parents:
Only the <tgroup> element contains <thead>.
- Children:
A <thead> element contains one or more <row> elements.
- Attributes:
The <thead> element contains the valign attribute (ignored by Docutils) and (via the %tbl.thead.att parameter entity) the common attributes.
Examples
See <table>.
<tip>
The <tip> element is a specific admonition, a distinctive and self-contained notice.
- Category:
- 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).
- 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.
- Attributes:
The <tip> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <tip>. The %structure.model parameter entity indirectly includes <tip>.
See also the generic <admonition> and the other specific admonition elements.
Examples
A reStructuredText "tip" directive:
.. Tip:: 15% if the service is good.
Pseudo-XML fragment from simple parsing:
<tip>
<paragraph>
15% if the service is good.
<title>
The <title> element stores the title of a <document>, structural elements, or a generic <admonition>. It is also used for the caption of a <table>.
- Category:
- Analogues:
<title> is analogous to the DocBook <title> element and the HTML header elements (<h1> etc.) while the HTML <title> element corresponds to a <document>'s title attribute. As child of a <table>, <title> corresponds to the HTML <caption> element.
- Parents:
The following elements may contain <title>: <admonition>, <document>, <section>, <sidebar>, <table>, <topic>.
- Children:
<title> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <title> element contains the common attributes plus refid (used as a backlink to a table of contents entry) and auto.
The <title> of a document may differ from its metadata title stored in the title attribute.
Examples
Section titles are marked up with "underlines" below the title text (or underlines and matching overlines):
A Title ======= A paragraph. Next section's title ====================
Pseudo-XML fragment from simple parsing:
<section ids="a-title" names="a\ title">
<title>
A Title
<paragraph>
A paragraph.
<section ids="next-section-s-title" names="next\ section's\ title">
<title>
Next section’s title
See also the examples for <admonition>, <document>, <section>, <sidebar>, <subtitle>, <table>, and <topic>.
<title_reference>
The <title_reference> element is an inline element representing the titles of a cited creative work.
- Category:
- Analogues:
<title_reference> is analogous to the HTML <cite> element and the DocBook <citetitle> element.
- Processing:
Typically displayed in italic type.
- Parents:
All elements employing the %text.model parameter entity in their content models may contain <title_reference>.
- Children:
<title_reference> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <title_reference> element contains only the common attributes.
Examples
The reStructuredText "title-reference" role creates a <title_reference> element:
The term "spam" is derived from the 1970 :title:`Spam` sketch.
Pseudo-XML fragment from simple parsing:
<paragraph>
The term “spam” is derived from the 1970
<title_reference>
Spam
sketch.
<topic>
The <topic> element represents a non-recursive section-like construct for content that is separate from the flow of the document.
- Category:
- Analogues:
<topic> is analogous to the DocBook <simplesect> element and the HTML <aside> element.
- Processing:
A <topic> element should be set off from the rest of the document somehow, such as with indentation or a border. In contrast to a <sidebar>, it should not float.
- Parents:
The following elements may contain <topic>: <document>, <section>, <sidebar>
- Children:
<topic> elements may begin with a <title> and contain body elements:
(title?, (%body.elements;)+)
- Attributes:
The <topic> element accepts the common attributes.
- Parameter Entities:
The %structure.model parameter entity directly includes <topic>.
Topics are terminal, "leaf" mini-sections, like block quotes with titles, or textual figures. A <topic> is just like a <section>, except that it has no subsections, it does not get listed in the ToC, and it doesn't have to conform to section placement rules. You may place a <topic> in the middle of a <section> and continue the same section after it --- something that cannot be done with a nested <section>.
Topics cannot nest inside topics, or body elements (tables, lists, block quotes, etc).
Docutils uses the <topic> element also for a generated table of contents, and the "abstract" and "dedication" bibliographic fields.
Examples
A reStructuredText "topic" directive:
.. topic:: Title Body.
Pseudo-XML fragment from simple parsing:
<topic>
<title>
Title
<paragraph>
Body.
<transition>
The <transition> element separates body elements and sections, dividing a <section> into untitled divisions.
- Category:
- 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.
- Parents:
The following elements may contain <transition>: <document>, <section>
- Children:
The <transition> element has no content.
- Attributes:
The <transition> element contains only the common attributes.
- Parameter Entities:
The %structure.model parameter entity directly includes <transition>.
A transition may not begin or end a section [9] or document, nor may two transitions be immediately adjacent.
See also Doctree Representation of Transitions in A Record of reStructuredText Syntax Alternatives.
Examples
A transition in the 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>.
- Category:
- 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>.
- Parents:
Only the <docinfo> element contains <version>.
- Children:
<version> elements may contain text data plus inline elements (%text.model).
- Attributes:
The <version> element contains only the common attributes.
- Parameter Entities:
The %bibliographic.elements parameter entity directly includes <version>.
Examples
In reStructuredText, "version" is one of the registered bibliographic fields:
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 a specific admonition, a distinctive and self-contained notice.
- Category:
- 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).
- 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.
- Attributes:
The <warning> element contains only the common attributes.
- Parameter Entities:
The %body.elements parameter entity directly includes <warning>. The %structure.model parameter entity indirectly includes <warning>.
See also the generic <admonition> and the other specific admonition elements.
Examples
A reStructuredText "warning" directive:
.. WARNING:: Reader discretion is strongly advised.
Pseudo-XML fragment from simple parsing:
<warning>
<paragraph>
Reader discretion is strongly advised.
Attribute Types
Standard Attribute Types
Standard attribute types are defined in the attribute types section of the XML 1.0 specification [xml1.0].
- CDATA
Character data. CDATA attributes may contain arbitrary text.
- NMTOKEN
A "name token". One or more of letters, digits, ".", "-", and "_".
- NMTOKENS
One or more space-separated NMTOKEN values.
- EnumeratedType
The attribute value may be one of a specified list of values.
Custom Attribute Types
The Docutils DTD defines custom attribute types via parameter entities that resolve to standard attribute types to highlight specific attribute value constraints. In the docutils.nodes reference implementation, values are stored using the specified Python data types.
- %classnames.type
- Space-separated list of class names. Resolves to NMTOKEN.Used in the classes attribute. Python data type: list[str].
- %idref.type
- Used in the refid attribute. Python data type: str.
- %idrefs.type
- Space separated list of references to other elements by their identifiers. Resolves to NMTOKENS. [11]Used in the backrefs attribute. Python data type: list[str].
- %ids.type
- Used in the ids attribute. Python data type: list[str].
- %measure
- A number which may be immediately followed by a unit or percent sign. ReStructuredText supports CSS3 length units. Handling of values without unit depends on the writer/output format (see the writer specific documentation in the user documentation for details). Resolves to CDATA.
- %number
- %refname.type
- A reference name. Resolves to CDATA.Used in the refname attribute. Python data type: str.
- %refnames.type
- Space-separated list of reference names. Resolves to CDATA.
Backslash escaping is used for space characters inside a reference name.
- %yesorno
Names and identifiers
The following names and identifiers are used in the custom attribute types.
- Class names
define sub-classes of existing elements.
Docutils employs the identifier normalization to ensure class names conform to both, HTML4.1 and CSS1.0 name requirements (the regular expression [a-z](-?[a-z0-9]+)*).
In reStructuredText, custom class names can be specified using the "class" directive, a directive's class option, or custom interpreted text roles.
Class names are used in the classes attribute (%classnames.type).
- Reference names
are identifiers assigned in the markup.
Reference names may consist of any text. Whitespace is normalized. [10]
In reStructuredText, reference names originate from internal hyperlink targets, a directive's name option, or the element's title or content and are used for internal cross-references.
Hyperlinks, footnotes, and citations all share the same namespace for reference names. Comparison ignores case.
Substitutions use a distinct namespace. Comparison is case-sensitive but forgiving.
Reference names are used in the name, names, refname, and dupnames attributes (%refname.type or %refnames.type).
- Identifiers
are used for cross references in generated documents.
Docutils employs the identifier normalization to comply with restrictions in the supported output formats (HTML4.1, HTML5, polyglot HTML, LaTeX, ODT, manpage, XML).
Identifiers cannot be specified directly in reStructuredText. Docutils generates them from reference names or from the auto_id_prefix, prepending the id_prefix and appending numbers for disambiguation if required.
Identifiers are used in the ids, refid, and backrefs attributes (%ids.type, %idref.type, or %idrefs.type) [11].
Common Attributes
Through the %basic.atts parameter entity, all elements support the following attributes: ids, names or dupnames, source, and classes.
Attribute Reference
alt
Attribute type: CDATA. Default value: none.
The alt attribute is used to store a text description in the <image> element.
align
Attribute type: EnumeratedType. Default value: none (inherit).
The align attribute is used in the <figure> and <table> elements via the %align-h.att parameter entity and in <image> via the %align-hv.att parameter entity to specify the alignment of the element within its parent element.
The Exchange Table Model uses align in the <colspec>, <entry>, end <tgroup> elements to specify the text alignment in table cells. It cannot be specified in reStructuredText and is ignored by Docutils writers.
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.type. Default value: none.
The backrefs attribute contains a space-separated list of identifier 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 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.
classes
Attribute type: %classnames.type. Default value: none.
The classes attribute is a space separated list containing zero or more class names.
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.
char
Attribute type: CDATA. Default value: "" (no aligning character).
The char attribute is used in the <colspec> and <entry> elements to specify an alignment character.
The attribute is defined in the Exchange Table Model (which see for details). It cannot be specified in reStructuredText and is ignored by Docutils.
charoff
Attribute type: NMTOKEN. Default value: "50" (i.e. 50%).
The charoff attribute is used in <colspec> and <entry> elements to specify the horizontal offset of the alignment character when align is "char".
The attribute is defined in the Exchange Table Model (which see for details). It cannot be specified in reStructuredText and is ignored by Docutils.
colname
Attribute type: NMTOKEN. Default value: none.
Name (identifier) of a table column.
The colname attribute is used in the <colspec> element name a table column and in the <entry> element to reference a named column.
The attribute is defined in the Exchange Table Model (which see for details). It cannot be specified in reStructuredText and is ignored by Docutils.
colnum
Attribute type: NMTOKEN. Default value: none.
The colnum attribute is used in the <colspec> element. The attribute is defined in the Exchange Table Model (which see for details). It serves no functional purpose other than a consistency check.
cols
Attribute type: NMTOKEN. Default value: none.
The cols attribute is used in the <tgroup> element. It stores the number of columns in a table group.
The attribute is defined in the Exchange Table Model (which see for details).
colsep
Attribute type: %yesorno. Default value: none.
The colsep attribute is used in the <colspec>, <entry>, <table>, and <tgroup> elements to specify the presence or absence of a column separator (vertical ruling).
The attribute is defined in the Exchange Table Model (which see for details). It cannot be specified in reStructuredText and is ignored by Docutils.
colwidth
Attribute type: CDATA. Default value: "1*" (sic!)
Column width specification used in the <colspec> element.
Either proportional measure of the form number*, e.g., “5*” for 5 times the proportion, or “*” (which is equivalent to “1*”); fixed measure, e.g., 2pt for 2 point, 3pi for 3 pica.
The fixed unit values are case insensitive. The standard list of allowed unit values is “pt” (points), “cm” (centimeters), “mm” (millimeters), “pi” (picas), and “in” (inches). The default fixed unit should be interpreted as “pt” if neither a proportion nor a fixed unit is specified.
Defined in the Exchange Table Model.
delimiter
Attribute type: CDATA. Default value: none.
The delimiter attribute is used in the <option_argument> element and 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 " ").
dupnames
Attribute type: %refnames.type. Default value: none.
dupnames is one of the common attributes, shared by all Docutils elements. It replaces the names attribute when there has been a naming conflict.
enumtype
Attribute type: EnumeratedType, one of "arabic", "loweralpha", "upperalpha", "lowerroman", or "upperroman". Default value: none.
The enumtype attribute is used in the <enumerated_list> element to record the intended enumeration sequence.
- Supported values:
- arabic:
1, 2, 3, ...
- loweralpha:
a, b, c, ..., z
- upperalpha:
A, B, C, ..., Z
- lowerroman:
i, ii, iii, iv, ..., mmmmcmxcix [4999]
- upperroman:
I, II, III, IV, ..., MMMMCMXCIX [4999]
format
Attribute type: NMTOKENS. Default value: none.
The format attribute is a string containing one or more space separated output format names.
The format attribute is used in the <raw> element.
frame
The frame attribute may be used in the <table> element to specify the table's outer frame.
The attribute is defined in the Exchange Table Model (which see for details). It cannot be specified in reStructuredText and is ignored by Docutils.
height
Attribute type: %measure. Default value: none.
The height attribute is used in the <image> element.
ids
Attribute type: %ids.type. Default value: none.
The ids attribute is a space separated list containing one or more unique identifiers, typically assigned by the system.
ids is one of the common attributes, shared by all Docutils elements.
level
Attribute type: %number. Default value: none.
The level attribute is used in the <system_message> element to indicate the message's severity level. See also the "type" attribute.
line
Attribute type: %number. Default value: none.
The line attribute is used in the <system_message> element to indicate the position of the reported problem in the document source. See also the source attribute.
ltrim
Attribute type: %yesorno. Default value: none (implies no).
The ltrim attribute is used in the <substitution_definition> element.
loading
Attribute type: EnumeratedType, one of "embed", "link", or "lazy". Default value: none.
The loading attribute is used in the <image> element to indicate the preferred handling by the Docutils writer. [12] The default depends on the writer and the image_loading configuration setting.
New in Docutils 0.21
morecols
Attribute type: %number. Default value: none.
The morecols attribute is used in the <entry> element to specify an entry that spans several physical table columns. It is similar to the colspan attribute of HTML table cells (<th> and <td>).
The morecols attribute is defined in the %tbl.entry.att parameter entity extending the Exchange Table Model.
morerows
Attribute type: %number. Default value: none.
The morerows attribute is used in the <entry> element to specify an entry that spans several physical table rows. It is similar to the rowspan attribute of HTML table cells (<th> and <td>).
The attribute is defined in the Exchange Table Model (which see for details).
name
Attribute type: NMTOKEN or CDATA. Default value: none.
The name attribute in the <meta> element accepts NMTOKEN values. The output format may limit valid values to a set of keywords (EnumeratedType).
The name attribute in the <reference> element holds the reference name of the referenced element. Whitespace is normalized but case is preserved. The attribute will no longer be used with <reference> elements in Docutils 1.0.
names
Attribute type: %refnames.type. Default value: none.
The names attribute is a space-separated list containing reference names of an element. Spaces inside a name are backslash-escaped.
Each name in the list 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.
namest
Attribute type: NMTOKEN. Default value: none.
The namest attribute is used in the <entry> element to specify the leftmost column of a span.
The attribute is defined in the Exchange Table Model (which see for details). It is ignored by Docutils which uses the morecols attribute instead.
nameend
Attribute type: NMTOKEN. Default value: none.
The nameend attribute is used in the <entry> element to specify the rightmost column of a span.
The attribute is defined in the Exchange Table Model (which see for details). It is ignored by Docutils which uses the morecols attribute instead.
pgwide
Attribute type: %yesorno. Default value: none (implies no).
The pgwide attribute is used in the <table> element to make the table span the full page width.
The attribute is defined in the Exchange Table Model (which see for details). It cannot be specified in reStructuredText and is ignored by Docutils.
prefix
Attribute type: CDATA. Default value: none.
The prefix attribute is used in the <enumerated_list> element to store the formatting characters used before the enumerator.
In documents originating from reStructuredText data, it will contain either "" (empty string) or "(" (left parenthesis). Writers may ignore this attribute.
refid
Attribute type: %idref.type. Default value: none.
The refid attribute contains a reference to another element via its identifier.
refid is used by the <citation_reference>, <footnote_reference>, <problematic>, <reference>, <target>, and <title> elements (via the %refid.att and %reference.atts parameter entities).
refname
Attribute type: %refname.type. Default value: none.
The refname attribute contains a reference to one of the names of another element.
refname is used by the <citation_reference>, <footnote_reference>, <reference>, <substitution_reference>, and <target> elements. [13]
On a <target> element, refname indicates an indirect target which may resolve to either an internal or external reference. Docutils transforms replace the refname attribute with a refid pointing to the same element.
refuri
Attribute type: CDATA. Default value: none.
The refuri attribute contains an external reference to a URI. It is used by the <target>, <reference>, <footnote_reference>, and <citation_reference> elements (via the %reference.atts parameter entity).
rowsep
Attribute type: %yesorno. Default value: none (implies no).
The rowsep attribute may be used in the <colspec>, <entry>, <row>, <table>, and <tgroup> elements to specify the presence or absence of row separators (horizontal ruling).
The attribute is defined in the Exchange Table Model (which see for details). It cannot be specified in reStructuredText and is ignored by Docutils.
rtrim
Attribute type: %yesorno. Default value: none (implies no).
The rtrim attribute is used in the <substitution_definition> element.
scale
Attribute type: %number. Default value: none.
The scale attribute is used in the <image> element to store a uniform scaling factor (integer percentage value).
source
Attribute type: CDATA. Default value: none.
The source attribute stores the path, URI, or a description of the source that was used to produce the document tree. [14]
source is one of the common attributes but typically only used with the <document> and <system_message> elements.
start
Attribute type: %number. Default value: none (implies 1).
The start attribute is used in the <enumerated_list> element to store the ordinal value of the first item in the list, in decimal notation.
For lists beginning at value 1 ("1", "a", "A", "i", or "I"), this attribute may be omitted.
stub
Attribute type: %yesorno. Default value: none.
The stub attribute is used in the <colspec> element to mark a table column as containing stubs (row titles, on the left). See also the "csv-table" and "list-table" directives.
The attribute is defined in the %tbl.colspec.att parameter entity extending the Exchange Table Model.
suffix
Attribute type: CDATA. Default value: none.
The suffix attribute is used in the <enumerated_list> element to store 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.
title
Attribute type: CDATA. Default value: none.
The title attribute stores the metadata title of a <document>. It is set by the "title" directive or the DocTitle transform. This title is typically not part of the rendered document. It is, for example, used as HTML <title> element and shown in a browser's title bar, in a user's history or bookmarks, or in search results.
type
Attribute type: NMTOKEN. Default value: none.
The type attribute is used in the <system_message> element. It holds the name of the message's severity level (cf. the "level" attribute).
uri
Attribute type: CDATA. Default value: none.
The uri attribute is used in the <image> and <figure> elements to refer to the image via a URI Reference [15]. [rfc3986]
valign
The valign attribute is used in the <entry>, <row>, <tbody>, and <thead> elements to specify the vertical text alignment within entries.
The attribute is defined in the Exchange Table Model (which see for details). It cannot be specified in reStructuredText and is ignored by Docutils.
width
Attribute type: %measure. Default value: none.
The width attribute is used in the <figure>, <image>, and <table> elements.
xml:space
The xml:space attribute is a standard XML attribute for whitespace-preserving elements. It is used by the <address>, <comment>, <doctest_block>, <literal_block>, <math_block>, 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.
Parameter Entity Reference
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. Empty placeholder entities whose names begin with "additional" are provided to allow easy extension by wrapper DTDs.
In addition, the Docutils DTD defines parameter entities for custom attribute types.
Attribute Entities
%align-h.att
The %align-h.att parameter entity contains the align attribute for horizontal alignment.
Entity definition:
align (left | center | right) #IMPLIED
The <figure> and <table> elements directly employ the %align-h.att parameter entity in their attribute lists.
%align-hv.att
The %align-hv.att parameter entity contains the align attribute for horizontal and vertical alignment.
Entity definition:
align (top | middle | bottom | left | center | right) #IMPLIED
The <image> element directly employs the %align-hv.att parameter entity in its attribute list.
%anonymous.att
The %anonymous.att parameter entity contains the anonymous attribute, used for unnamed hyperlinks.
Entity definition:
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:
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:
backrefs %idrefs.type; #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 the common attributes.
Entity definition:
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.
%bodyatt
The %bodyatt parameter entity is defined in the Exchange Table Model to allow customization of the <table> element's attribute list.
The Docutils DTD redefines it to add align, width, and the common attributes.
%fixedspace.att
The %fixedspace.att parameter entity contains the xml:space attribute, a standard XML attribute for whitespace-preserving elements.
Entity definition:
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>, <literal_block>, <math_block>, <raw>.
%reference.atts
The %reference.atts parameter entity groups together the refuri, refid, and refname attributes.
Entity definition:
%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:
refid %idref.type; #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:
refname %refname.type; #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.
Entity definition:
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.
%tbl.colspec.att
The %tbl.colspec.att parameter entity is defined in the Exchange Table Model to allow customization of the <colspec> element's attribute list.
The Docutils DTD redefines it to add stub and the common attributes.
%tbl.entry.att
The %tbl.entry.att parameter entity is defined in the Exchange Table Model to allow customization of the <entry> element's attribute list.
The Docutils DTD redefines it to add morecols and the common attributes.
%tbl.row.att
The %tbl.row.att parameter entity is defined in the Exchange Table Model to allow customization of the <row> element's attribute list.
The Docutils DTD redefines it to add the common attributes.
%tbl.tbody.att
The %tbl.tbody.att parameter entity is defined in the Exchange Table Model to allow customization of the <tbody> element's attribute list.
The Docutils DTD redefines it to add the common attributes.
%tbl.tgroup.att
The %tbl.tgroup.att parameter entity is defined in the Exchange Table Model to allow customization of the <tgroup> element's attribute list.
The Docutils DTD redefines it to add the common attributes.
%tbl.thead.att
The %tbl.thead.att parameter entity is defined in the Exchange Table Model to allow customization of the <thead> element's attribute list.
The Docutils DTD redefines it to add the common attributes.
Element Category Entities
%bibliographic.elements
The %bibliographic.elements parameter entity contains an OR-list of all 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.
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>, and <warning>
Via %structure.model, the %body.elements parameter entity is indirectly employed in the content models of the <document> and <section> elements.
%inline.elements
The %inline.elements parameter entity contains an OR-list of all Inline Elements.
The %additional.inline.elements parameter entity can be used by wrapper DTDs to extend %inline.elements.
The %inline.elements parameter entity is employed in the %text.model parameter entity.
%section.elements
The %section.elements parameter entity contains the <section> element.
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.
Model Entities
%calstblx
The %calstblx parameter entity is used to include the XML Exchange Table Model DTD [tm9901] as external DTD subset defining the table elements <colspec>, <entry>, <row>, <table>, <tbody>, <tgroup>, and <thead>.
Entity definition:
<!ENTITY % calstblx PUBLIC
"-//OASIS//DTD XML Exchange Table Model 19990315//EN"
"soextblx.dtd">
%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.
Simplified entity definition:
( ( %body.elements; | topic | sidebar | transition )*, ( %section.elements; | transition )* )
Each <document> or <section> contains zero or more body elements, topics, sidebars, or transitions, followed by zero or more sections (whose contents include this model), or transitions.
The actual entity definition is more complex,
( ( (%body.elements; | topic | sidebar)+, transition? )*,
( (%section.elements;),
(transition?, (%section.elements;) )* )? )
to impose the following restrictions:
A <transition> may not be the first element (i.e. it may not occur at the beginning of a document or directly after a title, subtitle, meta or decoration element).
Transitions must be separated by other elements (body elements, sections, etc.). In other words, a transition may not be immediately adjacent to another transition.
An additional restriction cannot be expressed in the language of DTDs: [16]
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.
%tbl.entry.mdl
The %tbl.entry.mdl parameter entity is defined in the Exchange Table Model to allow customization of the <entry> element's content model.
The Docutils DTD changes it to allow all body elements (including nested tables):
(%body.elements;)*
%tbl.tgroup.mdl
The %tbl.tgroup.mdl parameter entity is defined in the Exchange Table Model to allow customization of the <tgroup> element's content model.
The Docutils DTD changes it to require at least one <colspec> element:
colspec+,thead?,tbody
%text.model
The %text.model parameter entity is used by simple elements to represent text data mixed with inline elements.
Entity definition:
(#PCDATA | %inline.elements;)*
The %text.model parameter entity is directly employed in the content models of the following elements: <abbreviation>, <acronym>, <address>, <attribution>, <author>, <caption>, <classifier>, <contact>, <copyright>, <date>, <doctest_block>, <emphasis>, <field_name>, <generated>, <inline>, <line>, <literal>, <literal_block>, <organization>, <paragraph>, <problematic>, <reference>, <revision>, <rubric>, <status>, <strong>, <subscript>, <substitution_definition>, <substitution_reference>, <subtitle>, <superscript>, <target>, <term>, <title>, <title_reference>, <version>
Bibliography
DocBook 5.1: The Definitive Guide, Norman Walsh, https://tdg.docbook.org/tdg/5.1/.
HTML Living Standard, WHATWG (Apple, Google, Mozilla, Microsoft), https://html.spec.whatwg.org.
Berners-Lee, T., Fielding, R., and L. Masinter, Uniform Resource Identifier (URI): Generic Syntax, STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, https://www.rfc-editor.org/info/rfc3986.
XML Exchange Table Model DTD, OASIS Technical Memorandum 9901:1999, http://www.oasis-open.org/html/tm9901.html.
Extensible Markup Language (XML) 1.0, W3C Recommendation, https://www.w3.org/TR/xml/.