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

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

Inline Elements

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

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

abbreviation

To be completed.

acronym

To be completed.

address

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

%text.model;

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

This element is a generic, titled admonition. Also see the specific admonition elements Docutils offers (in alphabetical order): caution, danger, error, hint, important, note, tip, warning.

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

.. admonition:: And, by the way...

   You can make up your own admonition too.

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

attention

The attention element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): caution, danger, error, hint, important, note, tip, warning, and the generic admonition.

(%body.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 of the document.

%text.model;

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.

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

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

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

As a great paleontologist once said,

    This theory, that is mine, is mine.

    -- Anne Elk (Miss)

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

bullet_list

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

(list_item +)

- 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 an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, danger, error, hint, important, note, tip, warning, and the generic admonition.

(%body.elements;)+

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

%text.model;

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

To be completed.

comment

To be completed.

compound

To be completed.

contact

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

%text.model;

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

To be completed.

copyright

The copyright element contains the document's copyright statement.

%text.model;

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 an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, error, hint, important, note, tip, warning, and the generic admonition.

(%body.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.

%text.model;

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.

(header?, footer?)

A paragraph.

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

definition

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

(%body.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).

(definition_list_item +)

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

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

(term, classifier?, definition)

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>
            <paragraph>
                All brontosauruses are thin at one end,
                much much thicker in the middle
                and then thin again at the far end.
            <paragraph>
                -- Anne Elk (Miss)

description

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

(%body.elements;)+

docinfo

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

(%bibliographic.elements;)+

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>
            <field_name>
                Filename
            <field_body>
                <paragraph>
                    doctree.txt
        <copyright>
            This document has been placed in the public domain.

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.

%text.model;

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

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

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

To be completed.

entry

To be completed.

enumerated_list

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

(list_item +)

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 an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, danger, hint, important, note, tip, warning, and the generic admonition.

(%body.elements;)+

.. Error:: Does not compute.

<error>
    <paragraph>
        Does not compute.

field

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

(field_name, field_body)

field_body

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

(%body.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.

(field +)

: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 contains text; it is analogous to a database field's name.

%text.model;

figure

To be completed.

footer

The footer element is a container element whose contents are meant to appear at the bottom of a web page, or repeated at the bottom of every printed page. The footer element may contain processing information (datestamp, a link to Docutils, etc.) as well as custom content.

(%body.elements;)+

A paragraph.

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

footnote

To be completed.

footnote_reference

To be completed.

generated

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

To be completed.

header

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

(%body.elements;)+

.. header:: This space for rent.

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

hint

The hint element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, danger, error, important, note, tip, warning, and the generic admonition.

(%body.elements;)+

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

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

image

To be completed.

important

The important element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, danger, error, hint, note, tip, warning, and the generic admonition.

(%body.elements;)+

.. Important::

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

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

inline

To be completed.

label

To be completed.

legend

To be completed.

line

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

%text.model;

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.

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

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

(%body.elements;)*

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. literal_block elements are commonly used for program listings and interactive computer sessions. See line_block for an alternative useful for verse and addresses.

%text.model;

Here is a literal block::

    if literal_block:
        text = 'is left as-is'
        spaces_and_linebreaks = 'are preserved'
        markup_processing = None

<paragraph>
    Here is a literal block:
<literal_block xml:space="preserve">
    if literal_block:
        text = 'is left as-is'
        spaces_and_linebreaks = 'are preserved'
        markup_processing = None

note

The note element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, danger, error, hint, important, tip, warning, and the generic admonition.

(%body.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. Note that reStructuredText currently supports only one argument per option.

(option_string, option_argument *)

option_argument

The option_argument element contains placeholder text for option arguments.

(#PCDATA)

option_group

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

(option_group, description)

option_list

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

(option_list_item +)

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

(option_group, description)

option_string

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

(#PCDATA)

organization

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

%text.model;

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.

%text.model;

A paragraph.

<paragraph>
    A paragraph.

pending

To be completed.

problematic

To be completed.

raw

To be completed.

reference

To be completed.

revision

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

%text.model;

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

:Version: 1
:Revision: b

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

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.

(title,
 %structure.model;)

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. A sidebar is typically offset by a border and "floats" to the side of the page; the document's main text may flow around it. Sidebars can also be likened to super-footnotes; their content is outside of the flow of the document's main text.

The sidebar element is a nonrecursive section-like construct which may occur at the top level of a section wherever a body element (list, table, etc.) is allowed. In other words, sidebar elements cannot nest inside body elements, so you can't have a sidebar inside a table or a list, or inside another sidebar (or topic).

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

.. sidebar:: Title
   :subtitle: If Desired

   Body.

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

%text.model;

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

:Status: Work In Progress

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

strong

To be completed.

subscript

To be completed.

substitution_definition

To be completed.

substitution_reference

To be completed.

subtitle

The subtitle element stores the subtitle of a document.

%text.model;

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

A paragraph.

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

superscript

To be completed.

system_message

To be completed.

table

To be completed.

target

To be completed.

tbody

To be completed.

term

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

%text.model;

tgroup

To be completed.

thead

To be completed.

tip

The tip element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, danger, error, hint, important, note, warning, and the generic admonition.

(%body.elements;)+

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

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

title

The title element stores the title of a document, section, topic, sidebar, or generic admonition.

%text.model;

A Title
=======

A paragraph.

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

title_reference

To be completed.

topic

The topic element is a nonrecursive section-like construct which may occur at the top level of a section wherever a body element (list, table, etc.) is allowed. In other words, topic elements cannot nest inside body elements, so you can't have a topic inside a table or a list, or inside another topic.

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

.. topic:: Title

   Body.

<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 [1] or document, nor may two transitions be immediately adjacent.

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

EMPTY

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.

%text.model;

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

:Version: 1.1

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

warning

The warning element is an admonition, a distinctive and self-contained notice. Also see the other admonition elements Docutils offers (in alphabetical order): attention, caution, danger, error, hint, important, note, tip.

(%body.elements;)+

.. WARNING:: Reader discretion is strongly advised.

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

anonymous

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

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

auto

Attribute type: CDATA. Default value: none.

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

backrefs

Attribute type: IDREFS. Default value: none.

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

bullet

Attribute type: CDATA. Default value: none.

The bullet attribute is used in the bullet_list element.

classes

Attribute type: NMTOKENS. Default value: none.

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

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

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

delimiter

Attribute type: CDATA. Default value: none.

The delimiter attribute is used in the option_argument element.

dupnames

Attribute type: CDATA. Default value: none.

The dupnames attribute is a list containing the names of an element when there has been a naming conflict. The contents of the dupnames attribute would have been transferred from the names attribute. An element may have at most one of the names or dupnames attributes, but not both. dupnames is one of the common attributes, shared by all Docutils elements.

enumtype

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

The enumtype attribute is used in the enumerated_list element.

ids

Attribute type: NMTOKENS. Default value: none.

The ids attribute is a list containing one or more unique identifier keys. ids is one of the common attributes, shared by all Docutils elements.

names

Attribute type: CDATA. Default value: none.

The names attribute is a list containing the names of an element, typically originating from the element's title or content. Each name in names must be unique; if there are name conflicts (two or more elements want to the same name), the contents will be transferred to the dupnames attribute on the duplicate elements. An element may have at most one of the names or dupnames attributes, but not both. names is one of the common attributes, shared by all Docutils elements.

prefix

Attribute type: CDATA. Default value: none.

The prefix attribute is used in the enumerated_list element.

refid

Attribute type: IDREF. Default value: none.

The refid attribute contains references to ids attributes in other elements. It is used by the target, reference, footnote_reference, citation_reference, title and problematic elements (via the %refid.att; and %reference.atts; parameter entities).

refname

Attribute type: NMTOKENS. Default value: none.

The refname attribute contains an internal reference to the names attribute of another element. On a target element, refname indicates an indirect target which may resolve to either an internal or external reference. refname is used by the target, reference, footnote_reference, citation_reference, and substitution_reference elements (via the %refname.att; and %reference.atts; parameter entities).

refuri

Attribute type: CDATA. Default value: none.

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

source

Attribute type: CDATA. Default value: none.

The source attribute is used to store the path or URL to the source text that was used to produce the document tree. It is one of the common attributes, shared by all Docutils elements.

start

Attribute type: %number;. Default value: none.

The start attribute is used in the enumerated_list element.

suffix

Attribute type: CDATA. Default value: none.

The suffix attribute is used in the enumerated_list element.

xml:space

Attribute type: one of "default" or "preserve". Default value: "preserve" (fixed).

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

title

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

%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    #IMPLIED

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

%basic.atts;

The %basic.atts; parameter entity lists attributes common to all Docutils elements. See Common Attributes.

Entity definition:

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
| line_block | block_quote
| table | figure | image | footnote | citation | rubric
| bullet_list | enumerated_list | definition_list | field_list
| option_list
| attention | caution | danger | error | hint | important | note
| tip | warning | admonition
| reference | target | substitution_definition | comment | pending
| system_message | raw
%additional.body.elements;

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

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

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

%fixedspace.att;

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

Entity definition:

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
| reference | footnote_reference | citation_reference
| substitution_reference | title_reference
| abbreviation | acronym | subscript | superscript
| inline | problematic | generated
| target | image | raw
%additional.inline.elements;

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

Via %text.model;, the %inline.elements; parameter entity is indirectly employed in the content models of the following elements: abbreviation, acronym, address, attribution, author, caption, classifier, contact, copyright, date, doctest_block, emphasis, generated, inline, line_block, literal_block, organization, paragraph, problematic, raw, reference, revision, rubric, status, strong, subscript, substitution_definition, substitution_reference, subtitle, superscript, target, term, title, title_reference, version

%reference.atts;

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

Entity definition:

%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   CDATA     #IMPLIED

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

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

%refname.att;

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

Entity definition:

refname  NMTOKENS  #IMPLIED

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

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

%refuri.att;

The %refuri.att; parameter entity contains the refuri attribute, an external reference to a URI/URL.

Entity definition:

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.

An additional restriction, which cannot be expressed in the language of DTDs, is imposed by software:

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

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

%text.model;

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

Entity definition:

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