The Docutils Document Tree

Element Categories

Introduction

Each element in the Docutils Generic DTD is described in its own section below. Each section contains the following items:

• Summary description (up to two sentences).

• Details (of element relationships and semantics):

  Category:

  One or more references to the element categories in the Element Hierarchy above. Some elements belong to more than one category.

  Analogues:

  Analogous elements in well-known document models such as HTML [html.spec] or DocBook [tdg5.1]. Describes similarities and differences.

  Processing:

  Formatting or rendering recommendations for the element.

  Parents:

  Elements which may contain the element.

  Children:

  Elements which may occur within the element. Optionally followed by the formal XML content model from the Docutils Generic DTD.

  Attributes:

  XML Attributes that are defined for this element.

  Parameter Entities:

  Parameter entities which directly or indirectly include the element (if applicable and not already implied by the element category).

• Additional free text description and explanations (optional).

• Examples: reStructuredText examples are shown along with fragments of the document trees resulting from parsing. Pseudo-XML is used to display the results of parsing and processing.

<abbreviation>

The <abbreviation> element is an inline element representing an abbreviation, a shortened or contracted form of a word or phrase used to represent the whole.

Category:

Inline Elements

Analogues:

<abbreviation> is analogous to the DocBook <abbrev> element. The HTML <abbr> element is used for both, abbreviations and acronyms.

Processing:

May be used to semantically mark the presence of an abbreviation in the text for styling or scripting purposes. Writers may ignore the element and just render its contents.

Parents:

all elements employing %text.model in their content models

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

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

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

<acronym>

The <acronym> element is an inline element used to represent an acronym (abbreviation formed by the initial letters of other words).

Category:

Inline Elements

Analogues:

<acronym> is analogous to the DocBook <acronym> element. The HTML <abbr> element is used for both, abbreviations and acronyms.

Processing:

May be used to semantically mark the presence of an acronym in the text for styling or scripting purposes. Writers may ignore the element and just render its contents.

Parents:

all elements employing %text.model in their content models

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

`WWW`:acronym: is the acronym for the world wide web.

<paragraph>
    <acronym>
        WWW
    is the acronym for the world wide web.

<address>

The <address> element holds the surface mailing address information for the author(s) (individual or group) of the document, or a third-party contact address.

Category:

Bibliographic Elements

Analogues:

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

Processing:

As with the <literal_block> element, newlines are significant and must be preserved. However, a monospaced typeface should not be used.

Parents:

<docinfo>, <authors>

Children:

text data plus inline elements (%text.model)

Attributes:

the common attributes and xml:space.

The <address> element is only valid in the bibliographic data (<docinfo>). You may use a <line_block> to format addresses in the document body.

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

:Address: 123 Example Ave.
          Example, EX

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

<admonition>

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

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 %body.elements or %structure.model in their content models

Children:

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

Attributes:

only the common attributes.

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

.. admonition:: By the way...

   You can make up your own admonition too.

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

<attention>

The <attention> element is a specific admonition, a distinctive and self-contained notice.

Category:

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 %body.elements or %structure.model in their content models

Children:

one or more body elements

Attributes:

only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

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

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

Category:

Bibliographic Elements

Analogues:

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

Processing:

see <docinfo>

Parents:

<docinfo>, <authors>

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

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

:Author: J. Random Hacker

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

<authors>

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

Category:

Bibliographic Elements

Analogues:

<authors> is analogous to the DocBook <authorgroup> element.

Processing:

See <docinfo>.

Parent:

<docinfo>

Children:

<author>, <organization>, <address>, <contact>:

((author, organization?, address?, contact?)+)

Attributes:

only the common attributes.

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

:Authors: J. Random Hacker; Jane Doe

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

<block_quote>

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

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 %body.elements or %structure.model in their content models

Children:

body elements followed by an optional <attribution>

Attributes:

only the common attributes.

As a great palaeontologist once said,

    This theory, that is mine, is mine.

    -- Anne Elk (Miss)

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

<bullet_list>

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

Category:

Compound Body Elements

Analogues:

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

Processing:

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

Parents:

all elements employing %body.elements or %structure.model in their content models

Children:

one or more <list_item> elements

Attributes:

the common attributes and bullet.

- Item 1, paragraph 1.

  Item 1, paragraph 2.

- Item 2.

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

<caption>

To be completed.

<caution>

The <caution> element is a specific admonition, a distinctive and self-contained notice. See also the generic <admonition> and the other specific admonition elements.

Category:

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 %body.elements or %structure.model in their content models

Children:

one or more body elements

Attributes:

only the common attributes.

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

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

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>

Parent:

<definition_list_item>

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

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

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

<colspec>

The <colspec> element contains specifications for a column in a <table>. It is defined in the Exchange Table Model.

Category:

Body Subelements

Analogues:

<colspec> is analogous to the DocBook <colspec> element. The HTML <col> element is related but has different semantics.

Processing:

See colspec in the Exchange Table Model.

Parent:

<tgroup>

Children:

none (empty)

Attributes:

The Exchange Table Model defines the attributes align, char, charoff, colname, colnum, colsep, colwidth, and rowsep. [3] Via the %tbl.colspec.att parameter entity, <colspec> also accepts the common attributes and stub.

<comment>

To be completed.

<compound>

The <compound> element combines multiple body elements to a single logical paragraph.

Category:

Compound Body Elements

Analogues:

The <compound> element has no direct analogues in common DTDs. In HTML, it can be emulated with <div> and CSS styling. [4]

Processing:

Typically rendered as multiple distinct text blocks, with the possibility of variations to emphasize their logical unity (cf. the "compound" directive).

Parents:

all elements employing %body.elements or %structure.model in their content models

Children:

one or more body elements

Attributes:

only the common attributes.

.. compound::

   The 'rm' command is very dangerous.  If you are logged
   in as root and enter ::

       cd /
       rm -rf *

   you will erase the entire contents of your file system.

<compound>
    <paragraph>
        The 'rm' command is very dangerous.  If you are logged
        in as root and enter
    <literal_block xml:space="preserve">
        cd /
        rm -rf *
    <paragraph>
        you will erase the entire contents of your file system.

<contact>

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

Category:

Bibliographic Elements

Analogues:

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

Processing:

See <docinfo>.

Parents:

<docinfo>, <authors>

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

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

:Contact: jrh@example.com

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

<container>

The <container> element groups multiple body elements for user- or application-specific purposes.

Category:

Compound Body Elements

Analogues:

The <container> element is analogous to the HTML <div> element or the SVG <g> element.

Processing:

Can be used for styling or scripting purposes. An example is a frame or background colour based on the value of the classes attribute.

Parents:

all elements employing %body.elements or %structure.model in their content models

Children:

one or more body elements

Attributes:

only the common attributes.

.. container:: green boxed-equation

   .. math:: -1^2 = 1

   This paragraph is in the box, too.

<container classes="framed square">
    <math_block xml:space="preserve">
        -1^2 = 1
    <paragraph>
        This paragraph is in the box, too.

div.framed {border: solid;
         padding: 1em;}

<copyright>

The <copyright> element contains the document's copyright statement.

Category:

Bibliographic Elements

Analogues:

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

Processing:

see <docinfo>

Parent:

<docinfo>

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

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

:Copyright: This document has been placed in the public domain.

<document ids="document-title" names="document title">
    <title>
        Document Title
    <docinfo>
        <copyright>
            This document has been placed in the public domain.

<danger>

The <danger> element is a specific admonition, a distinctive and self-contained notice.

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 %body.elements or %structure.model in their content models

Children:

one or more body elements

Attributes:

only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

.. DANGER:: Mad scientist at work!

<danger>
    <paragraph>
        Mad scientist at work!

<date>

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

Category:

Bibliographic Elements

Analogues:

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

Processing:

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

Parent:

<docinfo>

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

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

:Date: 2002-08-20

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

<decoration>

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

Category:

Structural Subelements

Analogues:

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

Processing:

See the individual decorative elements.

Parent:

<document>

Children:

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

Attributes:

only the common attributes.

<definition>

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

Category:

Body Subelements (compound)

Analogues:

<definition> is analogous to the HTML <dd> element and to the DocBook <listitem> element (inside a <variablelistentry> element).

Processing:

see <definition_list_item>

Parent:

<definition_list_item>

Children:

body elements

Attributes:

only the common attributes.

<definition_list>

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

Category:

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 %body.elements or %structure.model in their content models

Children:

one or more <definition_list_item> elements

Attributes:

only the common attributes.

See also <field_list>.

Term
    Definition.

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

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

<definition_list_item>

A wrapper for a set of terms (with optional classifiers) and the associated definition in a <definition_list>.

Category:

Body Subelements (compound)

Analogues:

<definition_list_item> is analogous to the DocBook <variablelistentry> element.

Processing:

The optional <classifier>s can be rendered differently from the <term>. They should be separated visually, typically by spaces plus a colon or dash.

Parent:

<definition_list>

Children:

<definition_list_item> elements each contain one or more <term> elements, zero or more <classifier> elements, and a <definition>:

((term, classifier*)+, definition)

Changed in Docutils 0.22: allow multiple terms.

Attributes:

only the common attributes.

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)

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

<description>

The <description> element is the part of an <option_list> item that contains the description of a command-line option or group of options.

Category:

Body Subelements

Analogues:

<description> has no direct analogues in common DTDs.

Processing:

see <option_list>

Parent:

<option_list_item>

Children:

body elements

Attributes:

only the common attributes.

<docinfo>

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

Category:

Structural Subelements

Analogues:

There are no directly analogous HTML or DocBook elements. The DocBook <info> element is related but ususally suppressed in the output.

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.

Parent:

<document>

Children:

bibliographic elements

Attributes:

only the common attributes.

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

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.

<document ids="docinfo-example" names="docinfo example">
    <title>
        Docinfo Example
    <docinfo>
        <author>
            J. Random Hacker
        <contact>
            <reference refuri="mailto:jrh@example.com">
                jrh@example.com
        <date>
            2002-08-18
        <status>
            Work In Progress
        <version>
            1
        <field classes="filename">
            <field_name>
                Filename
            <field_body>
                <paragraph>
                    doctree.rst
        <copyright>
            This document has been placed in the public domain.

<doctest_block>

The <doctest_block> element is a Python-specific variant of a <literal_block>.

Category:

Simple Body Elements

Analogues:

<doctest_block> is analogous to the HTML <pre> element and 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 %body.elements or %structure.model in their content models

Children:

text data plus inline elements (%text.model)

Attributes:

the common attributes and xml:space.

This is an ordinary paragraph.

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

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

<document>

The <document> element is the root (topmost) element of the Docutils document tree.

Category:

Root Element

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:

structural elements, structural subelements, and body elements

( (title, subtitle?)?,
  meta*,
  decoration?,
  (docinfo, transition?)?,
  %structure.model; )

See the %structure.model parameter entity for details of the body of a <document>.

Attributes:

the common attributes and title.

<document> is the direct or indirect ancestor of every other element in the tree. It encloses the entire document tree. It is the starting point for a document.

Depending on the source of the data and the stage of processing, the <document> may not initially contain a <title>. A document title is not directly representable in reStructuredText. Instead, the DocTitle transform may promote a lone top-level section title to become the document <title>, and similarly a lone second-level (sub)section's title to become the document <subtitle>.

The contents of "<decoration>" may be specified in a document, constructed programmatically, or both.

The "<docinfo>" may be transformed from an initial <field_list>.

A Title
=======

A paragraph.

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

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

<emphasis>

The <emphasis> element is an inline element representing text that has stress emphasis.

Category:

Inline Elements

Analogues:

<emphasis> is analogous to the HTML <em> element and the DocBook <emphasis> element.

Processing:

Typically displayed in italic type.

Parents:

all elements employing %text.model in their content models

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

There are :emphasis:`two` ways to *emphasize* text.

<paragraph>
    There are
    <emphasis>
        two
     ways to
    <emphasis>
        emphasize
     text.

<entry>

The <entry> element represents one cell of a <table>. It is defined in the Exchange Table Model.

Category:

Body Subelements

Analogues:

<entry> is analogous to the DocBook <entry> element. HTML differentiates between header entries <td> and data entries <td>.

Processing:

Render content in a table cell. The morecols and morerows attributes may be used to define an entry spanning several table cells. See entry in the Exchange Table Model for details.

Parents:

<thead>, <tbody>

Children:

body elements (via the %tbl.entry.mdl parameter entity)

Attributes:

The <entry> element accepts the colname, namest, nameend, morerows, colsep, rowsep, align, char, charoff, and valign attributes (ignored by Docutils) and (via the %tbl.entry.att parameter entity) the common attributes and morecols.

<enumerated_list>

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

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 %body.elements or %structure.model in their content models

Children:

one or more <list_item> elements

Attributes:

enumtype, prefix, suffix, start, and the common attributes.

1. Item 1.

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

2. Item 2.

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

<error>

The <error> element is a specific admonition, a distinctive and self-contained notice.

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 %body.elements or %structure.model in their content models

Children:

one or more body elements

Attributes:

only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

.. Error:: Does not compute.

<error>
    <paragraph>
        Does not compute.

<field>

The <field> element contains one item of a <field_list>, a pair of <field_name> and <field_body> elements.

Category:

Body Subelements, Bibliographic Elements

Analogues:

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

Processing:

See <field_list>.

Parents:

<docinfo>, <field_list>

Children:

one <field_name> and one <field_body> element

Attributes:

only the common attributes.

<field_body>

The <field_body> element is analogous to a database field's data.

Category:

Body Subelements

Analogues:

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

Processing:

see <field_list>

Parent:

<field>

Children:

body elements

Attributes:

only the common attributes.

<field_list>

The <field_list> element contains two-column table-like structures resembling database records (label & data pairs).

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 %body.elements or %structure.model in their content models

Children:

one or more <field> elements

Attributes:

only the common attributes.

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.

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

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

<field_name>

The <field_name> element is analogous to a database field's name.

Category:

Body Subelements (simple)

Analogues:

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

Processing:

See <field_list>.

Parent:

<field>

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

<figure>

To be completed.

<footer>

The <footer> element is a container element whose contents are meant to appear at the bottom of a web page, or repeated at the bottom of every printed page.

Category:

Decorative Elements

Analogues:

<footer> is analogous to the HTML <footer> element. There are no direct analogies to <footer> in HTML4 or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system.

Parent:

<decoration>

Children:

body elements

Attributes:

only the common attributes.

The <footer> element may contain processing information (datestamp, a link to Docutils, etc.) as well as custom content.

A paragraph.

<document>
    <decoration>
        <footer>
            <paragraph>
                Generated on: 2002-08-20.
    <paragraph>
        A paragraph.

<footnote>

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

Category:

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 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 %body.elements or %structure.model in their content models

Children:

<footnote> elements begin with an optional [6] <label> and contain body elements.

(label?, (%body.elements;)+)

Attributes:

the common attributes plus auto and backrefs.

.. [1] This is a footnote.

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

<footnote_reference>

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

Category:

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 in square brackets.

Parents:

all elements employing %text.model in their content models

Children:

only text data

Attributes:

auto, refid, refname, and _the common attributes.

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

.. [#] First auto-numbered footnote.

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

<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>
        First auto-numbered footnote.

<generated>

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

To be completed.

<header>

The <header> element is a container element whose contents are meant to appear at the top of a web page, or at the top of every printed page.

Category:

Decorative Elements

Analogues:

<header> is analogous to the HTML <header> element. There are no direct analogies to <header> in HTML4 or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system.

Parent:

<decoration>

Children:

body elements

Attributes:

only the common attributes.

.. header:: This space for rent.

<document>
    <decoration>
        <header>
            <paragraph>
                This space for rent.

<hint>

The <hint> element is a specific admonition, a distinctive and self-contained notice.

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 %body.elements or %structure.model in their content models

Children:

one or more body elements

Attributes:

only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

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

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

<image>

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

Categories:

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

Parents:

all elements employing %body.elements, %text.model, or %structure.model in their content models

Children:

none (empty)

Attributes:

uri, alt, align, height, width, scale, loading, and the common attributes.

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.

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

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

<important>

The <important> element is a specific admonition, a distinctive and self-contained notice.

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 %body.elements or %structure.model in their content models

Children:

one or more body elements

Attributes:

only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

.. Important::

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

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

<inline>

The <inline> element is a generic inline container.

Category:

Inline Elements

Analogues:

<inline> is analogous to the HTML <span> element and the DocBook <phrase> element.

Processing:

Writers typically pass the classes attribute to the output document and leave styling to the backend or a custom stylesheet. They may also process the classes attribute and convert the <inline> element to a specific element or render the content distinctly for specific class values. Moreover, writers may ignore the element and just render the content.

Parents:

all elements employing %text.model in their content models

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

.. role:: custom

An example of using :custom:`interpreted text`

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

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

Parent:

<line_block>

Children:

text data plus inline elements

Attributes:

only the common attributes.

<line_block>

The <line_block> element is a “plain list” of lines and nested line blocks. It is commonly used for verse and addresses.

Category:

Compound Body Elements

Analogues:

<line_block> has no direct analogues in common DTDs. Is is related to the DocBook <literallayout> element, however <literallayout> is a verbatim environment which directly contains text.

Processing:

Each <line> should begin a new vertical block, without markers or additional spacing. Nested <line_blocks> should be indented.

Parents:

all elements employing %body.elements or %structure.model in their content models

Children:

<line>, <line_block>

Attributes:

only the common attributes.

See <literal_block> for an alternative useful for program listings and interactive computer sessions.

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

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

<list_item>

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

Category:

Body Subelements (compound)

Analogues:

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

Processing:

See <bullet_list> or <enumerated_list>.

Parents:

<bullet_list>, <enumerated_list>

Children:

body elements

Attributes:

only the common attributes.

1. Outer list, item 1.

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

2. Outer list, item 2.

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

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

.. parsed-literal::

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

<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

.. code:: python

       print(8/2)

<literal_block classes="code python" xml:space="preserve">
    <inline classes="name builtin">
        print
    <inline classes="punctuation">
        (
    <inline classes="literal number integer">
        8
    <inline classes="operator">
        /
    <inline classes="literal number integer">
        2
    <inline classes="punctuation">
        )

<math>

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

Category:

Inline Elements

Analogues:

<math> is related to the <math> element in MathML and HTML. However, it contains text data only.

Processing:

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

Parents:

all elements employing %text.model in their content models

Children:

only text data

Attributes:

only the common attributes.

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

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

<math_block>

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

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 %body.elements or %structure.model in their content models

Children:

only text data

Attributes:

the common attributes and xml:space.

Euler's identity is the equation

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

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

<meta>

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

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

Parent:

<document>

Children:

none (empty)

Attributes:

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

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

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

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

<note>

The <note> element is a specific admonition, a distinctive and self-contained notice.

Category:

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 %body.elements or %structure.model in their content models

Children:

one or more body elements

Attributes:

only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

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

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

<option>

The <option> element groups an option string together with zero or more option argument placeholders.

Category:

Body Subelements

Analogues:

<option> has no direct analogues in common DTDs.

Processing:

See <option_list>.

Parent:

<option_group>

Children:

<option> elements start with an <option_string> and may contain <option_argument> elements:

(option_string, option_argument*)

Attributes:

only the common attributes.

Note that reStructuredText currently supports only one argument per option.

<option_argument>

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

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.

Parent:

<option>

Children:

only text data

Attributes:

the common attributes and delimiter.

<option_group>

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

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.

Parent:

<option_list_item>

Children:

one or more <option> elements.

Attributes:

only the common attributes.

<option_list>

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

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 %body.elements or %structure.model in their content models

Children:

one or more <option_list_item> elements.

Attributes:

only the common attributes.

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

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

<option_list_item>

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

Category:

Body Subelements

Analogues:

<option_list_item> has no direct analogues in common DTDs.

Processing:

see <option_list>

Parent:

<option_list>

Children:

one <option_group> and one <description>

Attributes:

only the common attributes.

<option_string>

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

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.

Parent:

<option>

Children:

only text data

Attributes:

only the common attributes.

<organization>

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

Category:

Bibliographic Elements

Analogues:

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

Processing:

See <docinfo>.

Parent:

<docinfo>

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

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

:Organization: Humankind

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

<paragraph>

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

Category:

Simple Body Elements

Analogues:

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

Parents:

all elements employing %body.elements or %structure.model in their content models

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

A paragraph must be
left-aligned.

<paragraph>
    A paragraph must be
    left-aligned.

<pending>

To be completed.

<problematic>

The <problematic> element highlights a source part that caused a parsing problem.

Category:

Inline Elements

Analogues:

<problematic> has no direct analogues in common DTDs.

Processing:

Typically displayed in red colour. If the refid attribute is present, the element should point to the referenced element.

Parents:

all elements employing %text.model in their content models

Children:

text data plus inline elements (%text.model)

Attributes:

the common attributes and refid.

a single *star

<paragraph>
    a single
    <problematic ids="problematic-1" refid="system-message-1">
        *
    star
<system_message backrefs="problematic-1" ids="system-message-1"
                level="2" line="1" source="example.rst" type="WARNING">
    <paragraph>
        Inline emphasis start-string without end-string.

<raw>

The <raw> element contains non-reStructuredText data that is to be passed untouched to the Writer.

Category:

Simple Body Elements, Inline Elements

Analogues:

The <raw> element has no direct analogues in common DTDs.

Processing:

Passed untouched to the Writer. The interpretation is up to the Writer. A Writer may ignore <raw> elements not matching its format.

Parents:

all elements employing %body.elements, %structure.model, or %text.model in their content models

Children:

only text data

Attributes:

format, xml:space and the common attributes.

.. raw:: html

   <hr width=50 size=10>

<raw format="html" xml:space="preserve">
    <hr width=50 size=10>

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

Category:

Bibliographic Elements

Analogues:

<revision> is similar 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>.

Parent:

<docinfo>

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

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

:Version: 1
:Revision: b

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

<row>

The <row> element represents one row of a <table>. It is defined in the Exchange Table Model.

Category:

Body Subelements

Analogues:

<row> is analogous to the HTML <tr> element and the DocBook <row> element.

Processing:

Render content as a table row. See row in the Exchange Table Model for details.

Parents:

<thead>, <tbody>

Children:

one or more <entry> elements

Attributes:

The <row> element may contain the rowsep and valign attributes (ignored by Docutils) and (via the %tbl.row.att parameter entity) the common attributes.

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

Category:

Structural Elements

Analogues:

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

Parents:

<document>, <section>

Children:

<section> elements begin with a <title>, followed by an optional <subtitle>. They may contain structural elements, body elements, and <transition> elements:

(title, subtitle?, %structure.model;)

Attributes:

only the common attributes

Parameter Entities:

%section.elements directly includes <section>, %structure.model indirectly includes <section>.

The Docutils document model uses a simple, recursive model for section structure. A <document> nodeelements. Sections in turn may contain other <section> elements, without limit. The level (depth) of a section element is determined from its physical nesting level.

Paragraphs and other body elements may occur before a <section>, but not after it.

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

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

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

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

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

<sidebar>

Sidebars are like miniature, parallel documents that occur inside other documents, providing related or reference material. Their content is outside of the flow of the document's main text.

Category:

Structural Elements

Analogues:

<sidebar> is analogous to the DocBook <sidebar> element and the HTML <aside> element.

Processing:

A <sidebar> element should be set off from the rest of the document somehow, typically with a border. Sidebars typically "float" to the side of the page and the document's main text flows around them.

Parents:

<document>, <section>.

Children:

<sidebar> elements begin with optional <title> and <subtitle> and contain body elements and <topic> elements. There must not be a <subtitle> without title.

((title, subtitle?)?,
 (%body.elements; | topic)+)

Attributes:

only the common attributes

Parameter Entities:

%structure.model directly includes <sidebar>.

The <sidebar> element is a non-recursive <section>-like construct. <sidebar> elements cannot nest inside body elements, so you can't have a <sidebar> inside a <table> or a list, or inside another <sidebar> or <topic>.

.. sidebar:: Optional Title
   :subtitle: If Desired

   Body.

<sidebar>
    <title>
        Optional Title
    <subtitle>
        If Desired
    <paragraph>
        Body.

<status>

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

Category:

Bibliographic Elements

Analogues:

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

Processing:

See <docinfo>.

Parent:

<docinfo>

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

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

:Status: Work In Progress

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

<strong>

The <strong> element is an inline element representing text that has strong importance, seriousness, or urgency.

Category:

Inline Elements

Analogues:

<strong> is analogous to the HTML <strong> element.

Processing:

Typically displayed in boldface.

Parents:

all elements employing %text.model in their content models

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

There are :strong:`two` ways to **strongly emphasize** text.

<paragraph>
    There are
    <strong>
        two
     ways to
    <strong>
        strongly emphasize
     text.

<subscript>

The <subscript> element is an inline element representing text which should be displayed as subscript.

Category:

Inline Elements

Analogues:

<subscript> is analogous to the HTML <sub> element and the DocBook <subscript> element.

Processing:

Typically rendered with a lowered baseline using smaller text.

Parents:

all elements employing %text.model in their content models

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

The chemical formula for water is H\ :sub:`2`\ O.

<paragraph>
    The chemical formula for water is H
    <subscript>
        2
    O.

<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>, <section>, or <sidebar>.

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:

<document>, <section>, and <sidebar>

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

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

A paragraph.

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

<superscript>

The <superscript> element is an inline element representing text which should be displayed as superscript.

Category:

Inline Elements

Analogues:

<superscript> is analogous to the HTML <sup> element and the DocBook <superscript> element.

Processing:

Typically rendered with a raised baseline using smaller text.

Parents:

all elements employing %text.model in their content models

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

Key events of the 20\ :sup:`th` century.

<paragraph>
    Key events of the 20
    <superscript>
        th
     century.

<system_message>

The <system_message> element is used for feedback from the processing system.

Category:

Compound Body Elements

Analogues:

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

Processing:

Rendered similar to an <admonition>, with the generated title "System Message", its type/level and, if available, source and line.

Parents:

all elements employing %body.elements or %structure.model in their content models

Children:

one or more body elements

Attributes:

backrefs, level, line, type, and the common attributes.

In Docutils, the generation of system messages can be configured with the report_level setting.

.. contants::

<system_message level="3" line="8" source="example.rst" type="ERROR">
    <paragraph>
        Unknown directive type "contants".
    <literal_block xml:space="preserve">
        .. contants::

<table>

The <table> element represents a data arrangement with rows and columns. It is defined in the Exchange Table Model.

Category:

Compound Body Elements

Analogues:

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

Processing:

Content is arranged in rows and columns forming a grid. See table in the Exchange Table Model for details.

Parents:

<document>, <section> and all body elements

Children:

<table> elements begin with an optional <title> (caption) and may contain one or more <tgroup> elements:

(title?, tgroup+)

Attributes:

The <table> element may contain the frame, colsep, rowsep, and pgwide attributes (ignored by Docutils) and (via the %bodyatt parameter entity) the common attributes, align, and width.

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

<table>
    <tgroup cols="2">
        <colspec colwidth="8">
        <colspec colwidth="4">
        <tbody>
            <row>
                <entry>
                    <paragraph>
                        bread
                <entry>
                    <paragraph>
                        £2
            <row>
                <entry>
                    <paragraph>
                        butter
                <entry>
                    <paragraph>
                        £30

<target>

To be completed.

<tbody>

The <tbody> element identifies the rows that form the body of a <table> (as distinct from the header rows). It is defined in the Exchange Table Model.

Category:

Body Subelements

Analogues:

<tbody> is analogous to the <tbody> element in HTML and DocBook.

Processing:

Render content as table body.

Parent:

<tgroup>

Children:

one or more <row> elements

Attributes:

valign (ignored by Docutils) and the common attributes (via the %tbl.tbody.att parameter entity).

<term>

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

Category:

Body Subelements (simple)

Analogues:

<term> is analogous to the HTML <dt> element and to the DocBook <term> element.

Processing:

see <definition_list_item>

Parent:

<definition_list_item>

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

<tgroup>

The <tgroup> element identifies a logically complete portion of a <table>. It is defined in the Exchange Table Model.

Category:

Body Subelements

Analogues:

<tgroup> is analogous to the DocBook <tgroup> element. There is no corresponding HTML element (the <colgroup> element has a different purpose and semantics).

Processing:

See tgroup in the Exchange Table Model.

Parent:

<table>

Children:

One or more <colspec> elements, followed by an optional <thead> and a <tbody> (cf. the %tbl.tgroup.mdl parameter entity). The number of <colspec>s, must not exceed the value of the cols attribute. Docutils expects one <colspec> per column.

Attributes:

The <tgroup> element must contain a cols attribute and may contain colsep, rowsep, and align (ignored by Docutils). Via the %tbl.tgroup.att parameter entity, <tgroup> supports the common attributes.

Tables usually consist of a single <tgroup>. Complex tables with widely varying column specifications may be easier to code using multiple <tgroup>s. However, this is not supported by table markup in reStructuredText and Docutils table handling routines.

<thead>

The <thead> element identifies the row(s) that form the head of a <table> (as distinct from the body rows). It is defined in the Exchange Table Model.

Category:

Body Subelements

Analogues:

<thead> is analogous to the <thead> element in HTML and DocBook.

Processing:

Header rows are always rendered at the beginning of the table and often presented in an alternate typographic style, such as boldface. In paged media, if a table spans across multiple pages, header rows are printed at the top of each new page.

Parent:

<tgroup>

Children:

one or more <row> elements

Attributes:

the valign attribute (ignored by Docutils) and (via the %tbl.thead.att parameter entity) the common attributes.

<tip>

The <tip> element is a specific admonition, a distinctive and self-contained notice.

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 %body.elements or %structure.model in their content models

Children:

one or more body elements

Attributes:

only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

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

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

<title>

The <title> element stores the heading of a <document>, structural elements, or a generic <admonition>. It is also used for the caption of a <table>.

Category:

Structural Subelements, Body Subelements

Analogues:

<title> is analogous to the DocBook <title> element. In difference to the HTML section heading elements (<h1>, …, <h6>), the heading level is solely determined by the nesting level of the parent <section>. As child of a <table>, <title> corresponds to the HTML <caption> element.

Parents:

<admonition>, <document>, <section>, <sidebar>, <table>, and <topic>

Children:

text data plus inline elements (%text.model)

Attributes:

refid (used as a backlink to a table of contents entry), auto (for auto-numbered section titles), and the common attributes.

The displayed <title> of a <document> may differ from its metadata title that is stored in the title attribute.

A Title
=======

A paragraph.

Next section's title
====================

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

<title_reference>

The <title_reference> element is an inline element representing the titles of a cited creative work.

Category:

Inline Elements

Analogues:

<title_reference> is analogous to the HTML <cite> element and the DocBook <citetitle> element.

Processing:

Typically displayed in italic type.

Parents:

all elements employing %text.model in their content models

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

The term "spam" is derived from the 1970 :title:`Spam` sketch.

<paragraph>
    The term “spam” is derived from the 1970
    <title_reference>
        Spam
     sketch.

<topic>

The <topic> element represents a non-recursive section-like construct for content that is separate from the flow of the document.

Category:

Structural Elements

Analogues:

<topic> is analogous to the DocBook <simplesect> element and the HTML <aside> element.

Processing:

A <topic> element should be set off from the rest of the document somehow, such as with indentation or a border. In contrast to a <sidebar>, it should not float.

Parents:

<document>, <section>, and <sidebar>

Children:

<topic> elements may begin with a <title> and contain body elements:

(title?, (%body.elements;)+)

Attributes:

only the common attributes

Parameter Entities:

%structure.model directly includes <topic>.

Topics are terminal, "leaf" mini-sections, like block quotes with titles, or textual figures. A <topic> is just like a <section>, except that it has no subsections, it does not get listed in the ToC, and it doesn't have to conform to section placement rules. You may place a <topic> in the middle of a <section> and continue the same section after it --- something that cannot be done with a nested <section>.

Topics cannot nest inside topics, or body elements (tables, lists, block quotes, etc).

Docutils uses the <topic> element also for a generated table of contents, and the "abstract" and "dedication" bibliographic fields.

.. topic:: Title

   Body.

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

<transition>

The <transition> element separates body elements and sections, dividing a <section> into untitled divisions.

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:

<document>, <section>

Children:

none (empty)

Attributes:

only the common attributes

Parameter Entities:

%structure.model directly includes <transition>.

A transition may not begin or end a section [9] or document, nor may two transitions be immediately adjacent.

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

Paragraph 1.

--------

Paragraph 2.

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

<version>

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

Category:

Bibliographic Elements

Analogues:

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

Processing:

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

Parent:

<docinfo>

Children:

text data plus inline elements (%text.model)

Attributes:

only the common attributes.

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

:Version: 1.1

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

<warning>

The <warning> element is a specific admonition, a distinctive and self-contained notice.

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 %body.elements or %structure.model in their content models

Children:

one or more body elements

Attributes:

only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

.. WARNING:: Reader discretion is strongly advised.

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

Standard Attribute Types

Standard attribute types are defined in the attribute types section of the XML 1.0 specification [xml1.0].

CDATA

Character data. CDATA attributes may contain arbitrary text.

NMTOKEN

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

NMTOKENS

One or more space-separated NMTOKEN values.

EnumeratedType

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

Custom Attribute Types

To highlight specific attribute value constraints, the Docutils Generic DTD defines custom attribute types via parameter entities that resolve to standard attribute types. In the docutils.nodes Python module, values are stored using the specified data types.

%classnames.type

Space-separated list of class names. Resolves to NMTOKEN.

Used in the classes attribute. Python data type: list[str].

%idref.type

A reference to another element by its identifier. Resolves to NMTOKEN. [14]

Used in the refid attribute. Python data type: str.

%idrefs.type

Space separated list of references to other elements by their identifiers. Resolves to NMTOKENS. [14]

Used in the backrefs attribute. Python data type: list[str].

%ids.type

A space-separated list of unique identifiers. Resolves to NMTOKENS. [14]

Used in the ids attribute. Python data type: list[str].

%measure

A number which may be immediately followed by a unit or percent sign. ReStructuredText supports CSS3 length units. Attributes may restrict the value to some range. Handling of values without unit depends on the writer/output format (see the writer-specific documentation in the user documentation for details). Resolves to CDATA.

Used in the height and width attributes. Python data type: str.

%number

The attribute value must be a positive interger. Resolves to NMTOKEN.

Used in the level, morecols, morerows, scale, and start attributes. Python data type: int.

%refname.type

A reference name. Resolves to CDATA.

Used in the refname attribute. Python data type: str.

%refnames.type

Space-separated list of reference names. (Backslash escaping is used for space characters inside a reference name.) Resolves to CDATA.

Used in the names and dupnames attributes. Python data type: list[str].

%yesorno

Boolean: False if zero ("0"), true for any other value. Resolves to NMTOKEN.

Used in the anonymous, colsep, ltrim, rtrim, rowsep, and stub attributes. Python data type: bool.

Common Attributes

Through the %basic.atts parameter entity, all elements except <meta> support the 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: EnumeratedType. Default value: none (inherit).

The align attribute is used in the <figure> and <table> elements via the %align-h.att parameter entity and in <image> via the %align-hv.att parameter entity to specify the alignment of the element within its parent element.

The Exchange Table Model uses align in the <colspec>, <entry>, and <tgroup> elements to specify the text alignment in table cells. It cannot be specified in reStructuredText and is ignored by Docutils.

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). In <footnote> and <footnote_reference> elements, it also carries information about the label type: "1": auto-numbered, "*": auto-symbol.

backrefs

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

The backrefs attribute contains a space-separated list of identifier references, used for backlinks in <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. It is one of the common attributes, shared by all Docutils elements.

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.

char

Attribute type: CDATA. Default value: "" (no aligning character).

The char attribute is used in the <colspec> and <entry> elements to specify an alignment character.

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.

charoff

Attribute type: NMTOKEN. Default value: "50" (i.e. 50%).

The charoff attribute is used in <colspec> and <entry> elements to specify the horizontal offset of the alignment character when align is "char".

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.

colname

Attribute type: NMTOKEN. Default value: none.

The colname attribute is used in the <colspec> element to name a table column and in the <entry> element to reference a named column.

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.

colnum

Attribute type: NMTOKEN. Default value: none.

The colnum attribute is defined for the <colspec> element by the Exchange Table Model. It serves no functional purpose other than a consistency check.

cols

Attribute type: NMTOKEN. Default value: none.

The cols attribute is used in the <tgroup> element to store the number of columns in a table group.

The attribute is defined in the Exchange Table Model (which see for details).

colsep

Attribute type: %yesorno. Default value: none.

The colsep attribute is used in the <colspec>, <entry>, <table>, and <tgroup> elements to specify the presence or absence of a column separator (vertical ruling).

The attribute is defined in the Exchange Table Model It cannot be specified in reStructuredText and is ignored by Docutils.

colwidth

Attribute type: CDATA. Default value: "1*"

The colwidth attribute is used in the <colspec> element to specify the column width.

The attribute is defined in the Exchange Table Model (which see for details) as either a proportional measure (positive number followed by "*", e.g., "5*" for 5 times the unit proportion, or just "*" for one unit proportion) or a fixed measure (e.g., 2.5cm). Docutils supports only proportional measures.

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 replaces the names attribute when there has been a naming conflict. It is one of the common attributes, shared by all Docutils elements.

enumtype

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

The enumtype attribute is used in the <enumerated_list> element to record the intended enumeration sequence.

Supported values:

arabic:

1, 2, 3, ...

loweralpha:

a, b, c, ..., z

upperalpha:

A, B, C, ..., Z

lowerroman:

i, ii, iii, iv, ..., mmmmcmxcix [4999]

upperroman:

I, II, III, IV, ..., MMMMCMXCIX [4999]

format

Attribute type: NMTOKENS. Default value: none.

The format attribute is used in the <raw> element. It contains one or more space separated output format names.

frame

The frame attribute may be used in the <table> element to specify the table's outer frame.

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.

height

Attribute type: %measure. Default value: none.

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

ids

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

The ids attribute is a space separated list containing one or more unique identifiers, typically assigned by the system. It is one of the common attributes, shared by all Docutils elements.

level

Attribute type: %number. Default value: none.

The level attribute is used in the <system_message> element to indicate the message's severity level. See also the "type" attribute.

line

Attribute type: %number. Default value: none.

The line attribute is used in the <system_message> element to indicate the position of the reported problem in the document source. See also the source attribute.

ltrim

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

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

loading

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

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

New in Docutils 0.21

morecols

Attribute type: %number. Default value: none.

The morecols attribute is used in the <entry> element to specify an entry that spans several physical table columns. It is similar to the colspan attribute of HTML table cells (<th> and <td>).

The morecols attribute is defined in the %tbl.entry.att parameter entity.

morerows

Attribute type: %number. Default value: none.

The morerows attribute is used in the <entry> element to specify an entry that spans several physical table rows. It is similar to the rowspan attribute of HTML table cells (<th> and <td>).

The attribute is defined in the Exchange Table Model (which see for details).

name

Attribute type: NMTOKEN or CDATA. Default value: none.

The name attribute in the <meta> element accepts NMTOKEN values. The output format may limit valid values to a set of keywords (EnumeratedType).

The name attribute in the <reference> element holds the reference name of the referenced element. Whitespace is normalized but case is preserved.

The attribute will no longer be used with <reference> elements in Docutils 1.0.

names

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

The names attribute is a space-separated list containing reference names of an element (spaces inside a name are backslash-escaped). It is one of the common attributes, shared by all Docutils elements.

Each name in the list must be unique; if there are name conflicts (two or more elements want to use the same name), the contents will be transferred to the dupnames attribute on the duplicate elements. [11]

namest

Attribute type: NMTOKEN. Default value: none.

The namest attribute is used in the <entry> element to specify the leftmost column of a span.

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils which uses the morecols attribute instead.

nameend

Attribute type: NMTOKEN. Default value: none.

The nameend attribute is used in the <entry> element to specify the rightmost column of a span.

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils which uses the morecols attribute instead.

pgwide

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

The pgwide attribute is used in the <table> element to make the table span the full page width.

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.

prefix

Attribute type: CDATA. Default value: none.

The prefix attribute is used in the <enumerated_list> element to store the formatting characters used before the enumerator.

In documents originating from reStructuredText data, it will contain either "" (empty string) or "(" (left parenthesis). Writers may ignore this attribute.

refid

Attribute type: %idref.type. Default value: none.

The refid attribute contains a reference to another element via its identifier. It is used by the <citation_reference>, <footnote_reference>, <problematic>, <reference>, <target>, and <title> elements (via the %refid.att and %reference.atts parameter entities).

refname

Attribute type: %refname.type. Default value: none.

The refname attribute contains a reference to one of the names of another element. It is used by the <citation_reference>, <footnote_reference>, <reference>, <substitution_reference>, and <target> elements (via the %refname.att and %reference.atts parameter entities).

On a <target> element, refname indicates an indirect target which may resolve to either an internal or external reference. Docutils transforms replace the refname attribute with a refid pointing to the same element.

refuri

Attribute type: CDATA. Default value: none.

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

rowsep

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

The rowsep attribute may be used in the <colspec>, <entry>, <row>, <table>, and <tgroup> elements to specify the presence or absence of row separators (horizontal ruling).

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.

rtrim

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

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

scale

Attribute type: %number. Default value: none.

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

source

Attribute type: CDATA. Default value: none.

The source attribute stores the path, URI, or a description of the source that was used to produce the document tree. It is one of the common attributes but typically only used with the <document> and <system_message> elements.

An element's source attribute may differ from the main document source if the document is assembled from several sources (e.g. via the "include" directive).

start

Attribute type: %number. Default value: none (implies 1).

The start attribute is used in the <enumerated_list> element to store the ordinal value of the first item in the list, in decimal notation.

For lists beginning at value 1 ("1", "a", "A", "i", or "I"), this attribute may be omitted.

stub

Attribute type: %yesorno. Default value: none.

The stub attribute is used in the <colspec> element to mark a table column as containing stubs (row titles, on the left). See also the "csv-table" and "list-table" directives.

The attribute is defined in the %tbl.colspec.att parameter entity.

suffix

Attribute type: CDATA. Default value: none.

The suffix attribute is used in the <enumerated_list> element to store the formatting characters used after the enumerator.

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

title

Attribute type: CDATA. Default value: none.

The title attribute is used in the <document> element to store the document's metadata title.

It is set by the "title" directive or the DocTitle transform. This title is typically not part of the rendered document. It is, for example, used as HTML <title> element and shown in a browser's title bar, in a user's history or bookmarks, or in search results.

type

Attribute type: NMTOKEN. Default value: none.

The type attribute is used in the <system_message> element. It holds the name of the message's severity level (cf. the "level" attribute).

uri

Attribute type: CDATA. Default value: none.

The uri attribute is used in the <image> and <figure> elements to refer to the image via a URI Reference [12]. [rfc3986]

The root_prefix configuration setting is applied when a URI Reference starting with "/" is converted to a local filesystem path.

valign

The valign attribute is used in the <entry>, <row>, <tbody>, and <thead> elements to specify the vertical text alignment within entries.

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.

width

Attribute type: %measure. Default value: none.

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

xml:space

The xml:space attribute is a standard XML attribute for whitespace-preserving elements. It is used by the <address>, <comment>, <doctest_block>, <literal_block>, <math_block>, and <raw> elements (via the %fixedspace.att parameter entity). It is a fixed attribute, meant to communicate to an XML parser that the element contains significant whitespace. The attribute value should not be set in a document instance.

Attribute Entities

align (left | center | right) #IMPLIED

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

anonymous %yesorno; #IMPLIED

auto CDATA #IMPLIED

backrefs %idrefs.type; #IMPLIED

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

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

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

refid %idref.type; #IMPLIED

refname %refname.type; #IMPLIED

refuri CDATA #IMPLIED

Element Category Entities

Model Entities

<!ENTITY % calstblx PUBLIC
    "-//OASIS//DTD XML Exchange Table Model 19990315//EN"
    "soextblx.dtd">

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

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

(%body.elements;)*

colspec+,thead?,tbody

(#PCDATA | %inline.elements;)*

Placeholders

The following empty placeholders are employed to allow easy extension of the corresponding parameter entity by wrapper DTDs: