Docutils | Overview | About | Users | Reference | Developers

The Docutils Document Tree

A Guide to the Docutils DTD

Author:

David Goodger

Contact:
docutils-develop@lists.sourceforge.net
Revision:
$Revision$
Date:
$Date$

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.

Element Hierarchy

Below is a simplified diagram of the hierarchy of elements in the Docutils document tree structure. An element may contain any other elements immediately below it in the diagram. Notes are written in square brackets. Element types in parentheses indicate recursive or one-to-many relationships; sections may contain (sub)sections, tables contain further body elements, etc.

+--------------------------------------------------------------------+
| document  [may begin with a title, subtitle, decoration, docinfo]  |
|                             +--------------------------------------+
|                             | sections  [each begins with a title] |
+-----------------------------+-------------------------+------------+
| [body elements:]                                      | (sections) |
|         | - literal | - lists  |       | - hyperlink  +------------+
|         |   blocks  | - tables |       |   targets    |
| para-   | - doctest | - block  | foot- | - sub. defs  |
| graphs  |   blocks  |   quotes | notes | - comments   |
+---------+-----------+----------+-------+--------------+
| [text]+ | [text]    | (body elements)  | [text]       |
| (inline +-----------+------------------+--------------+
| markup) |
+---------+

The Docutils document model uses a simple, recursive model for section structure. A <document> node may contain body elements and <section> elements. Sections in turn may contain body elements and sections. The level (depth) of a section element is determined from its physical nesting level; unlike other document models (<h1> in HTML, <sect1> in DocBook, <div1> in XMLSpec) the level is not incorporated into the element name.

The Docutils document model uses strict element content models. Every element has a unique structure and semantics, but elements may be classified into general categories (below). Only elements which are meant to directly contain text data have a mixed content model, where text data and inline elements may be intermixed. This is unlike the much looser HTML document model, where paragraphs and text data may occur at the same level.

Structural Elements

Structural elements may only contain child elements; they do not directly contain text data. Structural elements may contain body elements or further structural elements. Structural elements can only be child elements of other structural elements.

Category members: <document>, <section>, <topic>, <sidebar>

Structural Subelements

Structural subelements are child elements of structural elements. Simple structural subelements (<title>, <subtitle>) contain text data; the others are compound elements and do not directly contain text data.

Category members: <title>, <subtitle>, <decoration>, <docinfo>, <meta>, <transition>

Bibliographic Elements

The <docinfo> element is an optional child of <document>. It groups bibliographic elements together. All bibliographic elements except <authors> and <field> contain text data. <authors> contains further bibliographic elements (most notably <author>). <field> contains <field_name> and <field_body> body subelements.

Category members: <address>, <author>, <authors>, <contact>, <copyright>, <date>, <field>, <organization>, <revision>, <status>, <version>

Decorative Elements

The <decoration> element is also an optional child of <document>. It groups together elements used to generate page headers and footers.

Category members: <footer>, <header>

Body Elements

Body elements are contained within structural elements and compound body elements. There are two subcategories of body elements: simple and compound.

Category members: <admonition>, <attention>, <block_quote>, <bullet_list>, <caution>, <citation>, <comment>, <compound>, <container>, <danger>, <definition_list>, <doctest_block>, <enumerated_list>, <error>, <field_list>, <figure>, <footnote>, <hint>, <image>, <important>, <line_block>, <literal_block>, <note>, <option_list>, <paragraph>, <pending>, <raw>, <rubric>, <substitution_definition>, <system_message>, <table>, <target>, <tip>, <warning>

Simple Body Elements

Simple body elements are empty or directly contain text data. Those that contain text data may also contain inline elements. Such elements therefore have a "mixed content model".

Category members: <comment>, <doctest_block>, <image>, <literal_block>, <math_block>, <paragraph>, <pending>, <raw>, <rubric>, <substitution_definition>, <target>

Compound Body Elements

Compound body elements contain local substructure (body subelements) and further body elements. They do not directly contain text data.

Category members: <admonition>, <attention>, <block_quote>, <bullet_list>, <caution>, <citation>, <compound>, <container>, <danger>, <definition_list>, <enumerated_list>, <error>, <field_list>, <figure>, <footnote>, <hint>, <important>, <line_block>, <note>, <option_list>, <system_message>, <table>, <tip>, <warning>

Body Subelements

Compound body elements contain specific subelements (e.g. <bullet_list> contains <list_item>). Subelements may themselves be compound elements (containing further child elements, like <field>) or simple data elements (containing text data, like <field_name>). These subelements always occur within specific parent elements, never at the body element level (beside paragraphs, etc.).

Category members (simple): <attribution>, <caption>, <classifier>, <colspec>, <field_name>, <label>, <line>, <option_argument>, <option_string>, <term>

Category members (compound): <definition>, <definition_list_item>, <description>, <entry>, <field>, <field_body>, <legend>, <list_item>, <option>, <option_group>, <option_list_item>, <row>, <tbody>, <tgroup>, <thead>

Inline Elements

Inline elements directly contain text data, and may also contain further inline elements. Inline elements are contained within simple body elements. Most inline elements have a "mixed content model".

Category members: <abbreviation>, <acronym>, <citation_reference>, <emphasis>, <footnote_reference>, <generated>, <image>, <inline>, <literal>, <math>, <problematic>, <raw>, <reference>, <strong>, <subscript>, <substitution_reference>, <superscript>, <target>, <title_reference>

Element Reference

Each element in the DTD (document type definition) is described in its own section below. Each section contains an introduction plus the following subsections:


Many of the element reference sections below are marked "to be completed". Please help complete this document by contributing to its writing.

<abbreviation>

The <abbreviation> element is an inline element used to represent an abbreviation being used in the document. An example of an abbreviation is 'St' being used instead of 'Street'.

Details

Category:

Inline Elements

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.

Examples

The reStructuredText abbreviation role creates an <abbreviation> element:

:abbreviation:`St` is a common abbreviation for "street".

Pseudo-XML fragment from simple parsing:

<paragraph>
    <abbreviation>
        St
    is a common abbreviation for "street".

<acronym>

To be completed.

<address>

The <address> element holds the surface mailing address information for the author(s) (individual or group) of the document, or a third-party contact address. Its structure is identical to that of the <literal_block> element: whitespace is significant, especially newlines.

Details

Category:

Bibliographic Elements

Analogues:

<address> is analogous to the DocBook <address> element.

Processing:

As with the <literal_block> element, newlines and other whitespace is significant and must be preserved. However, a monospaced typeface need not be used. See also <docinfo>.

Parents:

The following elements may contain <address>: <docinfo>, <authors>.

Children:

<address> elements contain text data plus inline elements (%text.model;).

Attributes:

The <address> element contains the common attributes plus xml:space.

Parameter Entities:

The %bibliographic.elements; parameter entity directly includes <address>.

Examples

In reStructuredText, "address" is one of the registered bibliographic fields:

Document Title
==============

:Address: 123 Example Ave.
          Example, EX

Complete pseudo-XML result after parsing and applying transforms:

<document ids="document-title" names="document title">
    <title>
        Document Title
    <docinfo>
        <address>
            123 Example Ave.
            Example, EX

See <docinfo> for a more complete example, including processing context.

<admonition>

The <admonition> element is a generic, titled admonition, a distinctive and self-contained notice.

See also the specific admonition elements <attention> <caution>, <danger>, <error>, <hint>, <important>, <note>, <tip>, and <warning>.

Details

Category:

Compound Body Elements

Analogues:

The generic <admonition> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. The specific admonitions <caution>, <note>, <tip>, and <warning> are analogous to the respective DocBook elements.

Processing:

Rendered distinctly (inset and/or in a box, etc.).

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <admonition>.

Children:

<admonition> elements begin with a <title> and may contain one or more body elements.

Attributes:

The <admonition> element contains only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <admonition>. The %structure.model; parameter entity indirectly includes <admonition>.

Examples

The reStructuredText "admonition" directive creates a generic <admonition> element:

.. admonition:: By the way...

   You can make up your own admonition too.

Pseudo-XML fragment from simple parsing:

<admonition class="admonition-by-the-way">
    <title>
        By the way...
    <paragraph>
        You can make up your own admonition too.

<attention>

The <attention> element is an admonition, a distinctive and self-contained notice. See also the generic <admonition> and the other specific admonition elements <caution>, <danger>, <error>, <hint>, <important>, <note>, <tip>, and <warning>.

Details

Category:

Compound Body Elements

Analogues:

<attention> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.

Processing:

Rendered distinctly (inset and/or in a box, etc.), with the generated title "Attention!" (or similar).

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <attention>.

Children:

<attention> elements contain one or more body elements.

Attributes:

The <attention> element contains only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <attention>. The %structure.model; parameter entity indirectly includes <attention>.

Examples

A reStructuredText "attention" directive:

.. Attention:: All your base are belong to us.

Pseudo-XML fragment from simple parsing:

<attention>
    <paragraph>
        All your base are belong to us.

<attribution>

To be completed.

<author>

The <author> element holds the name of the author (or one of the authors) of the document.

Details

Category:

Bibliographic Elements

Analogues:

<author> is analogous to the DocBook <author> element.

Processing:

See <docinfo>.

Parents:

The following elements may contain <author>: <docinfo>, <authors>.

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>.

Examples

In reStructuredText, "author" is one of the registered bibliographic fields:

Document Title
==============

:Author: J. Random Hacker

Complete pseudo-XML result after parsing and applying transforms:

<document ids="document-title" names="document title">
    <title>
        Document Title
    <docinfo>
        <author>
            J. Random Hacker

See <docinfo> for a more complete example, including processing context.

<authors>

The <authors> element is a container for author information for documents with multiple authors.

Details

Category:

Bibliographic Elements

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>.

Examples

In reStructuredText, "authors" is one of the registered bibliographic fields:

Document Title
==============

:Authors: J. Random Hacker; Jane Doe

Complete pseudo-XML result after parsing and applying transforms:

<document ids="document-title" names="document title">
    <title>
        Document Title
    <docinfo>
        <authors>
            <author>
                J. Random Hacker
            <author>
                Jane Doe

In reStructuredText, multiple author's names are separated with semicolons (";") or commas (","); semicolons take precedence. There is currently no way to represent the author's organization, address, or contact in a reStructuredText "Authors" field.

See <docinfo> for a more complete example, including processing context.

<block_quote>

The <block_quote> element is used for quotations set off from the main text (standalone).

Details

Category:

Compound Body Elements

Analogues:

<block_quote> is analogous to the <blockquote> element in both HTML and DocBook.

Processing:

<block_quote> elements serve to set their contents off from the main text, typically with indentation and/or other decoration.

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <block_quote>.

Children:

<block_quote> elements contain body elements followed by an optional <attribution> element.

Attributes:

The <block_quote> element contains only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <block_quote>. The %structure.model; parameter entity indirectly includes <block_quote>.

Examples

In reStructuredText, an indented text block without preceding markup is a block quote:

As a great palaeontologist once said,

    This theory, that is mine, is mine.

    -- Anne Elk (Miss)

Pseudo-XML fragment from simple parsing:

<paragraph>
    As a great palaeontologist once said,
<block_quote>
    <paragraph>
        This theory, that is mine, is mine.
    <attribution>
        Anne Elk (Miss)

<bullet_list>

The <bullet_list> element contains <list_item> elements which are uniformly marked with bullets. Bullets are typically simple dingbats (symbols) such as circles and squares.

Details

Category:

Compound Body Elements

Analogues:

<bullet_list> is analogous to the HTML<ul> element [1] and to the DocBook <itemizedlist> element.

Processing:

Each list item should begin a new vertical block, prefaced by a bullet/dingbat.

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <bullet_list>.

Children:

<bullet_list> elements contain one or more <list_item> elements.

Attributes:

The <bullet_list> element contains the common attributes plus bullet.

Parameter Entities:

The %body.elements; parameter entity directly includes <bullet_list>. The %structure.model; parameter entity indirectly includes <bullet_list>.

Examples

A reStructuredText bullet list:

- Item 1, paragraph 1.

  Item 1, paragraph 2.

- Item 2.

Pseudo-XML fragment from simple parsing:

<bullet_list bullet="-">
    <list_item>
        <paragraph>
            Item 1, paragraph 1.
        <paragraph>
            Item 1, paragraph 2.
    <list_item>
        <paragraph>
            Item 2.

See <list_item> for another example.

<caption>

To be completed.

<caution>

The <caution> element is an admonition, a distinctive and self-contained notice. See also the generic <admonition> and the other specific admonition elements <attention>, <danger>, <error>, <hint>, <important>, <note>, <tip>, and <warning>.

Details

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.

Attributes:

The <caution> element contains only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <caution>. The %structure.model; parameter entity indirectly includes <caution>.

Examples

A reStructuredText "caution" directive:

.. Caution:: Don't take any wooden nickels.

Pseudo-XML fragment from simple parsing:

<caution>
    <paragraph>
        Don't take any wooden nickels.

<citation>

To be completed.

<citation_reference>

To be completed.

<classifier>

The <classifier> element contains the classification or type of the <term> being defined in a <definition_list>. For example, it can be used to indicate the type of a variable.

Details

Category:

Body Subelements (simple)

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.

Examples

A reStructuredText definition list with classifiers:

name : string
    Customer name.
i : int
    Temporary index variable.

Pseudo-XML fragment from simple parsing:

<definition_list>
    <definition_list_item>
        <term>
            name
        <classifier>
            string
        <definition>
            <paragraph>
                Customer name.
    <definition_list_item>
        <term>
            i
        <classifier>
            int
        <definition>
            <paragraph>
                Temporary index variable.

<colspec>

Specifications for a column in a <table>.

Details

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.

Examples

See <table>.

<comment>

To be completed.

<compound>

To be completed.

<contact>

The <contact> element holds contact information for the author (individual or group) of the document, or a third-party contact. It is typically used for an email or web address.

Details

Category:

Bibliographic Elements

Analogues:

<contact> is analogous to the DocBook <email> element. The HTML <address> element serves a similar purpose.

Processing:

See <docinfo>.

Parents:

The following elements may contain <contact>: <docinfo>, <authors>.

Children:

<contact> elements may contain text data plus inline elements (%text.model;).

Attributes:

The <contact> element contains only the common attributes.

Parameter Entities:

The %bibliographic.elements; parameter entity directly includes <contact>.

Examples

In reStructuredText, "contact" is one of the registered bibliographic fields:

Document Title
==============

:Contact: jrh@example.com

Complete pseudo-XML result after parsing and applying transforms:

<document ids="document-title" names="document title">
    <title>
        Document Title
    <docinfo>
        <contact>
            <reference refuri="mailto:jrh@example.com">
                jrh@example.com

See <docinfo> for a more complete example, including processing context.

<container>

To be completed.

<danger>

The <danger> element is an admonition, a distinctive and self-contained notice. See also the generic <admonition> and the other specific admonition elements <attention>, <caution>, <error>, <hint>, <important>, <note>, <tip>, and <warning>.

Details

Category:

Compound Body Elements

Analogues:

<danger> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.

Processing:

Rendered distinctly (inset and/or in a box, etc.), with the generated title "!DANGER!" (or similar).

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <danger>.

Children:

<danger> elements contain one or more body elements.

Attributes:

The <danger> element contains only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <danger>. The %structure.model; parameter entity indirectly includes <danger>.

Examples

A reStructuredText "danger" directive:

.. DANGER:: Mad scientist at work!

Pseudo-XML fragment from simple parsing:

<danger>
    <paragraph>
        Mad scientist at work!

<date>

The <date> element contains the date of publication, release, or last modification of the document.

Details

Category:

Bibliographic Elements

Analogues:

<date> is analogous to the DocBook <date> element.

Processing:

Often used with the RCS/CVS keyword "Date". See <docinfo>.

Parents:

Only the <docinfo> element contains <date>.

Children:

<date> elements may contain text data plus inline elements (%text.model;).

Attributes:

The <date> element contains only the common attributes.

Parameter Entities:

The %bibliographic.elements; parameter entity directly includes <date>.

Examples

In reStructuredText, "date" is one of the registered bibliographic fields:

Document Title
==============

:Date: 2002-08-20

Complete pseudo-XML result after parsing and applying transforms:

<document ids="document-title" names="document title">
    <title>
        Document Title
    <docinfo>
        <date>
            2002-08-20

See <docinfo> for a more complete example, including processing context.

<decoration>

The <decoration> element is a container for <header> and <footer> elements and potential future extensions. These elements are used for notes, time/datestamp, processing information, etc.

Details

Category:

Structural Subelements

Analogues:

There are no direct analogies to <decoration> in HTML or in DocBook.

Processing:

See the individual decorative elements.

Parents:

Only the <document> element contains <decoration>.

Children:

<decoration> elements may contain the decorative elements <header> and/or <footer>. Although the content model doesn't specifically require contents, no empty <decoration> elements are ever created.

Attributes:

The <decoration> element contains only the common attributes.

Examples

See <header> and <footer>.

<definition>

The <definition> element is a container for the body elements used to define a <term> in a <definition_list>.

Details

Category:

Body Subelements (compound)

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.

Attributes:

The <definition> element contains only the common attributes.

Examples

See the examples for the <definition_list>, <definition_list_item>, and <classifier> elements.

<definition_list>

The <definition_list> element contains a list of terms and their definitions. It can be used for glossaries or dictionaries, to describe or classify things, for dialogues, or to itemize subtopics (such as in this reference).

Details

Category:

Compound Body Elements

Analogues:

<definition_list> is analogous to the HTML <dl> element and to the DocBook <variablelist> element.

Processing:

See <definition_list_item>.

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <definition_list>.

Children:

<definition_list> elements contain one or more <definition_list_item> elements.

Attributes:

The <definition_list> element contains only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <definition_list>. The %structure.model; parameter entity indirectly includes <definition_list>.

Examples

A reStructuredText definition list. The classifier is optional.

Term
    Definition.

Term : classifier
    The ' : ' indicates a classifier in
    definition list item terms only.

Pseudo-XML fragment from simple parsing:

<definition_list>
    <definition_list_item>
        <term>
            Term
        <definition>
            <paragraph>
                Definition.
    <definition_list_item>
        <term>
            Term
        <classifier>
            classifier
        <definition>
            <paragraph>
                The ' : ' indicates a classifier in
                definition list item terms only.

See <definition_list_item> and <classifier> for further examples.

<definition_list_item>

The <definition_list_item> element contains a single <term>/<definition> pair (with optional <classifier>).

Details

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.

Examples

A complex reStructuredText definition list:

Tyrannosaurus Rex : carnivore
    Big and scary; the "Tyrant King".

Brontosaurus : herbivore
  ..

    All brontosauruses are thin at one end,
    much much thicker in the middle
    and then thin again at the far end.

    -- Anne Elk (Miss)

Pseudo-XML fragment from simple parsing:

<definition_list>
    <definition_list_item>
        <term>
            Tyrannosaurus Rex
        <classifier>
            carnivore
        <definition>
            <paragraph>
                Big and scary; the "Tyrant King".
    <definition_list_item>
        <term>
            Brontosaurus
        <classifier>
            herbivore
        <definition>
            <comment xml:space="preserve">
            <block_quote>
                <paragraph>
                    All brontosauruses are thin at one end,
                    much much thicker in the middle
                    and then thin again at the far end.
                <attribution>
                    Anne Elk (Miss)

See <definition_list> and <classifier> for further examples.

<description>

The <description> element contains body elements, describing the purpose or effect of a command-line option or group of options.

Details

Category:

Body Subelements

Analogues:

<description> has no direct analogues in common DTDs.

Processing:

See <option_list>.

Parents:

Only the <option_list_item> element contains <description>.

Children:

<description> elements may contain body elements.

Attributes:

The <description> element contains only the common attributes.

Examples

See the examples for the <option_list> element.

<docinfo>

The <docinfo> element is a container for displayed document bibliographic data, or meta-data (data about the document). It corresponds to the front matter of a book, such as the title page and copyright page.

See also the <meta> element (for hidden meta-data).

Details

Category:

Structural Subelements

Analogues:

<docinfo> is analogous to DocBook <info> elements. There are no directly analogous HTML elements; the <meta> element carries some of the same information, albeit invisibly.

Processing:

The <docinfo> element may be rendered as a two-column table or in other styles. It may even be invisible or omitted from the processed output. Meta-data may be extracted from <docinfo> children; for example, HTML <meta> tags may be constructed.

When Docutils transforms a reStructuredText <field_list> into a <docinfo> element (see the examples below), RCS/CVS keywords are normally stripped from simple (one paragraph) field bodies. For complete details, please see RCS Keywords in the reStructuredText Markup Specification.

Parents:

Only the <document> element contains <docinfo>.

Children:

<docinfo> elements contain bibliographic elements.

Attributes:

The <docinfo> element contains only the common attributes.

Examples

Docinfo is represented in reStructuredText by a <field_list> in a bibliographic context: the first visible element of a <document>, after any document <title>/<subtitle>. The field list is transformed into a <docinfo> element and its children by the frontmatter.DocInfo 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 classes="filename">
            <field_name>
                Filename
            <field_body>
                <paragraph>
                    doctree.txt
        <copyright>
            This document has been placed in the public domain.

Note that "Filename" is a non-standard <docinfo> field, so becomes a generic field element. Also note that the "RCSfile" keyword syntax has been stripped from the "Filename" data.

See <field_list> for an example in a non-bibliographic context. Also see the individual examples for the various bibliographic elements.

<doctest_block>

The <doctest_block> element is a Python-specific variant of <literal_block>. It is a block of text where line breaks and whitespace are significant and must be preserved.

<doctest_block> elements are used for interactive Python interpreter sessions, which are distinguished by their input prompt: >>>. They are meant to illustrate usage by example, and provide an elegant and powerful testing environment via the doctest module in the Python standard library.

Details

Category:

Simple Body Elements

Analogues:

<doctest_block> is analogous to the HTML <pre> element and to the DocBook <programlisting> and <screen> elements.

Processing:

As with <literal_block>, <doctest_block> elements are typically rendered in a monospaced typeface. It is crucial that all whitespace and line breaks are preserved in the rendered form.

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>.

Examples

A reStructuredText doctest block:

This is an ordinary paragraph.

>>> print('this is a Doctest block')
this is a Doctest block

Pseudo-XML fragment from simple parsing:

<paragraph>
    This is an ordinary paragraph.
<doctest_block xml:space="preserve">
    >>> print('this is a Doctest block')
    this is a Doctest block

<document>

The <document> element is the root (topmost) element of the Docutils document tree. <document> is the direct or indirect ancestor of every other element in the tree. It encloses the entire document tree. It is the starting point for a document.

Details

Category:

Structural Elements

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 plus an optional title attribute which stores the document title metadata.

Examples

A minimal reStructuredText document with title:

A Title
=======

A paragraph.

Complete pseudo-XML result from simple parsing:

<document>
    <section ids="a-title" names="a title">
        <title>
            A Title
        <paragraph>
            A paragraph.

After applying transforms, the section title is promoted to become the document title:

<document ids="a-title" names="a title">
    <title>
        A Title
    <paragraph>
        A paragraph.

<emphasis>

To be completed.

<entry>

To be completed.

<enumerated_list>

The <enumerated_list> element contains <list_item> elements which are uniformly marked with enumerator labels.

Details

Category:

Compound Body Elements

Analogues:

<enumerated_list> is analogous to the HTML <ol> element and to the DocBook <orderedlist> element.

Processing:

Each list item should begin a new vertical block, prefaced by a enumeration marker (such as "1.").

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <enumerated_list>.

Children:

<enumerated_list> elements contain one or more <list_item> elements.

Attributes:

The <enumerated_list> element contains the common attributes plus enumtype, prefix, suffix, and start.

enumtype is used to record the intended enumeration sequence, one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z), "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ..., mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ..., MMMMCMXCIX [4999]).

prefix stores the formatting characters used before the enumerator. In documents originating from reStructuredText data, it will contain either "" (empty string) or "(" (left parenthesis). It may or may not affect processing.

suffix stores the formatting characters used after the enumerator. In documents originating from reStructuredText data, it will contain either "." (period) or ")" (right parenthesis). Depending on the capabilities of the output format, this attribute may or may not affect processing.

start contains the ordinal value of the first item in the list, in decimal. For lists beginning at value 1 ("1", "a", "A", "i", or "I"), this attribute may be omitted.

Parameter Entities:

The %body.elements; parameter entity directly includes <enumerated_list>. The %structure.model; parameter entity indirectly includes <enumerated_list>.

Examples

A reStructuredText enumerated list:

1. Item 1.

   (A) Item A.
   (B) Item B.
   (C) Item C.

2. Item 2.

Pseudo-XML fragment from simple parsing:

<enumerated_list enumtype="arabic" prefix="" suffix=".">
    <list_item>
        <paragraph>
            Item 1.
        <enumerated_list enumtype="upperalpha" prefix="(" suffix=")">
            <list_item>
                <paragraph>
                    Item A.
            <list_item>
                <paragraph>
                    Item B.
            <list_item>
                <paragraph>
                    Item C.
    <list_item>
        <paragraph>
            Item 2.

See <list_item> for another example.

<error>

The <error> element is an admonition, a distinctive and self-contained notice. See also the generic <admonition> and the other specific admonition elements <attention>, <caution>, <danger>, <hint>, <important>, <note>, <tip>, and <warning>.

Details

Category:

Compound Body Elements

Analogues:

<error> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.

Processing:

Rendered distinctly (inset and/or in a box, etc.), with the generated title "Error" (or similar).

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <error>.

Children:

<error> elements contain one or more body elements.

Attributes:

The <error> element contains only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <error>. The %structure.model; parameter entity indirectly includes <error>.

Examples

A reStructuredText "error" directive:

.. Error:: Does not compute.

Pseudo-XML fragment from simple parsing:

<error>
    <paragraph>
        Does not compute.

<field>

The <field> element contains a pair of <field_name> and <field_body> elements.

Details

Category:

Body Subelements

Analogues:

<field> has no direct analogues in common DTDs. HTML5 uses <div> elements inside <dl> lists for grouping <dt>/<dd> pairs.

Processing:

See <field_list>.

Parents:

The following elements may contain <field>: <docinfo>, <field_list>

Children:

Each <field> element contains one <field_name> and one <field_body> element.

Attributes:

The <field> element contains only the common attributes.

Parameter Entities:

The %bibliographic.elements; parameter entity directly includes <field>.

Examples

See the examples for the <field_list> and <docinfo> elements.

<field_body>

The <field_body> element contains body elements. It is analogous to a database field's data.

Details

Category:

Body Subelements

Analogues:

<field_body> is analogous to the HTML <dd> element.

Processing:

See <field_list>.

Parents:

Only the <field> element contains <field_body>.

Children:

<field_body> elements may contain body elements.

Attributes:

The <field_body> element contains only the common attributes.

Examples

See the examples for the <field_list> and <docinfo> elements.

<field_list>

The <field_list> element contains two-column table-like structures resembling database records (label & data pairs). Field lists are often meant for further processing. In reStructuredText, field lists are used to represent bibliographic fields (contents of the <docinfo> element) and directive options.

Details

Category:

Compound Body Elements

Analogues:

<field_list> is analogue to the HTML <dl> element.

Processing:

A <field_list> is typically rendered as a two-column list, where the first column contains "labels" (usually with a colon suffix). However, field lists are often used for extension syntax or special processing. Such structures do not survive as field lists to be rendered.

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <field_list>.

Children:

<field_list> elements contain one or more <field> elements.

Attributes:

The <field_list> element contains only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <field_list>. The %structure.model; parameter entity indirectly includes <field_list>.

Examples

A reStructuredText field list:

:Author: Me
:Version: 1
:Date: 2001-08-11
:Parameter i: integer

Pseudo-XML fragment from simple parsing:

<field_list>
    <field>
        <field_name>
            Author
        <field_body>
            <paragraph>
                Me
    <field>
        <field_name>
            Version
        <field_body>
            <paragraph>
                1
    <field>
        <field_name>
            Date
        <field_body>
            <paragraph>
                2001-08-11
    <field>
        <field_name>
            Parameter i
        <field_body>
            <paragraph>
                integer

<field_name>

The <field_name> element contains text; it is analogous to a database field's name.

Details

Category:

Body Subelements (simple)

Analogues:

<field_name> is analogous to the HTML <dt> element.

Processing:

See <field_list>.

Parents:

Only the <field> element contains <field_name>.

Children:

<field_name> elements may contain text data plus inline elements (%text.model;).

Attributes:

The <field_name> element contains only the common attributes.

Examples

See the examples for the <field_list> and <docinfo> elements.

<figure>

To be completed.

<footnote>

The <footnote> element is used for labelled notes that provide additional context to a passage of text (footnotes or endnotes). The corresponding footnote mark in running text is set by the <footnote_reference> element.

Details

Category:

Compound Body Elements

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>.

Examples

reStructuredText uses explicit markup blocks for footnotes:

.. [1] This is a footnote.

Pseudo-XML fragment from simple parsing:

<footnote ids="id1" names="1">
    <label>
        1
    <paragraph>
        This is a footnote.

<footnote_reference>

The <footnote_reference> element is an inline element representing a cross reference to a <footnote> (a footnote mark).

Details

Category:

Inline Elements

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.

Attributes:

The <footnote_reference> element contains the common attributes plus auto, refid, and refname.

Examples

A reStructuredText footnote reference and footnote:

[#]_ is an auto-numbered footnote reference.

.. [#] Auto-numbered footnote 1.

Pseudo-XML fragment from simple parsing:

<paragraph>
    <footnote_reference auto="1" ids="id1">
     is an auto-numbered footnote reference.
<footnote auto="1" ids="id3">
    <paragraph>
        Auto-numbered footnote 1.

The references.Footnotes Docutils transform resolves this to:

<paragraph>
    <footnote_reference auto="1" ids="id1" refid="id2">
        1
     is an auto-numbered footnote reference.
<footnote auto="1" backrefs="id1" ids="id2" names="1">
    <label>
        1
    <paragraph>
        Auto-numbered footnote 1.

<generated>

Docutils wraps <generated> elements around text that is inserted (generated) by Docutils; i.e., text that was not in the document, like section numbers inserted by the "sectnum" directive.

To be completed.

<hint>

The <hint> element is an admonition, a distinctive and self-contained notice. See also the generic <admonition> and the other specific admonition elements <attention>, <caution>, <danger>, <error>, <important>, <note>, <tip>, and <warning>.

Details

Category:

Compound Body Elements

Analogues:

<hint> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.

Processing:

Rendered distinctly (inset and/or in a box, etc.), with the generated title "Hint" (or similar).

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <hint>.

Children:

<hint> elements contain one or more body elements.

Attributes:

The <hint> element contains only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <hint>. The %structure.model; parameter entity indirectly includes <hint>.

Examples

A reStructuredText "hint" directive:

.. Hint:: It's bigger than a bread box.

Pseudo-XML fragment from simple parsing:

<hint>
    <paragraph>
        It's bigger than a bread box.

<image>

The <image> element refers to an image resource that should be included in the document.

It is up to the author to ensure compatibility of the image data format with the output format or user agent (LaTeX engine, HTML browser, ...). The reStructuredText Directives documentation contains a non exhaustive table of compatible image formats.

Details

Category:

Simple Body Elements, Inline Elements

Analogues:

<image> is analogous to the HTML <img>, DocBook <imagedata>, and SVG <image> elements.

Processing:

The specified image is included into the output document. Depending on the output format, this is done by referring to the image URI or by embedding the image files content.

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <image>.

Children:

None.

Attributes:

The <image> element contains the common attributes plus uri, alt, align, height, width, scale, and loading.

Parameter Entities:

The %body.elements; parameter entity directly includes <image>. The %structure.model; parameter entity indirectly includes <image>.

Examples

A reStructuredText "image" directive:

.. image:: picture.jpeg
   :width: 20 mm
   :alt: alternate text

Pseudo-XML fragment from simple parsing:

<image alt="alternate text" uri="picture.jpeg" width="20mm">

<important>

The <important> element is an admonition, a distinctive and self-contained notice. See also the generic <admonition> and the other specific admonition elements <attention>, <caution>, <danger>, <error>, <hint>, <note>, <tip>, and <warning>.

Details

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.

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>.

Examples

A reStructuredText "important" directive:

.. Important::

   * Wash behind your ears.
   * Clean up your room.
   * Back up your data.

Pseudo-XML fragment from simple parsing:

<important>
    <bullet_list>
        <list_item>
            <paragraph>
                Wash behind your ears.
        <list_item>
            <paragraph>
                Clean up your room.
        <list_item>
            <paragraph>
                Back up your data.

<inline>

The <inline> element is a generic inline container.

Details

Category:

Inline Elements

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 only the common attributes.

Examples

Custom interpreted text roles create <inline> elements (unless they are based on a standard role).

This reStructuredText source fragment creates and uses a custom role:

.. role:: custom

An example of using :custom:`interpreted text`

Pseudo-XML fragment from simple parsing:

<paragraph>
    An example of using
    <inline classes="custom">
        interpreted text

<label>

To be completed.

<legend>

To be completed.

<line>

The <line> element contains a single line of text, part of a <line_block>.

Details

Category:

Body Subelements (simple)

Analogues:

<line> has no direct analogues in common DTDs. It can be emulated with primitives or type effects.

Processing:

See <line_block>.

Parents:

Only the <line_block> element contains <line>.

Children:

<line> elements may contain text data plus inline elements.

Attributes:

The <line> element contains only the common attributes.

Examples

See <line_block>.

<line_block>

The <line_block> element contains a sequence of lines and nested line blocks. Line breaks (implied between elements) and leading whitespace (indicated by nesting) is significant and must be preserved.

<line_block> elements are commonly used for verse and addresses. See <literal_block> for an alternative useful for program listings and interactive computer sessions.

Details

Category:

Compound Body Elements

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 only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <line_block>. The %structure.model; parameter entity indirectly includes <line_block>.

Examples

A reStructuredText line block:

Take it away, Eric the Orchestra Leader!

| A one, two, a one two three four
|
| Half a bee, philosophically,
|     must, *ipso facto*, half not be.
| But half the bee has got to be,
|     *vis a vis* its entity.  D'you see?
|
| But can a bee be said to be
|     or not to be an entire bee,
|         when half the bee is not a bee,
|             due to some ancient injury?
|
| Singing...

Pseudo-XML fragment from simple parsing:

<paragraph>
    Take it away, Eric the Orchestra Leader!
<line_block>
    <line>
        A one, two, a one two three four
    <line>
    <line>
        Half a bee, philosophically,
    <line_block>
        <line>
            must,
            <emphasis>
                ipso facto
            , half not be.
    <line>
        But half the bee has got to be,
    <line_block>
        <line>
            <emphasis>
                vis a vis
             its entity.  D'you see?
        <line>
    <line>
        But can a bee be said to be
    <line_block>
        <line>
            or not to be an entire bee,
        <line_block>
            <line>
                when half the bee is not a bee,
            <line_block>
                <line>
                    due to some ancient injury?
                <line>
    <line>
        Singing...

<list_item>

The <list_item> element is a container for the elements of a list item.

Details

Category:

Body Subelements (compound)

Analogues:

<list_item> is analogous to the HTML <li> element and to the DocBook <listitem> element.

Processing:

See <bullet_list> or <enumerated_list>.

Parents:

The <bullet_list> and <enumerated_list> elements contain <list_item>.

Children:

<list_item> elements may contain body elements.

Attributes:

The <list_item> element contains only the common attributes.

Examples

A reStructuredText enumerated list with a nested bullet list:

1. Outer list, item 1.

   * Inner list, item 1.
   * Inner list, item 2.

2. Outer list, item 2.

Pseudo-XML fragment from simple parsing:

<enumerated_list enumtype="arabic" prefix="" suffix=".">
    <list_item>
        <paragraph>
            Outer list, item 1.
        <bullet_list bullet="*">
            <list_item>
                <paragraph>
                    Inner list, item 1.
            <list_item>
                <paragraph>
                    Inner list, item 2.
    <list_item>
        <paragraph>
            Outer list, item 2.

See <bullet_list> or <enumerated_list> for further examples.

<literal>

To be completed.

<literal_block>

The <literal_block> element contains a block of text where line breaks and whitespace are significant and must be preserved. <literal_block> elements are commonly used for program listings and interactive computer sessions. See <line_block> for an alternative useful for verse and addresses.

Details

Category:

Simple Body Elements

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>.

Examples

A reStructuredText "parsed-literal" directive:

.. parsed-literal::

    if parsed_literal:
        text = 'is parsed for reStructuredText_ markup'
        spaces_and_linebreaks = 'are preserved'
        markup_processing = **True**

Pseudo-XML fragment from simple parsing:

<literal_block xml:space="preserve">
    if parsed_literal:
        text = 'is parsed for
    <reference name="reStructuredText" refid="restructuredtext">
        reStructuredText
     markup'
        spaces_and_linebreaks = 'are preserved'
        markup_processing =
    <strong>
        True

<literal-block> elements are also generated by a literal block and the "code" directive.

<math>

The <math> element contains text in LaTeX math format [2] that is typeset as mathematical notation (inline formula).

Details

Category:

Inline Elements

Analogues:

<math> is analogous to a HTML/MathML <math> element or the LaTeX ($ math $) mode.

Processing:

Rendered as mathematical notation. If the output format does not support math typesetting, the content may be inserted verbatim.

Parents:

All elements employing the %inline.elements; parameter entities in their content models may contain <math>.

Children:

<math> elements may contain text data.

Attributes:

The <math> element contains only the common attributes.

Example

reStructuredText source:

Euler's identity is the equality :math:`e^{i\pi + 1 = 0`.

Pseudo-XML fragment from simple parsing:

<paragraph>
    Euler’s identity is the equality
    <math>
        e^{\mathrm{i}\pi + 1 = 0
    .

<math_block>

The <math_block> element contains a block of text in LaTeX math format [2] that is typeset as mathematical notation (display formula).

Details

Category:

Simple Body Elements

Analogues:

<math_block> is analogous to a HTML/MathML <math> element displayed as block-level element or a LaTeX equation* environment.

Processing:

Rendered in a block as mathematical notation, typically centered or with indentation If the output format does not support math typesetting, the content may be inserted verbatim.

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <math_block>.

Children:

<math_block> elements contain text data.

Attributes:

The <math> element contains only the common attributes.

Example

The reStructuredText "math" directive generates a <math_block> element:

Euler's identity is the equality

.. math:: e^{i\pi + 1 = 0

Pseudo-XML fragment from simple parsing:

<paragraph>
    Euler’s identity is the equality
<math_block xml:space="preserve">
    e^{i\pi + 1 = 0

<meta>

The <meta> element is a container for "hidden" document bibliographic data, or meta-data (data about the document). It corresponds to the HTML <meta> element.

See also the <docinfo> element for displayed meta-data. The document's title attribute stores the metadata document title.

Details

Category:

Structural Subelements

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.

Attributes:

The <meta> element contains the attributes name, content, http-equiv, lang, dir, media, and scheme that correspond to the respective attributes of the HTML <meta> element.

Example

A reStructuredText "meta" directive:

.. meta::
   :description lang=en: An amusing story
   :description lang=fr: Un histoire amusant

Pseudo-XML fragment from simple parsing:

<meta content="An amusing story" lang="en" name="description">
<meta content="Un histoire amusant" lang="fr" name="description">

<note>

The <note> element is an admonition, a distinctive and self-contained notice. See also the generic <admonition> and the other specific admonition elements <attention>, <caution>, <danger>, <error>, <hint>, <important>, <tip>, and <warning>.

Details

Category:

Compound Body Elements

Analogues:

<note> is analogous to the DocBook <note> element.

Processing:

Rendered distinctly (inset and/or in a box, etc.), with the generated title "Note" (or similar).

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <note>.

Children:

<note> elements contain one or more body elements.

Attributes:

The <note> element contains only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <note>. The %structure.model; parameter entity indirectly includes <note>.

Examples

A reStructuredText "note" directive:

.. Note:: Admonitions can be handy to break up a
   long boring technical document.

Pseudo-XML fragment from simple parsing:

<note>
    <paragraph>
        Admonitions can be handy to break up a
        long boring technical document.

<option>

The <option> element groups an option string together with zero or more option argument placeholders. Note that reStructuredText currently supports only one argument per option.

Details

Category:

Body Subelements

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.

Attributes:

The <option> element contains only the common attributes.

Examples

See the examples for the <option_list> element.

<option_argument>

The <option_argument> element contains placeholder text for option arguments.

Details

Category:

Body Subelements

Analogues:

<option_argument> has no direct analogues in common DTDs.

Processing:

The value of the "delimiter" attribute is prefixed to the <option_argument>, separating it from its <option_string> or a preceding <option_argument>. The <option_argument> text is typically rendered in a monospaced typeface, possibly italicized or otherwise altered to indicate its placeholder nature.

Parents:

Only the <option> element contains <option_argument>.

Children:

<option_argument> elements contain text data only.

Attributes:

The <option_argument> element contains the common attributes plus delimiter.

Examples

See the examples for the <option_list> element.

<option_group>

The <option_group> element groups together one or more <option> elements, all synonyms.

Details

Category:

Body Subelements

Analogues:

<option_group> has no direct analogues in common DTDs.

Processing:

Typically <option> elements within an <option_group> are joined together in a comma-separated list.

Parents:

Only the <option_list_item> element contains <option_group>.

Children:

<option_group> elements contain one or more <option> elements.

Attributes:

The <option_group> element contains only the common attributes.

Examples

See the examples for the <option_list> element.

<option_list>

Each <option_list> element contains a two-column list of command-line options and descriptions, documenting a program's options.

Details

Category:

Compound Body Elements

Analogues:

<option_list> has no direct analogues in common DTDs. It can be emulated with primitives such as tables.

Processing:

An <option_list> is typically rendered as a two-column list, where the first column contains option strings and arguments, and the second column contains descriptions.

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <option_list>.

Children:

<option_list> elements contain one or more <option_list_item> elements.

Attributes:

The <option_list> element contains only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <option_list>. The %structure.model; parameter entity indirectly includes <option_list>.

Examples

A reStructuredText option list:

-a            command-line option "a"
-1 file, --one=file, --two file
              Multiple options with arguments.

Pseudo-XML fragment from simple parsing:

<option_list>
    <option_list_item>
        <option_group>
            <option>
                <option_string>
                    -a
        <description>
            <paragraph>
                command-line option "a"
    <option_list_item>
        <option_group>
            <option>
                <option_string>
                    -1
                <option_argument delimiter=" ">
                    file
            <option>
                <option_string>
                    --one
                <option_argument delimiter="=">
                    file
            <option>
                <option_string>
                    --two
                <option_argument delimiter=" ">
                    file
        <description>
            <paragraph>
                Multiple options with arguments.

<option_list_item>

The <option_list_item> element is a container for a pair of <option_group> and <description> elements.

Details

Category:

Body Subelements

Analogues:

<option_list_item> has no direct analogues in common DTDs.

Processing:

See <option_list>.

Parents:

Only the <option_list> element contains <option_list_item>.

Children:

Each <option_list_item> element contains one <option_group> and one <description> element.

Attributes:

The <option_list_item> element contains only the common attributes.

Examples

See the examples for the <option_list> element.

<option_string>

The <option_string> element contains the text of a command-line option.

Details

Category:

Body Subelements

Analogues:

<option_string> has no direct analogues in common DTDs.

Processing:

The <option_string> text is typically rendered in a monospaced typeface.

Parents:

Only the <option> element contains <option_string>.

Children:

<option_string> elements contain text data only.

Attributes:

The <option_string> element contains only the common attributes.

Examples

See the examples for the <option_list> element.

<organization>

The <organization> element contains the name of document author's organization, or the organization responsible for the document.

Details

Category:

Bibliographic Elements

Analogues:

<organization> is analogous to the DocBook <orgname>, <corpname>, or <publishername> elements.

Processing:

See <docinfo>.

Parents:

Only the <docinfo> element contains <organization>.

Children:

<organization> elements may contain text data plus inline elements (%text.model;).

Attributes:

The <organization> element contains only the common attributes.

Parameter Entities:

The %bibliographic.elements; parameter entity directly includes <organization>.

Examples

In reStructuredText, "organization" is one of the registered bibliographic fields:

Document Title
==============

:Organization: Humankind

Complete pseudo-XML result after parsing and applying transforms:

<document ids="document-title" names="document title">
    <title>
        Document Title
    <docinfo>
        <organization>
            Humankind

See <docinfo> for a more complete example, including processing context.

<paragraph>

The <paragraph> element contains the text and inline elements of a single paragraph, a fundamental building block of documents.

Details

Category:

Simple Body Elements

Analogues:

<paragraph> is analogous to the HTML <p> element and to the DocBook <para> elements.

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <paragraph>.

Children:

<paragraph> elements may contain text data plus inline elements (%text.model;).

Attributes:

The <paragraph> element contains only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <paragraph>. The %structure.model; parameter entity indirectly includes <paragraph>.

Examples

In reStructuredText, blocks of left-aligned text are paragraphs unless marked up as another body element:

A paragraph must be
left-aligned.

Pseudo-XML fragment from simple parsing:

<paragraph>
    A paragraph must be
    left-aligned.

<pending>

To be completed.

<problematic>

To be completed.

<raw>

To be completed.

<reference>

To be completed.

<revision>

The <revision> element contains the revision number of the document. It can be used alone or in conjunction with <version>.

Details

Category:

Bibliographic Elements

Analogues:

<revision> is analogous to but simpler than the DocBook <revision> element. It closely matches the DocBook <revnumber> element, but in a simpler context.

Processing:

Often used with the RCS/CVS keyword "Revision". See <docinfo>.

Parents:

Only the <docinfo> element contains <revision>.

Children:

<revision> elements may contain text data plus inline elements (%text.model;).

Attributes:

The <revision> element contains only the common attributes.

Parameter Entities:

The %bibliographic.elements; parameter entity directly includes <revision>.

Examples

In reStructuredText, "revision" is one of the registered bibliographic fields:

Document Title
==============

:Version: 1
:Revision: b

Complete pseudo-XML result after parsing and applying transforms:

<document ids="document-title" names="document title">
    <title>
        Document Title
    <docinfo>
        <version>
            1
        <revision>
            b

See <docinfo> for a more complete example, including processing context.

<row>

To be completed.

<rubric>

rubric n. 1. a title, heading, or the like, in a manuscript, book, statute, etc., written or printed in red or otherwise distinguished from the rest of the text. ...

—Random House Webster's College Dictionary, 1991

A rubric is like an informal heading that doesn't correspond to the document's structure.

To be completed.

<section>

The <section> element is the main unit of hierarchy for Docutils documents. Docutils <section> elements are a recursive structure; a <section> may contain other <section> elements, without limit. Paragraphs and other body elements may occur before a <section>, but not after it.

Details

Category:

Structural Elements

Analogues:

<section> is analogous to the recursive <section> elements in DocBook and HTML.

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>.

Examples

reStructuredText does not impose a fixed number and order of section title adornment styles. The order enforced will be the order as encountered.

Title 1
=======
Paragraph 1.

Title 2
-------
Paragraph 2.

Title 3
=======
Paragraph 3.

Title 4
-------
Paragraph 4.

Complete pseudo-XML result after parsing:

<document>
    <section ids="title-1" names="title 1">
        <title>
            Title 1
        <paragraph>
            Paragraph 1.
        <section ids="title-2" names="title 2">
            <title>
                Title 2
            <paragraph>
                Paragraph 2.
    <section ids="title-3" names="title 3">
        <title>
            Title 3
        <paragraph>
            Paragraph 3.
        <section ids="title-4" names="title 4">
            <title>
                Title 4
            <paragraph>
                Paragraph 4.

<status>

The <status> element contains a status statement for the document, such as "Draft", "Final", "Work In Progress", etc.

Details

Category:

Bibliographic Elements

Analogues:

<status> is analogous to the DocBook <status> element.

Processing:

See <docinfo>.

Parents:

Only the <docinfo> element contains <status>.

Children:

<status> elements may contain text data plus inline elements (%text.model;).

Attributes:

The <status> element contains only the common attributes.

Parameter Entities:

The %bibliographic.elements; parameter entity directly includes <status>.

Examples

In reStructuredText, "status" is one of the registered bibliographic fields:

Document Title
==============

:Status: Work In Progress

Complete pseudo-XML result after parsing and applying transforms:

<document ids="document-title" names="document title">
    <title>
        Document Title
    <docinfo>
        <status>
            Work In Progress

See <docinfo> for a more complete example, including processing context.

<strong>

To be completed.

<subscript>

To be completed.

<substitution_definition>

The <substitution_definition> element stores a reStructuredText substitution definition.

To be completed.

<substitution_reference>

To be completed.

<subtitle>

The <subtitle> element stores the subtitle of a <document>.

Details

Category:

Structural Subelements

Analogues:

<subtitle> is analogous to the DocBook <subtitle> element. In HTML, subtitles are represented by a <p> element inside a <hgroup> element.

Processing:

A document's subtitle is usually rendered smaller than its <title>.

Parents:

The <document> and <sidebar> elements may contain <subtitle>.

Children:

<subtitle> elements may contain text data plus inline elements (%text.model;).

Attributes:

The <subtitle> element contains only the common attributes.

Examples

In reStructuredText, a lone second-level section title immediately after the “document title” can become the document subtitle:

=======
 Title
=======
----------
 Subtitle
----------

A paragraph.

Complete pseudo-XML result after parsing and applying transforms:

<document ids="title" names="title">
    <title>
        Title
    <subtitle ids="subtitle" names="subtitle">
        Subtitle
    <paragraph>
        A paragraph.

Note how two section levels have collapsed, promoting their titles to become the document's title and subtitle. Since there is only one structural element (document), the subsection's ids and names attributes are stored in the <subtitle> element.

<superscript>

To be completed.

<system_message>

To be completed.

<table>

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]. [3]

Details

Category:

Compound Body Elements

Analogues:

<table> is analogous to the HTML <table> element and the DocBook <table> and <informaltable> elements.

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 common attributes plus align, and width as well as the attributes frame, colsep, rowsep, and pgwide defined in the exchange-table-model.

Parameter Entities:

The %body.elements; parameter entity directly includes <table>. The %structure.model; parameter entity indirectly includes <table>.

Examples

In reStructuredText, tables can be specified via the table, csv-table, or list-table directives or directly as grid table or simple table, e.g.

======== ====
 bread   £2
 butter  £30
======== ====

Pseudo-XML fragment from simple parsing:

<table>
    <tgroup cols="2">
        <colspec colwidth="8">
        <colspec colwidth="4">
        <tbody>
            <row>
                <entry>
                    <paragraph>
                        bread
                <entry>
                    <paragraph>
                        £2
            <row>
                <entry>
                    <paragraph>
                        butter
                <entry>
                    <paragraph>
                        £30
[exchange-table-model] (1,2,3)

XML Exchange Table Model DTD, OASIS Technical Memorandum 9901:1999, http://www.oasis-open.org/html/tm9901.html.

<target>

To be completed.

<tbody>

To be completed.

<term>

The <term> element contains a word or phrase being defined in a <definition_list>.

Details

Category:

Body Subelements (simple)

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.

Examples

See the examples for the <definition_list>, <definition_list_item>, and <classifier> elements.

<tgroup>

See [exchange-table-model].

(colspec*, thead?, tbody)

To be completed.

<thead>

To be completed.

<tip>

The <tip> element is an admonition, a distinctive and self-contained notice. See also the generic <admonition> and the other specific admonition elements <attention>, <caution>, <danger>, <error>, <hint>, <note>, and <warning>.

Details

Category:

Compound Body Elements

Analogues:

<tip> is analogous to the DocBook <tip> element.

Processing:

Rendered distinctly (inset and/or in a box, etc.), with the generated title "Tip" (or similar).

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <tip>.

Children:

<tip> elements contain one or more body elements.

Attributes:

The <tip> element contains only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <tip>. The %structure.model; parameter entity indirectly includes <tip>.

Examples

A reStructuredText "tip" directive:

.. Tip:: 15% if the service is good.

Pseudo-XML fragment from simple parsing:

<tip>
    <paragraph>
        15% if the service is good.

<title>

The <title> element stores the title of a <document> [4], <section>, <sidebar>, <topic>, or generic <admonition>.

Details

Category:

Structural Subelements

Analogues:

<title> is analogous to HTML header elements (<h1> etc.) and to the DocBook <title> element. In contrast, the HTML <title> element corresponds to a <document>'s title attribute.

Parents:

The following elements may contain <title>: <admonition>, <document>, <section>, <sidebar>, <table>, <topic>.

Children:

<title> elements may contain text data plus inline elements (%text.model;).

Attributes:

The <title> element contains the common attributes plus refid (used as a backlink to a table of contents entry) and auto.

Examples

Section titles are marked up with "underlines" below the title text (or underlines and matching overlines):

A Title
=======

A paragraph.

The next section's title
========================

Pseudo-XML fragment from simple parsing:

<section ids="a-title" names="a\ title">
    <title>
        A Title
    <paragraph>
        A paragraph.
<section ids="the-next-section-s-title" names="the\ next\ section's\ title">
    <title>
        The next section’s title

See also the examples for <admonition>, <document>, <section>, <sidebar>, <subtitle>, <table>, and <topic>.

<title_reference>

To be completed.

<topic>

The <topic> element is a non-recursive <section>-like construct which may occur at the top level of a <document>, <section>, or <sidebar> wherever a body element (list, table, etc.) is allowed. In other words, <topic> elements cannot nest inside body elements. You may use a <rubric> element to get an informal heading inside a <table> or a <list>, or inside another <topic>.

Details

Category:

Structural Elements

Analogues:

<topic> is analogous to the DocBook <simplesect> element.

Processing:

A <topic> element should be set off from the rest of the document somehow, such as with indentation or a border.

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>.

Examples

A reStructuredText "topic" directive:

.. topic:: Title

   Body.

Pseudo-XML fragment from simple parsing:

<topic>
    <title>
        Title
    <paragraph>
        Body.

<transition>

The <transition> element is commonly seen in novels and short fiction, as a gap spanning one or more lines, with or without a type ornament such as a row of asterisks.

Transitions separate body elements and sections, dividing a section into untitled divisions. A transition may not begin or end a section [5] or document, nor may two transitions be immediately adjacent.

See also Doctree Representation of Transitions in A Record of reStructuredText Syntax Alternatives.

Details

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>.

Examples

A transition in the reStructuredText source:

Paragraph 1.

--------

Paragraph 2.

Complete pseudo-XML result after parsing:

<document>
    <paragraph>
        Paragraph 1.
    <transition>
    <paragraph>
        Paragraph 2.

<version>

The <version> element contains the version number of the document. It can be used alone or in conjunction with <revision>.

Details

Category:

Bibliographic Elements

Analogues:

<version> may be considered analogous to the DocBook <revision>, <revnumber>, or <biblioid> elements.

Processing:

Sometimes used with the RCS/CVS keyword "Revision". See <docinfo> and <revision>.

Parents:

Only the <docinfo> element contains <version>.

Children:

<version> elements may contain text data plus inline elements (%text.model;).

Attributes:

The <version> element contains only the common attributes.

Parameter Entities:

The %bibliographic.elements; parameter entity directly includes <version>.

Examples

In reStructuredText, "version" is one of the registered bibliographic fields:

Document Title
==============

:Version: 1.1

Complete pseudo-XML result after parsing and applying transforms:

<document ids="document-title" names="document title">
    <title>
        Document Title
    <docinfo>
        <version>
            1.1

See <docinfo> for a more complete example, including processing context.

<warning>

The <warning> element is an admonition, a distinctive and self-contained notice. See also the generic <admonition> and the other specific admonition elements <attention>, <caution>, <danger>, <error>, <hint>, <important>, <note>, and <tip>.

Details

Category:

Compound Body Elements

Analogues:

<warning> is analogous to the DocBook <warning> element.

Processing:

Rendered distinctly (inset and/or in a box, etc.), with the generated title "Warning" (or similar).

Parents:

All elements employing the %body.elements; or %structure.model; parameter entities in their content models may contain <warning>.

Children:

<warning> elements contain one or more body elements.

Attributes:

The <warning> element contains only the common attributes.

Parameter Entities:

The %body.elements; parameter entity directly includes <warning>. The %structure.model; parameter entity indirectly includes <warning>.

Examples

A reStructuredText "warning" directive:

.. WARNING:: Reader discretion is strongly advised.

Pseudo-XML fragment from simple parsing:

<warning>
    <paragraph>
        Reader discretion is strongly advised.

Attribute types

Standard attribute types

Attribute types defined in the attribute types section of the XML 1.0 specification:

CDATA

Character data. CDATA attributes may contain arbitrary text.

NMTOKEN

A "name token". One or more of letters, digits, ".", "-", and "_".

NMTOKENS

One or more space-separated NMTOKEN values.

EnumeratedType

The attribute value may be one of a specified list of values.

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.

Custom attribute types

The Docutils DTD defines parameter entities that resolve to standard attribute types to highlight specific attribute value constraints.

yesorno

Boolean: no if zero ("0"), yes if any other value. Resolves to NMTOKEN.

%yesorno; is used in the anonymous, ltrim, rtrim, and stub attributes.

number

The attribute value must be a number. Resolves to NMTOKEN.

%number; is used in the level, morecols, scale, and start attributes.

measure

A number which may be immediately followed by a unit or percent sign. Resolves to CDATA.

%measure; is used in the height and width attributes.

classnames.type

A space-separated list of class names [6]. Resolves to NMTOKEN.

%classnames.type; is used in the classes attribute.

refname.type

A normalized reference name. Resolves to CDATA (in contrast to NMTOKENS, reference names may consist of any text).

%refname.type; is used in the refname attribute.

refnames.type

A space-separated list of reference names. Resolves to CDATA.

Backslash escaping is used for space characters inside a reference name.

%refnames.type; is used in the names and dupnames attributes.

ids.type

A space-separated list of unique identifier keys [7]. Resolves to NMTOKENS (the XML standard attribute types do not provide for a list of IDs).

%ids.type; is used in the ids attribute.

idref.type

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).

%idref.type; is used in the refid attribute.

idrefs.type

A list of references to element identifiers. Resolves to NMTOKENS.

%idrefs.type; is used in the backrefs attribute.

Attribute Reference

Common Attributes:

Through the %basic.atts; parameter entity, all elements support the following attributes: ids, names or dupnames, source, and classes.

alt

Attribute type: CDATA. Default value: none.

The alt attribute is used to store a text description in the <image> element.

align

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).

anonymous

Attribute type: yesorno. Default value: none (implies no).

The anonymous attribute is used for unnamed hyperlinks in the <target> and <reference> elements (via the %anonymous.att; parameter entity).

auto

Attribute type: CDATA. Default value: none.

The auto attribute is used to indicate automatically-numbered <footnote>, <footnote_reference> and <title> elements (via the %auto.att; parameter entity).

backrefs

Attribute type: idrefs.type. Default value: none.

The backrefs attribute contains a space-separated list of identifier references, used for backlinks from <footnote>, <citation>, and <system_message> elements (via the %backrefs.att; parameter entity).

bullet

Attribute type: CDATA. Default value: none.

The bullet attribute is used in the <bullet_list> element to record the style of bullet from the input data. In documents processed from reStructuredText, it contains one of "-", "+", or "*". It may be ignored in processing.

classes

Attribute type: classnames.type. Default value: none.

The classes attribute is a space separated list containing zero or more class names.

The purpose of the attribute is to indicate an "is-a" variant relationship, to allow an extensible way of defining sub-classes of existing elements. It can be used to carry context forward between a Docutils Reader and Writer, when a custom structure is reduced to a standardized document tree. One common use is in conjunction with stylesheets, to add selection criteria. It should not be used to carry formatting instructions or arbitrary content.

The classes attribute's contents should be ignorable. Writers that are not familiar with the variant expressed should be able to ignore the attribute.

classes is one of the common attributes, shared by all Docutils elements.

colwidth

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.

delimiter

Attribute type: CDATA. Default value: none.

The delimiter attribute is used in the <option_argument> element and contains the text preceding the <option_argument>: either the text separating it from the <option_string> (typically either "=" or " ") or the text between option arguments (typically either "," or " ").

dupnames

Attribute type: refnames.type. Default value: none.

dupnames is one of the common attributes, shared by all Docutils elements. It replaces the names attribute when there has been a naming conflict.

enumtype

Attribute type: EnumeratedType, one of "arabic", "loweralpha", "upperalpha", "lowerroman", or "upperroman". Default value: none.

The enumtype attribute is used in the <enumerated_list> element.

height

Attribute type: measure. Default value: none.

The height attribute is used in the <image> element.

ids

Attribute type: ids.type. Default value: none.

The ids attribute is a space separated list containing one or more unique identifier keys, typically assigned by the system.

ids is one of the common attributes, shared by all Docutils elements.

level

Attribute type: number. Default value: none.

The level attribute is used in the <system_message> element.

ltrim

Attribute type: yesorno. Default value: none (implies no).

The ltrim attribute is used in the <substitution_definition> element.

loading

Attribute type: EnumeratedType, one of "embed", "link", or "lazy". Default value: none.

The loading attribute is used in the <image> element to indicate the preferred handling by the Docutils writer. [8] The default depends on the writer and the image_loading configuration setting.

morecols

Attribute type: number. Default value: none.

The morecols attribute is used in the <table> element.

names

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.

prefix

Attribute type: CDATA. Default value: none.

The prefix attribute is used in the <enumerated_list> element.

refid

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).

refname

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).

refuri

Attribute type: CDATA. Default value: none.

The refuri attribute contains an external reference to a URI/URL. It is used by the <target>, <reference>, <footnote_reference>, and <citation_reference> elements (via the %reference.atts; parameter entity).

rtrim

Attribute type: yesorno. Default value: none (implies no).

The rtrim attribute is used in the <substitution_definition> element.

scale

Attribute type: number. Default value: none.

The scale attribute is used in the <image> element to store a uniform scaling factor (integer percentage value).

source

Attribute type: CDATA. Default value: none.

The source attribute 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.

start

Attribute type: number. Default value: none.

The start attribute is used in the <enumerated_list> element.

stub

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.

suffix

Attribute type: CDATA. Default value: none.

The suffix attribute is used in the <enumerated_list> element.

title

Attribute type: CDATA. Default value: none.

The title attribute stores the title metadata of a <document>. This title is typically not part of the rendered document. It may for example be used in HTML's title element.

uri

Attribute type: CDATA. Default value: none.

The uri attribute is used in the <image> and <figure> elements to refer to the image via its Universal Resource Indicator.

width

Attribute type: measure. Default value: none.

The width attribute is used in the <figure>, <image>, and <table> element.

xml:space

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 Entity Reference

Parameter entities are used to simplify the DTD (to share definitions and reduce duplication) and to allow the DTD to be customized by wrapper DTDs (external client DTDs that use or import the Docutils DTD). Parameter entities may be overridden by wrapper DTDs, replacing the definitions below with custom definitions. Parameter entities whose names begin with "additional" are meant to allow easy extension by wrapper DTDs.

%align-h.att;

The %align-h.att; parameter entity contains the align attribute for horizontal alignment.

Entity definition:

align (left | center | right) #IMPLIED

The <figure> and <table> elements directly employ the %align-h.att; parameter entity in their attribute lists.

%align-hv.att;

The %align-hv.att; parameter entity contains the align attribute for horizontal and vertical alignment.

Entity definition:

align (top | middle | bottom | left | center | right) #IMPLIED

The <image> element directly employs the %align-hv.att; parameter entity in its attribute list.

%anonymous.att;

The %anonymous.att; parameter entity contains the anonymous attribute, used for unnamed hyperlinks.

Entity definition:

anonymous %yesorno; #IMPLIED

The <reference> and <target> elements directly employ the %anonymous.att; parameter entity in their attribute lists.

%auto.att;

The %auto.att; parameter entity contains the auto attribute, used to indicate an automatically-numbered footnote or title.

Entity definition:

auto CDATA #IMPLIED

The <footnote>, <footnote_reference>, and <title> elements directly employ the %auto.att; parameter entity in their attribute lists.

%backrefs.att;

The %backrefs.att; parameter entity contains the backrefs attribute, a space-separated list of id references, for backlinks.

Entity definition:

backrefs %idrefs.type; #IMPLIED

The <citation>, <footnote>, and <system_message> elements directly employ the %backrefs.att; parameter entity in their attribute lists.

%basic.atts;

The %basic.atts; parameter entity lists the common attributes.

Entity definition:

ids      NMTOKENS  #IMPLIED
names    CDATA     #IMPLIED
dupnames CDATA     #IMPLIED
source   CDATA     #IMPLIED
classes  NMTOKENS  #IMPLIED
%additional.basic.atts;

The %additional.basic.atts; parameter entity can be used by wrapper DTDs to extend %basic.atts;.

%bibliographic.elements;

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.

%body.elements;

The %body.elements; parameter entity contains an OR-list of all body elements. %body.elements; is itself contained within the %structure.model; parameter entity.

Entity definition:

paragraph | compound | container | literal_block | doctest_block
| math_block | line_block | block_quote
| table | figure | image | footnote | citation | rubric
| bullet_list | enumerated_list | definition_list | field_list
| option_list
| attention | caution | danger | error | hint | important | note
| tip | warning | admonition
| reference | target | substitution_definition | comment | pending
| system_message | raw
%additional.body.elements;

The %additional.body.elements; parameter entity can be used by wrapper DTDs to extend %body.elements;.

The %body.elements; parameter entity is directly employed in the content models of the following elements: <admonition>, <attention>, <block_quote>, <caution>, <citation>, <compound>, <danger>, <definition>, <description>, <entry>, <error>, <field_body>, <footer>, <footnote>, <header>, <hint>, <important>, <legend>, <list_item>, <note>, <sidebar>, <system_message>, <tip>, <topic>, and <warning>

Via %structure.model;, the %body.elements; parameter entity is indirectly employed in the content models of the <document> and <section> elements.

%fixedspace.att;

The %fixedspace.att; parameter entity contains the xml:space attribute, a standard XML attribute for whitespace-preserving elements.

Entity definition:

xml:space (default | preserve) #FIXED 'preserve'

The %fixedspace.att; parameter entity is directly employed in the attribute lists of the following elements: <address>, <comment>, <doctest_block>, <line_block>, <literal_block>, <raw>

%inline.elements;

The %inline.elements; parameter entity contains an OR-list of all inline elements.

Entity definition:

emphasis | strong | literal | math
| reference | footnote_reference | citation_reference
| substitution_reference | title_reference
| abbreviation | acronym | subscript | superscript
| inline | problematic | generated
| target | image | raw
%additional.inline.elements;

The %additional.inline.elements; parameter entity can be used by wrapper DTDs to extend %inline.elements;.

Via %text.model;, the %inline.elements; parameter entity is indirectly employed in the content models of the following elements: <abbreviation>, <acronym>, <address>, <attribution>, <author>, <caption>, <classifier>, <contact>, <copyright>, <date>, <doctest_block>, <emphasis>, <generated>, <inline>, <line_block>, <literal_block>, <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>

%reference.atts;

The %reference.atts; parameter entity groups together the refuri, refid, and refname attributes.

Entity definition:

%refuri.att;
%refid.att;
%refname.att;
%additional.reference.atts;

The %additional.reference.atts; parameter entity can be used by wrapper DTDs to extend %additional.reference.atts;.

The <citation_reference>, <footnote_reference>, <reference>, and <target> elements directly employ the %reference.att; parameter entity in their attribute lists.

%refid.att;

The %refid.att; parameter entity contains the refid attribute, an internal reference to the ids attribute of another element.

Entity definition:

refid %idref.type; #IMPLIED

The <title> and <problematic> elements directly employ the %refid.att; parameter entity in their attribute lists.

Via %reference.atts;, the %refid.att; parameter entity is indirectly employed in the attribute lists of the <citation_reference>, <footnote_reference>, <reference>, and <target> elements.

%refname.att;

The %refname.att; parameter entity contains the refname attribute, an internal reference to the names attribute of another element. On a <target> element, refname indicates an indirect target which may resolve to either an internal or external reference.

Entity definition:

refname %refname.type; #IMPLIED

The <substitution_reference> element directly employs the %refname.att; parameter entity in its attribute list.

Via %reference.atts;, the %refname.att; parameter entity is indirectly employed in the attribute lists of the <citation_reference>, <footnote_reference>, <reference>, and <target> elements.

%refuri.att;

The %refuri.att; parameter entity contains the refuri attribute, an external reference to a URI/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.

%section.elements;

The %section.elements; parameter entity contains an OR-list of all <section>-equivalent elements. %section.elements; is itself contained within the %structure.model; parameter entity.

Entity definition:

section
%additional.section.elements;

The %additional.section.elements; parameter entity can be used by wrapper DTDs to extend %section.elements;.

Via %structure.model;, the %section.elements; parameter entity is indirectly employed in the content models of the <document> and <section> elements.

%structure.model;

The %structure.model; parameter entity encapsulates the hierarchical structure of a document and of its constituent parts. See the discussion of the element hierarchy above.

Entity definition:

( ( (%body.elements; | topic | sidebar)+, transition? )*,
  ( (%section.elements;), (transition?, (%section.elements;) )* )? )

Each <document> or <section> contains zero or more body elements, topics, and/or sidebars, optionally interspersed with single transitions, followed by zero or more sections (whose contents are recursively the same as this model) optionally interspersed with transitions.

The following restrictions are imposed by this model:

  • Transitions must be separated by other elements (body elements, sections, etc.). In other words, a transition may not be immediately adjacent to another transition.

  • A transition may not occur at the beginning of a document or section.

The %structure.model; parameter entity is directly employed in the content models of the <document> and <section> elements.

%text.model;

The %text.model; parameter entity is used by many elements to represent text data mixed with inline elements.

Entity definition:

(#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>