| Author: | David Goodger |
|---|---|
| Contact: | docutils-develop@lists.sourceforge.net |
| Revision: | 9080 |
| Date: | 2022-06-19 |
| Copyright: | This document has been placed in the public domain. |
Contents
This document describes the XML data structure of Docutils documents: the relationships and semantics of elements and attributes. The Docutils document structure is formally defined by the Docutils Generic DTD XML document type definition, docutils.dtd, which is the definitive source for details of element structural relationships.
This document does not discuss implementation details. Those can be found in internal documentation (docstrings) for the docutils.nodes module, where the document tree data structure is implemented in a class library.
The reader is assumed to have some familiarity with XML or SGML, and an understanding of the data structure meaning of "tree". For a list of introductory articles, see Introducing the Extensible Markup Language (XML).
The reStructuredText markup is used for illustrative examples throughout this document. For a gentle introduction, see A ReStructuredText Primer. For complete technical details, see the reStructuredText Markup Specification.
Below is a simplified diagram of the hierarchy of elements in the Docutils document tree structure. An element may contain any other elements immediately below it in the diagram. Notes are written in square brackets. Element types in parentheses indicate recursive or one-to-many relationships; sections may contain (sub)sections, tables contain further body elements, etc.
+--------------------------------------------------------------------+ | document [may begin with a title, subtitle, decoration, docinfo] | | +--------------------------------------+ | | sections [each begins with a title] | +-----------------------------+-------------------------+------------+ | [body elements:] | (sections) | | | - literal | - lists | | - hyperlink +------------+ | | blocks | - tables | | targets | | para- | - doctest | - block | foot- | - sub. defs | | graphs | blocks | quotes | notes | - comments | +---------+-----------+----------+-------+--------------+ | [text]+ | [text] | (body elements) | [text] | | (inline +-----------+------------------+--------------+ | markup) | +---------+
The Docutils document model uses a simple, recursive model for section structure. A document node may contain body elements and section elements. Sections in turn may contain body elements and sections. The level (depth) of a section element is determined from its physical nesting level; unlike other document models (<h1> in HTML, <sect1> in DocBook, <div1> in XMLSpec) the level is not incorporated into the element name.
The Docutils document model uses strict element content models. Every element has a unique structure and semantics, but elements may be classified into general categories (below). Only elements which are meant to directly contain text data have a mixed content model, where text data and inline elements may be intermixed. This is unlike the much looser HTML document model, where paragraphs and text data may occur at the same level.
Structural elements may only contain child elements; they do not directly contain text data. Structural elements may contain body elements or further structural elements. Structural elements can only be child elements of other structural elements.
Category members: document, section, topic, sidebar
Structural subelements are child elements of structural elements. Simple structuctural subelements (title, subtitle) contain text data; the others are compound and do not directly contain text data.
Category members: title, subtitle, decoration, docinfo, meta, transition
The docinfo element is an optional child of document. It groups bibliographic elements together. All bibliographic elements except authors and field contain text data. authors contains further bibliographic elements (most notably author). field contains field_name and field_body body subelements.
Category members: address, author, authors, contact, copyright, date, field, organization, revision, status, version
The decoration element is also an optional child of document. It groups together elements used to generate page headers and footers.
Body elements are contained within structural elements and compound body elements. There are two subcategories of body elements: simple and compound.
Category members: admonition, attention, block_quote, bullet_list, caution, citation, comment, compound, container, danger, definition_list, doctest_block, enumerated_list, error, field_list, figure, footnote, hint, image, important, line_block, literal_block, note, option_list, paragraph, pending, raw, rubric, substitution_definition, system_message, table, target, tip, warning
Simple body elements are empty or directly contain text data. Those that contain text data may also contain inline elements. Such elements therefore have a "mixed content model".
Category members: comment, doctest_block, image, literal_block, math_block, paragraph, pending, raw, rubric, substitution_definition, target
Compound body elements contain local substructure (body subelements) and further body elements. They do not directly contain text data.
Category members: admonition, attention, block_quote, bullet_list, caution, citation, compound, container, danger, definition_list, enumerated_list, error, field_list, figure, footnote, hint, important, line_block, note, option_list, system_message, table, tip, warning
Compound body elements contain specific subelements (e.g. bullet_list contains list_item). Subelements may themselves be compound elements (containing further child elements, like field) or simple data elements (containing text data, like field_name). These subelements always occur within specific parent elements, never at the body element level (beside paragraphs, etc.).
Category members (simple): attribution, caption, classifier, colspec, field_name, label, line, option_argument, option_string, term
Category members (compound): definition, definition_list_item, description, entry, field, field_body, legend, list_item, option, option_group, option_list_item, row, tbody, tgroup, thead
Inline elements directly contain text data, and may also contain further inline elements. Inline elements are contained within simple body elements. Most inline elements have a "mixed content model".
Category members: abbreviation, acronym, citation_reference, emphasis, footnote_reference, generated, image, inline, literal, math, problematic, reference, strong, subscript, substitution_reference, superscript, target, title_reference, raw
Each element in the DTD (document type definition) is described in its own section below. Each section contains an introduction plus the following subsections:
Details (of element relationships and semantics):
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.
The abbreviation element is an inline element used to represent an abbreviation being used in the document. An example of an abbreviation is 'St' being used instead of 'Street'.
| Category: | |
|---|---|
| Analogues: | abbreviation is analogous to the HTML "abbr" element. |
| Parents: | All elements employing the %inline.elements; 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. |
The abbreviation element is not exposed in default restructured text. It can only be accessed through custom roles.
Pseudo-XML example from a custom :abbr: role:
<paragraph>
<abbreviation explanation="Street">
St
is a common abbreviation for "street".
The address element holds the surface mailing address information for the author (individual or group) of the document, or a third-party contact address. Its structure is identical to that of the literal_block element: whitespace is significant, especially newlines.
| 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. |
|
reStructuredText source:
Document Title
==============
:Address: 123 Example Ave.
Example, EX
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<address>
123 Example Ave.
Example, EX
See docinfo for a more complete example, including processing context.
This element is a generic, titled admonition. Also see the specific admonition elements Docutils offers (in alphabetical order): caution, danger, error, hint, important, note, tip, warning.
| Category: | |
|---|---|
| Analogues: | admonition has no direct analogues in common DTDs. It can be emulated with primitives and type effects. |
| Processing: | Rendered distinctly (inset and/or in a box, etc.). |
| 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. (title_, (`%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. |
|
reStructuredText source:
.. admonition:: And, by the way... You can make up your own admonition too.
Pseudo-XML fragment from simple parsing:
<admonition class="admonition-and-by-the-way">
<title>
And, by the way...
<paragraph>
You can make up your own admonition too.
The attention element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): caution, danger, error, hint, important, note, tip, warning, and the generic admonition.
| 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. (%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. |
|
reStructuredText source:
.. Attention:: All your base are belong to us.
Pseudo-XML fragment from simple parsing:
<attention>
<paragraph>
All your base are belong to us.
The author element holds the name of the author of the document.
| Category: | |
|---|---|
| Analogues: | author is analogous to the DocBook "author" element. |
| Processing: | See docinfo. |
| Parents: | |
| Children: | author elements may contain text data plus inline elements. %text.model; |
| Attributes: | The author element contains only the common attributes. |
| Parameter Entities: | |
The %bibliographic.elements; parameter entity directly includes author. |
|
reStructuredText source:
Document Title ============== :Author: J. Random Hacker
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<author>
J. Random Hacker
See docinfo for a more complete example, including processing context.
The authors element is a container for author information for documents with multiple authors.
| Category: | |
|---|---|
| Analogues: | authors is analogous to the DocBook "authors" element. |
| Processing: | See docinfo. |
| Parents: | Only the docinfo element contains authors. |
| Children: | authors elements may contain the following elements: author, organization, address, contact: ((author, organization?, address?, contact?)+) |
| Attributes: | The authors element contains only the common attributes. |
| Parameter Entities: | |
The %bibliographic.elements; parameter entity directly includes authors. |
|
reStructuredText source:
Document Title ============== :Authors: J. Random Hacker; Jane Doe
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<authors>
<author>
J. Random Hacker
<author>
Jane Doe
In reStructuredText, multiple author's names are separated with semicolons (";") or commas (","); semicolons take precedence. There is currently no way to represent the author's organization, address, or contact in a reStructuredText "Authors" field.
See docinfo for a more complete example, including processing context.
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. ((%body.elements;)+, attribution?) |
| 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. |
|
reStructuredText source:
As a great paleontologist once said,
This theory, that is mine, is mine.
-- Anne Elk (Miss)
Pseudo-XML fragment from simple parsing:
<paragraph>
As a great paleontologist once said,
<block_quote>
<paragraph>
This theory, that is mine, is mine.
<attribution>
Anne Elk (Miss)
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 and to the DocBook "itemizedlist" element. HTML's "ul" is short for "unordered list", which we consider to be a misnomer. "Unordered" implies that the list items may be randomly rearranged without affecting the meaning of the list. Bullet lists are often ordered; the ordering is simply left implicit. |
| Processing: | Each list item should begin a new vertical block, prefaced by a bullet/dingbat. |
| 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: (list_item_+) |
| Attributes: | The bullet_list element contains the common attributes plus bullet. bullet is used to record the style of bullet from the input data. In documents processed from reStructuredText, it contains one of "-", "+", or "*". It may be ignored in processing. |
| Parameter Entities: | |
The %body.elements; parameter entity directly includes bullet_list. The %structure.model; parameter entity indirectly includes bullet_list. |
|
reStructuredText source:
- Item 1, paragraph 1. Item 1, paragraph 2. - Item 2.
Pseudo-XML fragment from simple parsing:
<bullet_list bullet="-">
<list_item>
<paragraph>
Item 1, paragraph 1.
<paragraph>
Item 1, paragraph 2.
<list_item>
<paragraph>
Item 2.
See list_item for another example.
The caution element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, danger, error, hint, important, note, tip, warning, and the generic admonition.
| Category: | Compound Body Elements |
|---|---|
| Analogues: | caution is analogous to the DocBook "caution" element. |
| Processing: | Rendered distinctly (inset and/or in a box, etc.), with the generated title "Caution" (or similar). |
| 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. (%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. |
|
reStructuredText source:
.. Caution:: Don't take any wooden nickels.
Pseudo-XML fragment from simple parsing:
<caution>
<paragraph>
Don't take any wooden nickels.
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: | See definition_list_item. |
| 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. |
Here is a hypothetical data dictionary. reStructuredText source:
name : string
Customer name.
i : int
Temporary index variable.
Pseudo-XML fragment from simple parsing:
<definition_list>
<definition_list_item>
<term>
name
<classifier>
string
<definition>
<paragraph>
Customer name.
<definition_list_item>
<term>
i
<classifier>
int
<definition>
<paragraph>
Temporary index variable.
Specifications for a column in a table.
| Category: | Body Subelements (simple) |
|---|---|
| Analogues: | colspec is based on the [exchange-table-model] and analogous to the DocBook "colspec" element. |
| Processing: | The colspec element contains layout information for the parent table. |
| Parents: | Only the tgroup element contains colspec. |
| Children: | colspec is an empty element and has no children. |
| Attributes: | The colspec element contains the optional "colnum", "colname", "colwidth", "colsep", "rowsep", "align", "char", and "charoff" attributes defined in the exchange-table-model plus the common attributes and stub. Docutils uses only colwidth and stub. Attention! In contrast to the definition in the exchange-table-model, unitless values of the "colwidth" are interpreted as proportional values, not fixed values with unit "pt". Future versions of Docutils may use the standard form number*, e.g., “5*” for 5 times the proportion. |
See table.
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. |
|
reStructuredText source:
Document Title ============== :Contact: jrh@example.com
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<contact>
<reference refuri="mailto:jrh@example.com">
jrh@example.com
See docinfo for a more complete example, including processing context.
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. |
|
reStructuredText source:
Document Title ============== :Copyright: This document has been placed in the public domain.
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<copyright>
This document has been placed in the public domain.
See docinfo for a more complete example, including processing context.
The danger element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, error, hint, important, note, tip, warning, and the generic admonition.
| 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. (%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. |
|
reStructuredText source:
.. DANGER:: Mad scientist at work!
Pseudo-XML fragment from simple parsing:
<danger>
<paragraph>
Mad scientist at work!
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. |
|
reStructuredText source:
Document Title ============== :Date: 2002-08-20
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<date>
2002-08-20
See docinfo for a more complete example, including processing context.
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. Equivalents are typically constructed from primitives and/or generated by the processing system. |
| Processing: | See the individual decorative elements. |
| Parents: | Only the document element contains decoration. |
| Children: | decoration elements may contain decorative elements. (header?, footer?) |
Although the content model doesn't specifically require contents, no empty decoration elements are ever created.
| Attributes: | The decoration element contains only the common attributes. |
|---|
reStructuredText source:
A paragraph.
Complete pseudo-XML result after parsing and applying transforms, assuming that the datestamp command-line option or configuration setting has been supplied:
<document>
<decoration>
<footer>
<paragraph>
Generated on: 2002-08-20.
<paragraph>
A paragraph.
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: | See definition_list_item. |
| Parents: | Only definition_list_item elements contain definition. |
| Children: | definition elements contain body elements. (%body.elements;)+ |
| Attributes: | The definition element contains only the common attributes. |
See the examples for the definition_list, definition_list_item, and classifier elements.
The definition_list element contains a list of terms and their definitions. It can be used for glossaries or dictionaries, to describe or classify things, for dialogues, or to itemize subtopics (such as in this reference).
| Category: | Compound Body Elements |
|---|---|
| Parents: | All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain definition_list. |
| Children: | definition_list elements contain one or more definition_list_item elements. |
| Analogues: | definition_list is analogous to the HTML "dl" element and to the DocBook "variablelist" element. |
| Processing: | See definition_list_item. |
| 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. | |
reStructuredText source:
Term
Definition.
Term : classifier
The ' : ' indicates a classifier in
definition list item terms only.
Pseudo-XML fragment from simple parsing:
<definition_list>
<definition_list_item>
<term>
Term
<definition>
<paragraph>
Definition.
<definition_list_item>
<term>
Term
<classifier>
classifier
<definition>
<paragraph>
The ' : ' indicates a classifier in
definition list item terms only.
See definition_list_item and classifier for further examples.
The definition_list_item element contains a single term/definition pair (with optional classifier).
| Category: | Body Subelements (compound) |
|---|---|
| Analogues: | definition_list_item is analogous to the DocBook "variablelistentry" element. |
| Processing: | The optional classifier can be rendered differently from the term. They should be separated visually, typically by spaces plus a colon or dash. |
| Parents: | Only the definition_list element contains definition_list_item. |
| Children: | definition_list_item elements each contain a single term, an optional classifier, and a definition: (term, classifier?, definition) |
| Attributes: | The definition_list_item element contains only the common attributes. |
reStructuredText source:
Tyrannosaurus Rex : carnivore
Big and scary; the "Tyrant King".
Brontosaurus : herbivore
All brontosauruses are thin at one end,
much much thicker in the middle
and then thin again at the far end.
-- Anne Elk (Miss)
Pseudo-XML fragment from simple parsing:
<definition_list>
<definition_list_item>
<term>
Tyrannosaurus Rex
<classifier>
carnivore
<definition>
<paragraph>
Big and scary; the "Tyrant King".
<definition_list_item>
<term>
Brontosaurus
<classifier>
herbivore
<definition>
<paragraph>
All brontosauruses are thin at one end,
much much thicker in the middle
and then thin again at the far end.
<paragraph>
-- Anne Elk (Miss)
See definition_list and classifier for further examples.
The description element contains body elements, describing the purpose or effect 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. (%body.elements;)+ |
| Attributes: | The description element contains only the common attributes. |
See the examples for the option_list element.
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.
See also the meta element (for "hidden" meta-data).
| Category: | |
|---|---|
| Analogues: | docinfo is analogous to DocBook "info" elements ("bookinfo" etc.). There are no directly analogous HTML elements; the "meta" element carries some of the same information, albeit invisibly. |
| Processing: | The docinfo element may be rendered as a two-column table or in other styles. It may even be invisible or omitted from the processed output. Meta-data may be extracted from docinfo children; for example, HTML <meta> tags may be constructed. When Docutils transforms a reStructuredText field_list into a docinfo element (see the examples below), RCS/CVS keywords are normally stripped from simple (one paragraph) field bodies. For complete details, please see RCS Keywords in the reStructuredText Markup Specification. |
| Parents: | Only the document element contains docinfo. |
| Children: | docinfo elements contain bibliographic elements. (%bibliographic.elements;)+ |
| Attributes: | The docinfo element contains only the common attributes. |
Docinfo is represented in reStructuredText by a field_list in a bibliographic context: the first non-comment element of a document, after any document title/subtitle. The field list is transformed into a docinfo element and its children by a transform. Source:
Docinfo Example =============== :Author: J. Random Hacker :Contact: jrh@example.com :Date: 2002-08-18 :Status: Work In Progress :Version: 1 :Filename: $RCSfile$ :Copyright: This document has been placed in the public domain.
Complete pseudo-XML result after parsing and applying transforms:
<document ids="docinfo-example" names="docinfo example">
<title>
Docinfo Example
<docinfo>
<author>
J. Random Hacker
<contact>
<reference refuri="mailto:jrh@example.com">
jrh@example.com
<date>
2002-08-18
<status>
Work In Progress
<version>
1
<field>
<field_name>
Filename
<field_body>
<paragraph>
doctree.txt
<copyright>
This document has been placed in the public domain.
Note that "Filename" is a non-standard docinfo field, so becomes a generic field element. Also note that the "RCSfile" keyword syntax has been stripped from the "Filename" data.
See field_list for an example in a non-bibliographic context. Also see the individual examples for the various bibliographic elements.
The doctest_block element is a Python-specific variant of literal_block. It is a block of text where line breaks and whitespace are significant and must be preserved. doctest_block elements are used for interactive Python interpreter sessions, which are distinguished by their input prompt: >>>. They are meant to illustrate usage by example, and provide an elegant and powerful testing environment via the doctest module in the Python standard library.
| 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. |
|
reStructuredText source:
This is an ordinary paragraph. >>> print 'this is a Doctest block' this is a Doctest block
Pseudo-XML fragment from simple parsing:
<paragraph>
This is an ordinary paragraph.
<doctest_block xml:space="preserve">
>>> print 'this is a Doctest block'
this is a Doctest block
The document element is the root (topmost) element of the Docutils document tree. document is the direct or indirect ancestor of every other element in the tree. It encloses the entire document tree. It is the starting point for a document.
| 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 subelements, structural elements, and body elements. ( (title, subtitle?)?, decoration?, (docinfo, transition?)?, %structure.model; ) |
Depending on the source of the data and the stage of processing, the "document" may not initially contain a "title". A document title is not directly representable in reStructuredText. Instead, a lone top-level section may have its title promoted to become the document title, and similarly for a lone second-level (sub)section's title to become the document subtitle.
The contents of "decoration" may be specified in a document, constructed programmatically, or both. The "docinfo" may be transformed from an initial field_list.
See the %structure.model; parameter entity for details of the body of a document.
| Attributes: | The document element contains the common attributes (ids, names, dupnames, source, and classes), plus an optional title attribute which stores the document title metadata. |
|---|
reStructuredText source:
A Title ======= A paragraph.
Complete pseudo-XML result from simple parsing:
<document>
<section ids="a-title" names="a title">
<title>
A Title
<paragraph>
A paragraph.
After applying transforms, the section title is promoted to become the document title:
<document ids="a-title" names="a title">
<title>
A Title
<paragraph>
A paragraph.
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: (list_item+) |
| Attributes: | The enumerated_list element contains the common attributes plus enumtype, prefix, suffix, and start. enumtype is used to record the intended enumeration sequence, one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z), "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ..., mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ..., MMMMCMXCIX [4999]). prefix stores the formatting characters used before the enumerator. In documents originating from reStructuredText data, it will contain either "" (empty string) or "(" (left parenthesis). It may or may not affect processing. suffix stores the formatting characters used after the enumerator. In documents originating from reStructuredText data, it will contain either "." (period) or ")" (right parenthesis). Depending on the capabilities of the output format, this attribute may or may not affect processing. start contains the ordinal value of the first item in the list, in decimal. For lists beginning at value 1 ("1", "a", "A", "i", or "I"), this attribute may be omitted. |
| Parameter Entities: | |
The %body.elements; parameter entity directly includes enumerated_list. The %structure.model; parameter entity indirectly includes enumerated_list. |
|
reStructuredText source:
1. Item 1. (A) Item A. (B) Item B. (C) Item C. 2. Item 2.
Pseudo-XML fragment from simple parsing:
<enumerated_list enumtype="arabic" prefix="" suffix=".">
<list_item>
<paragraph>
Item 1.
<enumerated_list enumtype="upperalpha" prefix="(" suffix=")">
<list_item>
<paragraph>
Item A.
<list_item>
<paragraph>
Item B.
<list_item>
<paragraph>
Item C.
<list_item>
<paragraph>
Item 2.
See list_item for another example.
The error element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, danger, hint, important, note, tip, warning, and the generic admonition.
| 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. (%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. |
|
reStructuredText source:
.. Error:: Does not compute.
Pseudo-XML fragment from simple parsing:
<error>
<paragraph>
Does not compute.
The field element contains a pair of field_name and field_body elements.
| Category: | |
|---|---|
| Analogues: | field has no direct analogues in common DTDs. |
| 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: (field_name, field_body) |
| Attributes: | The field element contains only the common attributes. |
| Parameter Entities: | |
The %bibliographic.elements; parameter entity directly includes field. |
|
See the examples for the field_list and docinfo elements.
The field_body element contains body elements. It is analogous to a database field's data.
| Category: | |
|---|---|
| Analogues: | field_body has no direct analogues in common DTDs. |
| Processing: | See field_list. |
| Parents: | Only the field element contains field_body. |
| Children: | field_body elements may contain body elements. (%body.elements;)* |
| Attributes: | The field_body element contains only the common attributes. |
See the examples for the field_list and docinfo elements.
The field_list element contains two-column table-like structures resembling database records (label & data pairs). Field lists are often meant for further processing. In reStructuredText, field lists are used to represent bibliographic fields (contents of the docinfo element) and directive options.
| Category: | |
|---|---|
| Analogues: | field_list has no direct analogues in common DTDs. It can be emulated with primitives such as tables. |
| Processing: | A field_list is typically rendered as a two-column list, where the first column contains "labels" (usually with a colon suffix). However, field lists are often used for extension syntax or special processing. Such structures do not survive as field lists to be rendered. |
| 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. (field+) |
| 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. |
|
reStructuredText source:
:Author: Me :Version: 1 :Date: 2001-08-11 :Parameter i: integer
Pseudo-XML fragment from simple parsing:
<field_list>
<field>
<field_name>
Author
<field_body>
<paragraph>
Me
<field>
<field_name>
Version
<field_body>
<paragraph>
1
<field>
<field_name>
Date
<field_body>
<paragraph>
2001-08-11
<field>
<field_name>
Parameter i
<field_body>
<paragraph>
integer
The field_name element contains text; it is analogous to a database field's name.
| Category: | Body Subelements (simple) |
|---|---|
| Analogues: | field_name has no direct analogues in common DTDs. |
| 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. |
See the examples for the field_list and docinfo elements.
The footnote element is used for labeled 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 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 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. |
|
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.
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 i square brackets. |
| Parents: | All elements employing the %inline.elements; parameter entities in their content models may contain footnote-reference. |
| Children: | footnote_reference elements may contain text data. (#PCDATA) |
| Attributes: | The footnote_reference element contains the common attributes plus auto, refid, and refname. |
reStructuredText source fragment:
[#]_ 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.
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.
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. (%body.elements;)+ |
| Attributes: | The header element contains only the common attributes. |
reStructuredText source fragment:
.. header:: This space for rent.
Pseudo-XML fragment from simple parsing:
<document>
<decoration>
<header>
<paragraph>
This space for rent.
The hint element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, danger, error, important, note, tip, warning, and the generic admonition.
| 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. (%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. |
|
reStructuredText source:
.. Hint:: It's bigger than a bread box.
Pseudo-XML fragment from simple parsing:
<hint>
<paragraph>
It's bigger than a bread box.
| Attributes: | The image element contains the common attributes plus uri, align, alt, height, width, and scale. |
|---|
The important element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, danger, error, hint, note, tip, warning, and the generic admonition.
| Category: | Compound Body Elements |
|---|---|
| Analogues: | important is analogous to the DocBook "important" element. |
| Processing: | Rendered distinctly (inset and/or in a box, etc.), with the generated title "Important" (or similar). |
| 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. (%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. |
|
reStructuredText source:
.. Important:: * Wash behind your ears. * Clean up your room. * Back up your data. * Call your mother.
Pseudo-XML fragment from simple parsing:
<important>
<bullet_list>
<list_item>
<paragraph>
Wash behind your ears.
<list_item>
<paragraph>
Clean up your room.
<list_item>
<paragraph>
Back up your data.
<list_item>
<paragraph>
Call your mother.
The inline element is a generic inline container.
| Category: | |
|---|---|
| Analogues: | inline is analogous to the HTML "span" 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 classes attribute and render the content as ordinary text. |
| Parents: | All elements employing the %inline.elements; parameter entities in their content models may contain inline. |
| Children: | inline elements may contain text data plus inline elements. %text.model; |
| Attributes: | The inline element contains the common attributes. |
Custom interpreted text roles create inline elements (unless they are based on a standard role).
reStructuredText source fragment:
.. 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
The line element contains a single line of text, part of a line_block.
| Category: | Body Subelements (simple) |
|---|---|
| Parents: | Only the line_block element contains line. |
| Children: | line elements may contain text data plus inline elements. |
| Analogues: | line has no direct analogues in common DTDs. It can be emulated with primitives or type effects. |
| Processing: | See line_block. |
| Parents: | All elements employing the %inline.elements; parameter entities in their content models may contain inline. |
| Children: | inline elements may contain text data plus inline elements. %text.model; |
| Attributes: | The line element contains the common attributes. |
See line_block.
The line_block element contains a sequence of lines and nested line blocks. Line breaks (implied between elements) and leading whitespace (indicated by nesting) is significant and must be preserved. line_block elements are commonly used for verse and addresses. See literal_block for an alternative useful for program listings and interactive computer sessions.
| Category: | |
|---|---|
| Analogues: | line_block is analogous to the DocBook "literallayout" element and to the HTML "pre" element (with modifications to typeface styles). |
| Processing: | Unlike literal_block, line_block elements are typically rendered in an ordinary text typeface. It is crucial that leading whitespace and line breaks are preserved in the rendered form. |
| 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 the common attributes. |
| Parameter Entities: | |
The %body.elements; parameter entity directly includes line_block. The %structure.model; parameter entity indirectly includes line_block. |
|
Example source:
Take it away, Eric the Orchestra Leader! | A one, two, a one two three four | | Half a bee, philosophically, | must, *ipso facto*, half not be. | But half the bee has got to be, | *vis a vis* its entity. D'you see? | | But can a bee be said to be | or not to be an entire bee, | when half the bee is not a bee, | due to some ancient injury? | | Singing...
Pseudo-XML fragment from simple parsing:
<paragraph>
Take it away, Eric the Orchestra Leader!
<line_block>
<line>
A one, two, a one two three four
<line>
<line>
Half a bee, philosophically,
<line_block>
<line>
must,
<emphasis>
ipso facto
, half not be.
<line>
But half the bee has got to be,
<line_block>
<line>
<emphasis>
vis a vis
its entity. D'you see?
<line>
<line>
But can a bee be said to be
<line_block>
<line>
or not to be an entire bee,
<line_block>
<line>
when half the bee is not a bee,
<line_block>
<line>
due to some ancient injury?
<line>
<line>
Singing...
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. (%body.elements;)* |
| Attributes: | The list_item element contains only the common attributes. |
reStructuredText source:
1. Outer list, item 1. * Inner list, item 1. * Inner list, item 2. 2. Outer list, item 2.
Pseudo-XML fragment from simple parsing:
<enumerated_list enumtype="arabic" prefix="" suffix=".">
<list_item>
<paragraph>
Outer list, item 1.
<bullet_list bullet="*">
<list_item>
<paragraph>
Inner list, item 1.
<list_item>
<paragraph>
Inner list, item 2.
<list_item>
<paragraph>
Outer list, item 2.
See bullet_list or enumerated_list for further examples.
The literal_block element contains a block of text where line breaks and whitespace are significant and must be preserved. literal_block elements are commonly used for program listings and interactive computer sessions. See line_block for an alternative useful for verse and addresses.
| 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. |
|
reStructuredText source:
Here is a literal block::
if literal_block:
text = 'is left as-is'
spaces_and_linebreaks = 'are preserved'
markup_processing = None
Pseudo-XML fragment from simple parsing:
<paragraph>
Here is a literal block:
<literal_block xml:space="preserve">
if literal_block:
text = 'is left as-is'
spaces_and_linebreaks = 'are preserved'
markup_processing = None
The math element contains text in LaTeX math format [1] that is typeset as mathematical notation (inline formula).
If the output format does not support math typesetting, the content is inserted verbatim.
| Category: | |
|---|---|
| Analogues: | math is analogous to a MathML "math" element or the LaTeX ($ math $) mode. |
| Processing: | Rendered as mathematical notation. |
| Parents: | All elements employing the %inline.elements; parameter entities in their content models may contain math. |
| Children: | math elements may contain text data. %text.model; |
| Attributes: | The math element contains the common attributes. |
| [1] | (1, 2) For details of the supported mathematical language, see the "math" directive |
The math_block element contains a block of text in LaTeX math format [1] that is typeset as mathematical notation (display formula). The math_block element is generated during the initial parse from a "math" directive.
If the output format does not support math typesetting, the content is inserted verbatim.
| Category: | |
|---|---|
| Analogues: | math_block is analogous to a LaTeX "equation*" environment or a MathML "math" element displayed as block-level element. |
| Processing: | Rendered in a block as mathematical notation, typically centered or with indentation |
| Parents: | All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain math_block. |
| Children: | math_block elements may contain text data. (#PCDATA) |
| Attributes: | The math element contains the common attributes. |
The meta element is a container for "hidden" document bibliographic data, or meta-data (data about the document). It corresponds to HTML META tags.
See also the docinfo element for displayed meta-data. The document's title attribute stores the metadate document title.
| 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: | None. |
The "meta" directive is used to create a meta element. reStructuredText source:
.. 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">
The note element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, danger, error, hint, important, tip, warning, and the generic admonition.
| 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. (%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. |
|
reStructuredText source:
.. Note:: Admonitions can be handy to break up a long boring technical document.
Pseudo-XML fragment from simple parsing:
<note>
<paragraph>
Admonitions can be handy to break up a
long boring technical document.
The option element groups an option string together with zero or more option argument placeholders. Note that reStructuredText currently supports only one argument per option.
| Category: | |
|---|---|
| Analogues: | option has no direct analogues in common DTDs. |
| Processing: | See option_list. |
| Parents: | Only the option_group element contains option. |
| Children: | Each option element contains one option_string and zero or more option_argument elements. (option_string, option_argument*) |
| Attributes: | The option element contains only the common attributes. |
See the examples for the option_list element.
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. (#PCDATA) |
| Attributes: | The option_argument element contains the common attributes plus delimiter. delimiter contains the text preceding the option_argument: either the text separating it from the option_string (typically either "=" or " ") or the text between option arguments (typically either "," or " "). |
See the examples for the option_list element.
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. (option+) |
| Attributes: | The option_group element contains only the common attributes. |
See the examples for the option_list element.
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. (option_list_item+) |
| 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. |
|
reStructuredText source:
-a command-line option "a"
-1 file, --one=file, --two file
Multiple options with arguments.
Pseudo-XML fragment from simple parsing:
<option_list>
<option_list_item>
<option_group>
<option>
<option_string>
-a
<description>
<paragraph>
command-line option "a"
<option_list_item>
<option_group>
<option>
<option_string>
-1
<option_argument delimiter=" ">
file
<option>
<option_string>
--one
<option_argument delimiter="=">
file
<option>
<option_string>
--two
<option_argument delimiter=" ">
file
<description>
<paragraph>
Multiple options with arguments.
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. (option_group, description) |
| Attributes: | The option_list_item element contains only the common attributes. |
See the examples for the option_list element.
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. (#PCDATA) |
| Attributes: | The option_string element contains only the common attributes. |
See the examples for the option_list element.
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. |
|
reStructuredText source:
Document Title ============== :Organization: Humankind
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<organization>
Humankind
See docinfo for a more complete example, including processing context.
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. |
|
reStructuredText source:
A paragraph.
Pseudo-XML fragment from simple parsing:
<paragraph>
A paragraph.
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. |
|
reStructuredText source:
Document Title ============== :Version: 1 :Revision: b
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<version>
1
<revision>
b
See docinfo for a more complete example, including processing context.
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.
The section element is the main unit of hierarchy for Docutils documents. Docutils section elements are a recursive structure; a section may contain other section elements, without limit. Paragraphs and other body elements may occur before a section, but not after it.
| Category: | |
|---|---|
| Analogues: | section is analogous to the recursive "section" elements in DocBook and HTML5. |
| Parents: | The following elements may contain section: document, section |
| Children: | section elements begin with a title, and may contain body elements as well as transition, topic, and sidebar elements. (title, %structure.model;) See the %structure.model; parameter entity for details of the body of a section. |
| Attributes: | The section element contains only the common attributes. |
| Parameter Entities: | |
The %section.elements; parameter entity directly includes section. The %structure.model; parameter entity indirectly includes section. |
|
reStructuredText source:
Title 1 ======= Paragraph 1. Title 2 ------- Paragraph 2. Title 3 ======= Paragraph 3. Title 4 ------- Paragraph 4.
Complete pseudo-XML result after parsing:
<document>
<section ids="title-1" names="title 1">
<title>
Title 1
<paragraph>
Paragraph 1.
<section ids="title-2" names="title 2">
<title>
Title 2
<paragraph>
Paragraph 2.
<section ids="title-3" names="title 3">
<title>
Title 3
<paragraph>
Paragraph 3.
<section ids="title-4" names="title 4">
<title>
Title 4
<paragraph>
Paragraph 4.
Sidebars are like miniature, parallel documents that occur inside other documents, providing related or reference material. A sidebar is typically offset by a border and "floats" to the side of the page; the document's main text may flow around it. Sidebars can also be likened to super-footnotes; their content is outside of the flow of the document's main text.
The sidebar element is a nonrecursive section-like construct which may occur at the top level of a section wherever a body element (list, table, etc.) is allowed. In other words, sidebar elements cannot nest inside body elements, so you can't have a sidebar inside a table or a list, or inside another sidebar (or topic).
| Category: | |
|---|---|
| Analogues: | sidebar is analogous to the DocBook "sidebar" element. |
| Processing: | A sidebar element should be set off from the rest of the document somehow, typically with a border. Sidebars typically "float" to the side of the page and the document's main text flows around them. |
| Parents: | The following elements may contain sidebar: document, section |
| Children: | sidebar elements begin with optional title and subtitle and contain body elements and topic elements. (title, subtitle?, (%body.elements; | topic)+) |
| Attributes: | The sidebar element contains only the common attributes. |
| Parameter Entities: | |
The %structure.model; parameter entity directly includes sidebar. |
|
The "sidebar" directive is used to create a sidebar element. reStructuredText source:
.. sidebar:: Optional Title :subtitle: If Desired Body.
Pseudo-XML fragment from simple parsing:
<sidebar>
<title>
Optional Title
<subtitle>
If Desired
<paragraph>
Body.
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. |
|
reStructuredText source:
Document Title ============== :Status: Work In Progress
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<status>
Work In Progress
See docinfo for a more complete example, including processing context.
The subtitle element stores the subtitle of a document.
| Category: | |
|---|---|
| Analogues: | subtitle is analogous to HTML header elements ("h2" etc.) and to the DocBook "subtitle" element. |
| Processing: | A document's subtitle is usually rendered smaller than its title. |
| Parents: | |
| Children: | subtitle elements may contain text data plus inline elements. %text.model; |
| Attributes: | The subtitle element contains only the common attributes. |
reStructuredText source:
======= Title ======= ---------- Subtitle ---------- A paragraph.
Complete pseudo-XML result after parsing and applying transforms:
<document ids="title" names="title">
<title>
Title
<subtitle ids="subtitle" names="subtitle">
Subtitle
<paragraph>
A paragraph.
Note how two section levels have collapsed, promoting their titles to become the document's title and subtitle. Since there is only one structural element (document), the subsection's ids and names attributes are stored in the subtitle element.
The table element identifies a data arrangement with rows and columns.
Docutils tables are based on the Exchange subset of the CALS-table model [exchange-table-model]. [2]
| [2] | The interpretation of column widths in colspec differs from the specification. |
| Category: | |
|---|---|
| Analogues: | table is analogous to the HTML "table" element. |
| Processing: | Content is rendered in rows and columns. |
| Parents: | All elements employing the %body.elements; or %structure.model; parameter entities in their content models 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 contains the attributes frame, colsep, rowsep, and pgwide defined in the exchange-table-model, the common attributes, align, and width. |
| Parameter Entities: | |
The %body.elements; parameter entity directly includes table. The %structure.model; parameter entity indirectly includes table. |
|
In reStructuredText, tables can 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
| [exchange-table-model] | (1, 2, 3) XML Exchange Table Model DTD, OASIS Technical Memorandum 9901:1999, http://www.oasis-open.org/html/tm9901.html. |
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: | See definition_list_item. |
| 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. |
See the examples for the definition_list, definition_list_item, and classifier elements.
The tip element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, danger, error, hint, important, note, warning, and the generic admonition.
| Category: | |
|---|---|
| Analogues: |
|
| 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. (%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. |
|
reStructuredText source:
.. Tip:: 15% if the service is good.
Pseudo-XML fragment from simple parsing:
<tip>
<paragraph>
15% if the service is good.
The title element stores the title of a document, section, sidebar, table, topic, or generic admonition.
| Category: | |
|---|---|
| Analogues: | title is analogous to HTML "title" and header ("h1" etc.) elements, and to the DocBook "title" 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 and auto. refid is used as a backlink to a table of contents entry. auto is used to indicate (with value "1") that the title has been numbered automatically. |
reStructuredText source:
A Title ======= A paragraph.
Pseudo-XML fragment from simple parsing:
<section ids="a-title" names="a title">
<title>
A Title
<paragraph>
A paragraph.
The topic element is a nonrecursive section-like construct which may occur at the top level of a section wherever a body element (list, table, etc.) is allowed. In other words, topic elements cannot nest inside body elements, so you can't have a topic inside a table or a list, or inside another topic.
| Category: | |
|---|---|
| Analogues: | topic is analogous to the DocBook "simplesect" element. |
| Processing: | A topic element should be set off from the rest of the document somehow, such as with indentation or a border. |
| Parents: | The following elements may contain topic: document, section, sidebar |
| Children: | topic elements begin with a title and may contain body elements. (title?, (%body.elements;)+) |
| Attributes: | The topic element contains only the common attributes. |
| Parameter Entities: | |
The %structure.model; parameter entity directly includes topic. |
|
The "topic" directive is used to create a topic element. reStructuredText source:
.. topic:: Title Body.
Pseudo-XML fragment from simple parsing:
<topic>
<title>
Title
<paragraph>
Body.
The transition element is commonly seen in novels and short fiction, as a gap spanning one or more lines, with or without a type ornament such as a row of asterisks. Transitions separate body elements and sections, dividing a section into untitled divisions. A transition may not begin or end a section [3] or document, nor may two transitions be immediately adjacent.
See Doctree Representation of Transitions in A Record of reStructuredText Syntax Alternatives.
| [3] | In reStructuredText markup, a transition may appear to fall at the end of a section immediately before another section. A transform recognizes this case and moves the transition so it separates the sections. |
| Category: | Structural Subelements |
|---|---|
| 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. | |
reStructuredText source:
Paragraph 1. -------- Paragraph 2.
Complete pseudo-XML result after parsing:
<document>
<paragraph>
Paragraph 1.
<transition>
<paragraph>
Paragraph 2.
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. |
|
reStructuredText source:
Document Title ============== :Version: 1.1
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<version>
1.1
See docinfo for a more complete example, including processing context.
The warning element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, danger, error, hint, important, note, tip.
| 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. (%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. |
|
reStructuredText source:
.. WARNING:: Reader discretion is strongly advised.
Pseudo-XML fragment from simple parsing:
<warning>
<paragraph>
Reader discretion is strongly advised.
Attribute types defined in the attribute types section of the XML 1.0 specification:
Docutils uses custom attribute types instead of the ID, IDREF, and IDREFS standard types, because it does not adhere to the One ID per Element Type validity constraint.
The Docutils DTD defines parameter entities that resolve to standard attribute types to highlight specific attribute value constraints.
Boolean: no if zero ("0"), yes if any other value. Resolves to NMTOKEN.
The attribute value must be a number. Resolves to NMTOKEN.
A number which may be immediately followed by a unit or percent sign. Resolves to CDATA.
A space-separated list of class names [4]. Resolves to NMTOKEN.
Used in the classes attribute.
A normalized reference name. Resolves to CDATA (in contrast to NMTOKENS, reference names may consist of any text).
Used in the refname attribute.
A space-separated list of reference names. Resolves to CDATA.
Backslash escaping is used for space characters inside a reference name.
A space-separated list of unique identifier keys [5]. Resolves to NMTOKENS (the XML standard attribute types do not provide for a list of IDs).
Used in the ids attribute.
A reference to an identifier key. Resolves to NMTOKEN (Docutils identifier keys do not use the ID standard type as required by the IDREF Validity constraint).
Used in the refid attribute.
A list of references to element identifiers. Resolves to NMTOKENS.
Used in the backrefs attribute.
| [4] | Class names define sub-classes of existing elements. In reStructuredText, custom class names can be specified using the "class" directive, a directive's :class: option, or custom interpreted text roles. Docutils normalizes them to conform to both, HTML4.1 and CSS1.0 name requirements (the regular expression [a-z](-?[a-z0-9]+)*) via the identifier normalization. |
| [5] | Identifier keys are used for cross references in generated documents. Therefore, they must comply with restrictions in the respective output formats (HTML4.1, HTML5, polyglot HTML, LaTeX, ODT, troff (manpage), XML). Identifier keys cannot be specified directly in reStructuredText. Docutils generates them by applying the identifier normalization to reference names or from the auto_id_prefix, prepending the id_prefix and potentially appending numbers for disambiguation. |
Attribute type: CDATA. Default value: none (inherit).
The align attribute is used in the figure, image, and table elements (via the %align-h.att; and %align-hv.att; parameter entities).
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).
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).
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).
Attribute type: CDATA. Default value: none.
The bullet attribute is used in the bullet_list element.
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.
Attribute type: CDATA. Default value: "1*"
Column width specification used in the colspec element. Defined in the exchange-table-model.
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.
Important
Currently, Docutils interprets unitless numbers as proportions.
Attribute type: CDATA. Default value: none.
The delimiter attribute is used in the option_argument element.
Attribute type: refnames.type. Default value: none.
The dupnames attribute replaces the names attribute when there has been a naming conflict. dupnames is one of the common attributes, shared by all Docutils elements.
Attribute type: EnumeratedType, one of "arabic", "loweralpha", "upperalpha", "lowerroman", or "upperroman". Default value: none.
The enumtype attribute is used in the enumerated_list element.
Attribute type: measure. Default value: none.
The height attribute is used in the image element.
Attribute type: ids.type. Default value: none.
The ids attribute is a space separated list containing one or more unique identifier keys, typically assigned by the system.
ids is one of the common attributes, shared by all Docutils elements.
Attribute type: number. Default value: none.
The level attribute is used in the system_message element.
Attribute type: number. Default value: none.
The morecols attribute is used in the table element.
Attribute type: refnames.type. Default value: none.
The names attribute is a space-separated list containing normalized reference names of an element. Whitespace inside a name is 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.
Reference names are identifiers assigned in the markup. They originate from internal hyperlink targets, a directive's name option, or the element's title or content and are used for internal cross-references (cf. refname).
names is one of the common attributes, shared by all Docutils elements.
Attribute type: CDATA. Default value: none.
The prefix attribute is used in the enumerated_list element.
Attribute type: idref.type. Default value: none.
The refid attribute contains a reference to an identifier key
refid is used by the target, reference, footnote_reference, citation_reference, title and problematic elements (via the %refid.att; and %reference.atts; parameter entities).
Attribute type: refname.type. Default value: none.
The refname attribute contains a reference to one of the reference names in 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. Docutils "transforms" replace the refname attribute with a refid pointing to the same element.
refname is used by the target, reference, footnote_reference, citation_reference, and substitution_reference elements (via the %refname.att; and %reference.atts; parameter entities).
Attribute type: CDATA. Default value: none.
The refuri attribute contains an external reference to a URI/URL. It is used by the target, reference, footnote_reference, and citation_reference elements (via the %reference.atts; parameter entity).
Attribute type: number. Default value: none.
The scale attribute is used in the image element.
Attribute type: CDATA. Default value: none.
The source attribute is used to store the path or URL to the source text that was used to produce the document tree. It is one of the common attributes, declared for all Docutils elements.
Attribute type: number. Default value: none.
The start attribute is used in the enumerated_list element.
Attribute type: yesorno. Default value: none.
The stub attribute is used in the colspec element. It marks a table column containing "stubs" (row titles, on the left). See also the csv-table and list-table directives.
Attribute type: CDATA. Default value: none.
The suffix attribute is used in the enumerated_list element.
Attribute type: CDATA. Default value: none.
The title attribute stores the title metadata of a document. This title is typically not part of the rendered document. It may for example be used in HTML's title element.
Attribute type: measure. Default value: none.
The width attribute is used in the figure, image, and table element.
Attribute type: EnumeratedType, one of "default" or "preserve". Default value: "preserve" (fixed).
The xml:space attribute is a standard XML attribute for whitespace-preserving elements. It is used by the literal_block, line_block, doctest_block, comment, and raw elements (via the %fixedspace.att; parameter entity). It is a fixed attribute, meant to communicate to an XML parser that the element contains significant whitespace. The attribute value should not be set in a document instance.
Parameter entities are used to simplify the DTD (to share definitions and reduce duplication) and to allow the DTD to be customized by wrapper DTDs (external client DTDs that use or import the Docutils DTD). Parameter entities may be overridden by wrapper DTDs, replacing the definitions below with custom definitions. Parameter entities whose names begin with "additional" are meant to allow easy extension by wrapper DTDs.
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.
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.
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.
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.
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.
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;.
The %bibliographic.elements; parameter entity contains an OR-list of all bibliographic elements.
Entity definition:
author | authors | organization | contact | address | version | revision | status | date | copyright | field %additional.bibliographic.elements;
The %additional.bibliographic.elements; parameter entity can be used by wrapper DTDs to extend %bibliographic.elements;.
Only the docinfo element directly employs the %bibliographic.elements; parameter entity in its content model.
The %body.elements; parameter entity contains an OR-list of all body elements. %body.elements; is itself contained within the %structure.model; parameter entity.
Entity definition:
admonition | attention | block_quote | bullet_list | caution | citation | compound | comment | container | danger | definition_list | doctest_block | enumerated_list | error | field_list | figure | footnote | hint | image | important | line_block | literal_block | note | option_list | paragraph | pending | raw reference | rubric | substitution_definition | system_message | table | target | tip | warning %additional.body.elements;
The %additional.body.elements; parameter entity can be used by wrapper DTDs to extend %body.elements;.
The %body.elements; parameter entity is directly employed in the content models of the following elements: admonition, attention, block_quote, caution, citation, compound, danger, definition, description, entry, error, field_body, footer, footnote, header, hint, important, legend, list_item, note, sidebar, system_message, tip, topic, warning
Via %structure.model;, the %body.elements; parameter entity is indirectly employed in the content models of the document and section elements.
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, line_block, literal_block, raw
The %inline.elements; parameter entity contains an OR-list of all inline elements.
Entity definition:
abbreviation | acronym | citation_reference | emphasis | footnote_reference | generated | image | inline | literal | problematic | raw | reference | strong | substitution_reference | subscript | superscript | target | title_reference %additional.inline.elements;
The %additional.inline.elements; parameter entity can be used by wrapper DTDs to extend %inline.elements;.
Via %text.model;, the %inline.elements; parameter entity is indirectly employed in the content models of the following elements: abbreviation, acronym, address, attribution, author, caption, classifier, contact, copyright, date, doctest_block, emphasis, generated, inline, line_block, literal_block, math, math_block, organization, paragraph, problematic, raw, reference, revision, rubric, status, strong, subscript, substitution_definition, substitution_reference, subtitle, superscript, target, term, title, title_reference, version
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.
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.
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.
The %refuri.att; parameter entity contains the refuri attribute, an external reference to a URI/URL.
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.
The %section.elements; parameter entity contains an OR-list of all section-equivalent elements. %section.elements; is itself contained within the %structure.model; parameter entity.
Entity definition:
section %additional.section.elements;
The %additional.section.elements; parameter entity can be used by wrapper DTDs to extend %section.elements;.
Via %structure.model;, the %section.elements; parameter entity is indirectly employed in the content models of the document and section elements.
The %structure.model; parameter entity encapsulates the hierarchical structure of a document and of its constituent parts. See the discussion of the element hierarchy above.
Entity definition:
( ( (%body.elements; | topic | sidebar)+, transition? )*, ( (%section.elements;), (transition?, (%section.elements;) )* )? )
Each document or section contains zero or more body elements, topics, and/or sidebars, optionally interspersed with single transitions, followed by zero or more sections (whose contents are recursively the same as this model) optionally interspersed with transitions.
The following restrictions are imposed by this model:
The %structure.model; parameter entity is directly employed in the content models of the document and section elements.
The %text.model; parameter entity is used by many 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, author, caption, classifier, contact, copyright, date, doctest_block, emphasis, field_name, generated, line_block, literal_block, organization, paragraph, problematic, raw, reference, revision, status, strong, substitution_definition, substitution_reference, subtitle, target, term, title, version