The Docutils Document Tree¶
A Guide to the Docutils DTD¶
Author: | David Goodger |
---|---|
Contact: | docutils-develop@lists.sourceforge.net |
Revision: | $Revision: 7882 $ |
Date: | $Date: 2015-04-20 10:55:19 +0000 (Mon, 20 Apr 2015) $ |
Copyright: | このドキュメントは、パブリック ドメインで公開されています。 |
Contents
This document describes the XML data structure of Docutils documents: the relationships and semantics of elements and attributes. The Docutils document structure is formally defined by the Docutils Generic DTD XML document type definition, docutils.dtd, which is the definitive source for details of element structural relationships.
This document does not discuss implementation details. Those can be
found in internal documentation (docstrings) for the
docutils.nodes
module, where the document tree data structure is
implemented in a class library.
The reader is assumed to have some familiarity with XML or SGML, and an understanding of the data structure meaning of "tree". For a list of introductory articles, see Introducing the Extensible Markup Language (XML).
The reStructuredText markup is used for illustrative examples throughout this document. For a gentle introduction, see A ReStructuredText Primer. For complete technical details, see the reStructuredText Markup Specification.
Element Hierarchy¶
Below is a simplified diagram of the hierarchy of elements in the Docutils document tree structure. An element may contain any other elements immediately below it in the diagram. Notes are written in square brackets. Element types in parentheses indicate recursive or one-to-many relationships; sections may contain (sub)sections, tables contain further body elements, etc.
+--------------------------------------------------------------------+
| document [may begin with a title, subtitle, decoration, docinfo] |
| +--------------------------------------+
| | sections [each begins with a title] |
+-----------------------------+-------------------------+------------+
| [body elements:] | (sections) |
| | - literal | - lists | | - hyperlink +------------+
| | blocks | - tables | | targets |
| para- | - doctest | - block | foot- | - sub. defs |
| graphs | blocks | quotes | notes | - comments |
+---------+-----------+----------+-------+--------------+
| [text]+ | [text] | (body elements) | [text] |
| (inline +-----------+------------------+--------------+
| markup) |
+---------+
The Docutils document model uses a simple, recursive model for section
structure. A document node may contain body elements and section
elements. Sections in turn may contain body elements and sections.
The level (depth) of a section element is determined from its physical
nesting level; unlike other document models (<h1>
in HTML,
<sect1>
in DocBook, <div1>
in XMLSpec) the level is not
incorporated into the element name.
The Docutils document model uses strict element content models. Every element has a unique structure and semantics, but elements may be classified into general categories (below). Only elements which are meant to directly contain text data have a mixed content model, where text data and inline elements may be intermixed. This is unlike the much looser HTML document model, where paragraphs and text data may occur at the same level.
Structural Elements¶
Structural elements may only contain child elements; they do not directly contain text data. Structural elements may contain body elements or further structural elements. Structural elements can only be child elements of other structural elements.
Category members: document, section, topic, sidebar
Structural Subelements¶
Structural subelements are child elements of structural elements. Simple structuctural subelements (title, subtitle) contain text data; the others are compound and do not directly contain text data.
Category members: title, subtitle, decoration, docinfo, transition
Bibliographic Elements¶
The docinfo element is an optional child of document. It groups bibliographic elements together. All bibliographic elements except authors and field contain text data. authors contains further bibliographic elements (most notably author). field contains field_name and field_body body subelements.
Category members: address, author, authors, contact, copyright, date, field, organization, revision, status, version
Decorative Elements¶
The decoration element is also an optional child of document. It groups together elements used to generate page headers and footers.
本文エレメント¶
Body elements are contained within structural elements and compound body elements. There are two subcategories of body elements: simple and compound.
Category members: admonition, attention, block_quote, bullet_list, caution, citation, comment, compound, container, danger, definition_list, doctest_block, enumerated_list, error, field_list, figure, footnote, hint, image, important, line_block, literal_block, note, option_list, paragraph, pending, raw, rubric, substitution_definition, system_message, table, target, tip, warning
Simple Body Elements¶
Simple body elements are empty or directly contain text data. Those that contain text data may also contain inline elements. Such elements therefore have a "mixed content model".
Category members: comment, doctest_block, image, literal_block, math_block, paragraph, pending, raw, rubric, substitution_definition, target
Compound Body Elements¶
Compound body elements contain local substructure (body subelements) and further body elements. They do not directly contain text data.
Category members: admonition, attention, block_quote, bullet_list, caution, citation, compound, container, danger, definition_list, enumerated_list, error, field_list, figure, footnote, hint, important, line_block, note, option_list, system_message, table, tip, warning
Body Subelements¶
Compound body elements contain specific subelements (e.g. bullet_list contains list_item). Subelements may themselves be compound elements (containing further child elements, like field) or simple data elements (containing text data, like field_name). These subelements always occur within specific parent elements, never at the body element level (beside paragraphs, etc.).
Category members (simple): attribution, caption, classifier, colspec, field_name, label, line, option_argument, option_string, term
Category members (compound): definition, definition_list_item, description, entry, field, field_body, legend, list_item, option, option_group, option_list_item, row, tbody, tgroup, thead
Inline Elements¶
Inline elements directly contain text data, and may also contain further inline elements. Inline elements are contained within simple body elements. Most inline elements have a "mixed content model".
Category members: abbreviation, acronym, citation_reference, emphasis, footnote_reference, generated, image, inline, literal, math, problematic, reference, strong, subscript, substitution_reference, superscript, target, title_reference, raw
Element Reference¶
abbreviation
acronym
address
admonition
attention
attribution
author
authors
block_quote
bullet_list
caption
caution
citation
citation_reference
classifier
colspec
comment
compound
contact
container
copyright
danger
date
decoration
definition
definition_list
definition_list_item
description
docinfo
doctest_block
document
emphasis
entry
enumerated_list
error
field
field_body
field_list
field_name
figure
footer
footnote
footnote_reference
generated
header
hint
image
important
inline
label
legend
line
line_block
list_item
literal
literal_block
math
math_block
note
option
option_argument
option_group
option_list
option_list_item
option_string
organization
paragraph
pending
problematic
raw
reference
revision
row
rubric
section
sidebar
status
strong
subscript
substitution_definition
substitution_reference
subtitle
superscript
system_message
table
target
tbody
term
tgroup
thead
tip
title
title_reference
topic
transition
version
warning
Each element in the DTD (document type definition) is described in its own section below. Each section contains an introduction plus the following subsections:
Details (of element relationships and semantics):
- Category: One or more references to the element categories in Element Hierarchy above. Some elements belong to more than one category.
- Parents: A list of elements which may contain the element.
- Children: A list of elements which may occur within the element.
- Analogues: Describes analogous elements in well-known document models such as HTML or DocBook. Lists similarities and differences.
- Processing: Lists formatting or rendering recommendations for the element.
Content Model:
The formal XML content model from the Docutils DTD, followed by:
- Attributes: Describes (or refers to descriptions of) the possible values and semantics of each attribute.
- Parameter Entities: Lists the parameter entities which directly or indirectly include the element.
Examples: reStructuredText examples are shown along with fragments of the document trees resulting from parsing. Pseudo-XML is used for the results of parsing and processing. Pseudo-XML is a representation of XML where nesting is indicated by indentation and end-tags are not shown. Some of the precision of real XML is given up in exchange for easier readability. For example, the following are equivalent:
Real XML:
<document> <section ids="a-title" names="a title"> <title>A Title</title> <paragraph>A paragraph.</paragraph> </section> </document>
Pseudo-XML:
<document> <section ids="a-title" names="a title"> <title> A Title <paragraph> A paragraph.
Many of the element reference sections below are marked "to be completed". Please help complete this document by contributing to its writing.
abbreviation
¶
The abbreviation
element is an inline element used to represent an
abbreviation being used in the document. An example of an abbreviation is 'St'
being used instead of 'Street'.
Details¶
Category: | Inline Elements |
---|---|
Parents: | All elements employing the %inline.elements; parameter entities in their
content models may contain abbreviation . |
Children: | abbreviation elements may contain text data plus inline elements. |
Analogues: | abbreviation is analogous to the HTML "abbr" element. |
Content Model¶
%text.model;
Attributes: | The abbreviation element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
The abbreviation
element is not exposed in default restructured text. It
can only be accessed through custom roles.
Pseudo-XML example from a custom :abbr: role:
<paragraph>
<abbreviation explanation="Street">
St
is a common abbreviation for "street".
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.
Details¶
Category: | |
---|---|
Parents: | The following elements may contain |
Children: |
|
Analogues: |
|
Processing: | As with the literal_block element, newlines and other whitespace is significant and must be preserved. However, a monospaced typeface need not be used. See also docinfo. |
Content Model¶
%text.model;
Attributes: | The address element contains the common attributes (ids,
names, dupnames, source, and classes), plus xml:space. |
---|---|
Parameter Entities: | |
The %bibliographic.elements; parameter entity directly includes
address . |
Examples¶
reStructuredText source:
Document Title
==============
:Address: 123 Example Ave.
Example, EX
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<address>
123 Example Ave.
Example, EX
See docinfo for a more complete example, including processing context.
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.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain admonition . |
Children: | admonition elements begin with a title and may contain one or
more `body elements`_. |
Analogues: | admonition has no direct analogues in common DTDs. It can be
emulated with primitives and type effects. |
Processing: | Rendered distinctly (inset and/or in a box, etc.). |
Content Model¶
(title, (%body.elements;)+)
Attributes: | The admonition element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
admonition . The %structure.model; parameter entity
indirectly includes admonition . |
Examples¶
reStructuredText source:
.. admonition:: And, by the way...
You can make up your own admonition too.
Pseudo-XML fragment from simple parsing:
<admonition class="admonition-and-by-the-way">
<title>
And, by the way...
<paragraph>
You can make up your own admonition too.
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.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain attention . |
Children: | attention elements contain one or more `body elements`_. |
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). |
Content Model¶
(%body.elements;)+
Attributes: | The attention element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
attention . The %structure.model; parameter entity
indirectly includes attention . |
Examples¶
reStructuredText source:
.. Attention:: All your base are belong to us.
Pseudo-XML fragment from simple parsing:
<attention>
<paragraph>
All your base are belong to us.
author
¶
The author
element holds the name of the author of the document.
Details¶
Category: | Bibliographic Elements |
---|---|
Parents: | The following elements may contain author : docinfo, authors |
Children: | author elements may contain text data plus inline elements. |
Analogues: | author is analogous to the DocBook "author" element. |
Processing: | See docinfo. |
Content Model¶
%text.model;
Attributes: | The author element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %bibliographic.elements; parameter entity directly includes
author . |
Examples¶
reStructuredText source:
Document Title
==============
:Author: J. Random Hacker
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<author>
J. Random Hacker
See docinfo for a more complete example, including processing context.
authors
¶
The authors
element is a container for author information for
documents with multiple authors.
Details¶
Category: | Bibliographic Elements |
---|---|
Parents: | Only the docinfo element contains authors . |
Children: | authors elements may contain the following elements: author,
organization, address, contact |
Analogues: | authors is analogous to the DocBook "authors" element. |
Processing: | See docinfo. |
Content Model¶
((author, organization?, address?, contact?)+)
Attributes: | The authors element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %bibliographic.elements; parameter entity directly includes
authors . |
Examples¶
reStructuredText source:
Document Title
==============
:Authors: J. Random Hacker; Jane Doe
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<authors>
<author>
J. Random Hacker
<author>
Jane Doe
In reStructuredText, multiple author's names are separated with semicolons (";") or commas (","); semicolons take precedence. There is currently no way to represent the author's organization, address, or contact in a reStructuredText "Authors" field.
See docinfo for a more complete example, including processing context.
block_quote
¶
The block_quote
element is used for quotations set off from the
main text (standalone).
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain block_quote . |
Children: | block_quote elements contain `body elements`_ followed by an
optional attribution element. |
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. |
Content Model¶
((%body.elements;)+, attribution?)
Attributes: | The block_quote element contains only the common
attributes: ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
block_quote . The %structure.model; parameter entity
indirectly includes block_quote . |
Examples¶
reStructuredText source:
As a great paleontologist once said,
This theory, that is mine, is mine.
-- Anne Elk (Miss)
Pseudo-XML fragment from simple parsing:
<paragraph>
As a great paleontologist once said,
<block_quote>
<paragraph>
This theory, that is mine, is mine.
<attribution>
Anne Elk (Miss)
bullet_list
¶
The bullet_list
element contains list_item elements which are
uniformly marked with bullets. Bullets are typically simple dingbats
(symbols) such as circles and squares.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain bullet_list . |
Children: | bullet_list elements contain one or more list_item elements. |
Analogues: | bullet_list is analogous to the HTML "ul" element and to the
DocBook "itemizedlist" element. HTML's "ul" is short for
"unordered list", which we consider to be a misnomer. "Unordered"
implies that the list items may be randomly rearranged without
affecting the meaning of the list. Bullet lists are often
ordered; the ordering is simply left implicit. |
Processing: | Each list item should begin a new vertical block, prefaced by a bullet/dingbat. |
Content Model¶
(list_item +)
Attributes: | The
|
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
|
Examples¶
reStructuredText source:
- Item 1, paragraph 1.
Item 1, paragraph 2.
- Item 2.
Pseudo-XML fragment from simple parsing:
<bullet_list bullet="-">
<list_item>
<paragraph>
Item 1, paragraph 1.
<paragraph>
Item 1, paragraph 2.
<list_item>
<paragraph>
Item 2.
See list_item for another example.
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.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain caution . |
Children: | caution elements contain one or more `body elements`_. |
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). |
Content Model¶
(%body.elements;)+
Attributes: | The caution element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
caution . The %structure.model; parameter entity
indirectly includes caution . |
Examples¶
reStructuredText source:
.. Caution:: Don't take any wooden nickels.
Pseudo-XML fragment from simple parsing:
<caution>
<paragraph>
Don't take any wooden nickels.
classifier
¶
The classifier
element contains the classification or type of the
term being defined in a definition_list. For example, it can be
used to indicate the type of a variable.
Details¶
Category: | Body Subelements (simple) |
---|---|
Parents: | Only the definition_list_item element contains classifier . |
Children: | classifier elements may contain text data plus inline elements. |
Analogues: | classifier has no direct analogues in common DTDs. It can be
emulated with primitives or type effects. |
Processing: | See definition_list_item. |
Content Model¶
%text.model;
Attributes: | The classifier element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
Here is a hypothetical data dictionary. reStructuredText source:
name : string
Customer name.
i : int
Temporary index variable.
Pseudo-XML fragment from simple parsing:
<definition_list>
<definition_list_item>
<term>
name
<classifier>
string
<definition>
<paragraph>
Customer name.
<definition_list_item>
<term>
i
<classifier>
int
<definition>
<paragraph>
Temporary index variable.
contact
¶
The contact
element holds contact information for the author
(individual or group) of the document, or a third-party contact. It
is typically used for an email or web address.
Details¶
Category: | Bibliographic Elements |
---|---|
Parents: | The following elements may contain contact : docinfo, authors |
Children: | contact elements may contain text data plus inline
elements. |
Analogues: | contact is analogous to the DocBook "email" element. The HTML
"address" element serves a similar purpose. |
Processing: | See docinfo. |
Content Model¶
%text.model;
Attributes: | The contact element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %bibliographic.elements; parameter entity directly includes
contact . |
Examples¶
reStructuredText source:
Document Title
==============
:Contact: jrh@example.com
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<contact>
<reference refuri="mailto:jrh@example.com">
jrh@example.com
See docinfo for a more complete example, including processing context.
copyright
¶
The copyright
element contains the document's copyright statement.
Details¶
Category: | Bibliographic Elements |
---|---|
Parents: | Only the docinfo element contains copyright . |
Children: | copyright elements may contain text data plus inline
elements. |
Analogues: | copyright is analogous to the DocBook "copyright" element. |
Processing: | See docinfo. |
Content Model¶
%text.model;
Attributes: | The copyright element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %bibliographic.elements; parameter entity directly includes
copyright . |
Examples¶
reStructuredText source:
Document Title
==============
:Copyright: This document has been placed in the public domain.
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<copyright>
This document has been placed in the public domain.
See docinfo for a more complete example, including processing context.
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.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain danger . |
Children: | danger elements contain one or more `body elements`_. |
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). |
Content Model¶
(%body.elements;)+
Attributes: | The danger element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
danger . The %structure.model; parameter entity
indirectly includes danger . |
Examples¶
reStructuredText source:
.. DANGER:: Mad scientist at work!
Pseudo-XML fragment from simple parsing:
<danger>
<paragraph>
Mad scientist at work!
date
¶
The date
element contains the date of publication, release, or
last modification of the document.
Details¶
Category: | Bibliographic Elements |
---|---|
Parents: | Only the docinfo element contains date . |
Children: | date elements may contain text data plus inline elements. |
Analogues: | date is analogous to the DocBook "date" element. |
Processing: | Often used with the RCS/CVS keyword "Date". See docinfo. |
Content Model¶
%text.model;
Attributes: | The date element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %bibliographic.elements; parameter entity directly includes
date . |
Examples¶
reStructuredText source:
Document Title
==============
:Date: 2002-08-20
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<date>
2002-08-20
See docinfo for a more complete example, including processing context.
decoration
¶
The decoration
element is a container for header and footer
elements and potential future extensions. These elements are used for
notes, time/datestamp, processing information, etc.
Details¶
Category: | Structural Subelements |
---|---|
Parents: | Only the document element contains decoration . |
Children: | decoration elements may contain decorative elements. |
Analogues: | There are no direct analogies to decoration in HTML or in
DocBook. Equivalents are typically constructed from primitives
and/or generated by the processing system. |
Processing: | See the individual decorative elements. |
Content Model¶
(header?, footer?)
Although the content model doesn't specifically require contents, no
empty decoration
elements are ever created.
Attributes: | The decoration element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
reStructuredText source:
A paragraph.
Complete pseudo-XML result after parsing and applying transforms, assuming that the datestamp command-line option or configuration setting has been supplied:
<document>
<decoration>
<footer>
<paragraph>
Generated on: 2002-08-20.
<paragraph>
A paragraph.
definition
¶
The definition
element is a container for the body elements used
to define a term in a definition_list.
Details¶
Category: | Body Subelements (compound) |
---|---|
Parents: | Only definition_list_item elements contain definition . |
Children: | definition elements may contain `body elements`_. |
Analogues: | definition is analogous to the HTML "dd" element and to the
DocBook "listitem" element (inside a "variablelistentry" element). |
Processing: | See definition_list_item. |
Content Model¶
(%body.elements;)+
Attributes: | The definition element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
See the examples for the definition_list, definition_list_item, and classifier elements.
definition_list
¶
The definition_list
element contains a list of terms and their
definitions. It can be used for glossaries or dictionaries, to
describe or classify things, for dialogues, or to itemize subtopics
(such as in this reference).
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain definition_list . |
Children: | definition_list elements contain one or more
definition_list_item elements. |
Analogues: | definition_list is analogous to the HTML "dl" element and to
the DocBook "variablelist" element. |
Processing: | See definition_list_item. |
Content Model¶
(definition_list_item +)
Attributes: | The definition_list element contains only the common
attributes: ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
definition_list . The %structure.model; parameter entity
indirectly includes definition_list . |
Examples¶
reStructuredText source:
Term
Definition.
Term : classifier
The ' : ' indicates a classifier in
definition list item terms only.
Pseudo-XML fragment from simple parsing:
<definition_list>
<definition_list_item>
<term>
Term
<definition>
<paragraph>
Definition.
<definition_list_item>
<term>
Term
<classifier>
classifier
<definition>
<paragraph>
The ' : ' indicates a classifier in
definition list item terms only.
See definition_list_item and classifier for further examples.
definition_list_item
¶
The definition_list_item
element contains a single
term/definition pair (with optional classifier).
Details¶
Category: | Body Subelements (compound) |
---|---|
Parents: | Only the definition_list element contains
definition_list_item . |
Children: | definition_list_item elements each contain a single term,
an optional classifier, and a definition. |
Analogues: | definition_list_item is analogous to the DocBook
"variablelistentry" element. |
Processing: | The optional classifier can be rendered differently from the term. They should be separated visually, typically by spaces plus a colon or dash. |
Content Model¶
(term, classifier?, definition)
Attributes: | The definition_list_item element contains only the common
attributes: ids, names, dupnames, source, and classes. |
---|
Examples¶
reStructuredText source:
Tyrannosaurus Rex : carnivore
Big and scary; the "Tyrant King".
Brontosaurus : herbivore
All brontosauruses are thin at one end,
much much thicker in the middle
and then thin again at the far end.
-- Anne Elk (Miss)
Pseudo-XML fragment from simple parsing:
<definition_list>
<definition_list_item>
<term>
Tyrannosaurus Rex
<classifier>
carnivore
<definition>
<paragraph>
Big and scary; the "Tyrant King".
<definition_list_item>
<term>
Brontosaurus
<classifier>
herbivore
<definition>
<paragraph>
All brontosauruses are thin at one end,
much much thicker in the middle
and then thin again at the far end.
<paragraph>
-- Anne Elk (Miss)
See definition_list and classifier for further examples.
description
¶
The description
element contains body elements, describing the
purpose or effect of a command-line option or group of options.
Details¶
Category: | Body Subelements |
---|---|
Parents: | Only the option_list_item element contains description . |
Children: | description elements may contain `body elements`_. |
Analogues: | description has no direct analogues in common DTDs. |
Processing: | See option_list. |
Content Model¶
(%body.elements;)+
Attributes: | The description element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
See the examples for the option_list element.
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.
Details¶
Category: | |
---|---|
Parents: | Only the document element contains |
Children: |
|
Analogues: |
|
Processing: | The When Docutils transforms a reStructuredText field_list into a
|
Content Model¶
(%bibliographic.elements;)+
Attributes: | The docinfo element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
Docinfo is represented in reStructuredText by a field_list in a
bibliographic context: the first non-comment element of a document,
after any document title/subtitle. The field list is transformed
into a docinfo
element and its children by a transform. Source:
Docinfo Example
===============
:Author: J. Random Hacker
:Contact: jrh@example.com
:Date: 2002-08-18
:Status: Work In Progress
:Version: 1
:Filename: $RCSfile$
:Copyright: This document has been placed in the public domain.
Complete pseudo-XML result after parsing and applying transforms:
<document ids="docinfo-example" names="docinfo example">
<title>
Docinfo Example
<docinfo>
<author>
J. Random Hacker
<contact>
<reference refuri="mailto:jrh@example.com">
jrh@example.com
<date>
2002-08-18
<status>
Work In Progress
<version>
1
<field>
<field_name>
Filename
<field_body>
<paragraph>
doctree.txt
<copyright>
This document has been placed in the public domain.
Note that "Filename" is a non-standard docinfo
field, so becomes a
generic field
element. Also note that the "RCSfile" keyword
syntax has been stripped from the "Filename" data.
See field_list for an example in a non-bibliographic context. Also see the individual examples for the various bibliographic elements.
doctest_block
¶
The doctest_block
element is a Python-specific variant of
literal_block. It is a block of text where line breaks and
whitespace are significant and must be preserved. doctest_block
elements are used for interactive Python interpreter sessions, which
are distinguished by their input prompt: >>>
. They are meant to
illustrate usage by example, and provide an elegant and powerful
testing environment via the doctest module in the Python standard
library.
Details¶
Category: | Simple Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain doctest_block . |
Children: | doctest_block elements may contain text data plus inline
elements. |
Analogues: | doctest_block is analogous to the HTML "pre" element and to
the DocBook "programlisting" and "screen" elements. |
Processing: | As with literal_block, doctest_block elements are typically
rendered in a monospaced typeface. It is crucial that all
whitespace and line breaks are preserved in the rendered form. |
Content Model¶
%text.model;
Attributes: | The doctest_block element contains the common attributes
(ids, names, dupnames, source, and classes), plus xml:space. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
doctest_block . The %structure.model; parameter entity
indirectly includes doctest_block . |
Examples¶
reStructuredText source:
This is an ordinary paragraph.
>>> print 'this is a Doctest block'
this is a Doctest block
Pseudo-XML fragment from simple parsing:
<paragraph>
This is an ordinary paragraph.
<doctest_block xml:space="preserve">
>>> print 'this is a Doctest block'
this is a Doctest block
document
¶
The document
element is the root (topmost) element of the Docutils
document tree. document
is the direct or indirect ancestor of
every other element in the tree. It encloses the entire document
tree. It is the starting point for a document.
Details¶
Category: | Structural Elements |
---|---|
Parents: | The document element has no parents. |
Children: | document elements may contain structural subelements,
structural elements, and `body elements`_. |
Analogues: | document is analogous to the HTML "html" element and to
several DocBook elements such as "book". |
Content Model¶
( (title, subtitle?)?, decoration?, (docinfo, transition?)?, %structure.model; )
Depending on the source of the data and the stage of processing, the "document" may not initially contain a "title". A document title is not directly representable in reStructuredText. Instead, a lone top-level section may have its title promoted to become the document title, and similarly for a lone second-level (sub)section's title to become the document subtitle.
The contents of "decoration" may be specified in a document, constructed programmatically, or both. The "docinfo" may be transformed from an initial field_list.
See the %structure.model; parameter entity for details of the body
of a document
.
Attributes: | The document element contains the common attributes (ids,
names, dupnames, source, and classes), plus an optional title
attribute which stores the document title metadata. |
---|
Examples¶
reStructuredText source:
A Title
=======
A paragraph.
Complete pseudo-XML result from simple parsing:
<document>
<section ids="a-title" names="a title">
<title>
A Title
<paragraph>
A paragraph.
After applying transforms, the section title is promoted to become the document title:
<document ids="a-title" names="a title">
<title>
A Title
<paragraph>
A paragraph.
enumerated_list
¶
The enumerated_list
element contains list_item elements which are
uniformly marked with enumerator labels.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain enumerated_list . |
Children: | enumerated_list elements contain one or more list_item
elements. |
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."). |
Content Model¶
(list_item +)
Attributes: | The
|
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
|
Examples¶
reStructuredText source:
1. Item 1.
(A) Item A.
(B) Item B.
(C) Item C.
2. Item 2.
Pseudo-XML fragment from simple parsing:
<enumerated_list enumtype="arabic" prefix="" suffix=".">
<list_item>
<paragraph>
Item 1.
<enumerated_list enumtype="upperalpha" prefix="(" suffix=")">
<list_item>
<paragraph>
Item A.
<list_item>
<paragraph>
Item B.
<list_item>
<paragraph>
Item C.
<list_item>
<paragraph>
Item 2.
See list_item for another example.
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.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain error . |
Children: | error elements contain one or more `body elements`_. |
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). |
Content Model¶
(%body.elements;)+
Attributes: | The error element contains only the common attributes: ids,
names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
error . The %structure.model; parameter entity indirectly
includes error . |
Examples¶
reStructuredText source:
.. Error:: Does not compute.
Pseudo-XML fragment from simple parsing:
<error>
<paragraph>
Does not compute.
field
¶
The field
element contains a pair of field_name and field_body
elements.
Details¶
Category: | Body Subelements |
---|---|
Parents: | The following elements may contain field : docinfo,
field_list |
Children: | Each field element contains one field_name and one
field_body element. |
Analogues: | field has no direct analogues in common DTDs. |
Processing: | See field_list. |
Content Model¶
(field_name, field_body)
Attributes: | The field element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %bibliographic.elements; parameter entity directly includes
field . |
Examples¶
See the examples for the field_list and docinfo elements.
field_body
¶
The field_body
element contains body elements. It is analogous to
a database field's data.
Details¶
Category: | Body Subelements |
---|---|
Parents: | Only the field element contains field_body . |
Children: | field_body elements may contain `body elements`_. |
Analogues: | field_body has no direct analogues in common DTDs. |
Processing: | See field_list. |
Content Model¶
(%body.elements;)*
Attributes: | The field_body element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
See the examples for the field_list and docinfo elements.
field_list
¶
The field_list
element contains two-column table-like structures
resembling database records (label & data pairs). Field lists are
often meant for further processing. In reStructuredText, field lists
are used to represent bibliographic fields (contents of the docinfo
element) and directive options.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain field_list . |
Children: | field_list elements contain one or more field elements. |
Analogues: | field_list has no direct analogues in common DTDs. It can be
emulated with primitives such as tables. |
Processing: | A field_list is typically rendered as a two-column list, where
the first column contains "labels" (usually with a colon suffix).
However, field lists are often used for extension syntax or
special processing. Such structures do not survive as field lists
to be rendered. |
Content Model¶
(field +)
Attributes: | The field_list element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
field_list . The %structure.model; parameter entity
indirectly includes field_list . |
Examples¶
reStructuredText source:
:Author: Me
:Version: 1
:Date: 2001-08-11
:Parameter i: integer
Pseudo-XML fragment from simple parsing:
<field_list>
<field>
<field_name>
Author
<field_body>
<paragraph>
Me
<field>
<field_name>
Version
<field_body>
<paragraph>
1
<field>
<field_name>
Date
<field_body>
<paragraph>
2001-08-11
<field>
<field_name>
Parameter i
<field_body>
<paragraph>
integer
field_name
¶
The field_name
element contains text; it is analogous to a
database field's name.
Details¶
Category: | Body Subelements (simple) |
---|---|
Parents: | Only the field element contains field_name . |
Children: | field_name elements may contain text data plus inline elements. |
Analogues: | field_name has no direct analogues in common DTDs. |
Processing: | See field_list. |
Content Model¶
%text.model;
Attributes: | The field_name element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
See the examples for the field_list and docinfo elements.
generated
¶
Docutils wraps generated
elements around text that is inserted
(generated) by Docutils; i.e., text that was not in the document, like
section numbers inserted by the "sectnum" directive.
header
¶
The header
element is a container element whose contents are meant
to appear at the top of a web page, or at the top of every printed
page.
Details¶
Category: | Decorative Elements |
---|---|
Parents: | Only the decoration element contains header . |
Children: | header elements may contain `body elements`_. |
Analogues: | There are no direct analogies to header in HTML or DocBook.
Equivalents are typically constructed from primitives and/or
generated by the processing system. |
Content Model¶
(%body.elements;)+
Attributes: | The header element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
reStructuredText source fragment:
.. header:: This space for rent.
Pseudo-XML fragment from simple parsing:
<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.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain hint . |
Children: | hint elements contain one or more `body elements`_. |
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). |
Content Model¶
(%body.elements;)+
Attributes: | The hint element contains only the common attributes: ids,
names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
hint . The %structure.model; parameter entity indirectly
includes hint . |
Examples¶
reStructuredText source:
.. Hint:: It's bigger than a bread box.
Pseudo-XML fragment from simple parsing:
<hint>
<paragraph>
It's bigger than a bread box.
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.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain important . |
Children: | important elements contain one or more `body elements`_. |
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). |
Content Model¶
(%body.elements;)+
Attributes: | The important element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
important . The %structure.model; parameter entity
indirectly includes important . |
Examples¶
reStructuredText source:
.. Important::
* Wash behind your ears.
* Clean up your room.
* Back up your data.
* Call your mother.
Pseudo-XML fragment from simple parsing:
<important>
<bullet_list>
<list_item>
<paragraph>
Wash behind your ears.
<list_item>
<paragraph>
Clean up your room.
<list_item>
<paragraph>
Back up your data.
<list_item>
<paragraph>
Call your mother.
line
¶
The line
element contains a single line of text, part of a
line_block.
Details¶
Category: | Body Subelements (simple) |
---|---|
Parents: | Only the line_block element contains line . |
Children: | line elements may contain text data plus inline elements. |
Analogues: | line has no direct analogues in common DTDs. It can be
emulated with primitives or type effects. |
Processing: | See line_block. |
Content Model¶
%text.model;
Attributes: | The line element contains the common attributes (ids,
names, dupnames, source, and classes), plus xml:space. |
---|
Examples¶
See line_block.
line_block
¶
The line_block
element contains a sequence of lines and nested
line blocks. Line breaks (implied between elements) and leading
whitespace (indicated by nesting) is significant and must be
preserved. line_block
elements are commonly used for verse and
addresses. See literal_block for an alternative useful for program
listings and interactive computer sessions.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain line_block . |
Children: | line_block elements may contain line elements and nested
line_block elements. |
Analogues: | line_block is analogous to the DocBook "literallayout" element
and to the HTML "pre" element (with modifications to typeface
styles). |
Processing: | Unlike literal_block , line_block elements are typically
rendered in an ordinary text typeface. It is crucial that leading
whitespace and line breaks are preserved in the rendered form. |
Content Model¶
(line | line_block)+
Attributes: | The line_block element contains the common attributes (ids,
names, dupnames, source, and classes), plus xml:space. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
line_block . The %structure.model; parameter entity
indirectly includes line_block . |
Examples¶
reStructuredText uses a directive to indicate a line_block
.
Example source:
Take it away, Eric the Orchestra Leader!
| A one, two, a one two three four
|
| Half a bee, philosophically,
| must, *ipso facto*, half not be.
| But half the bee has got to be,
| *vis a vis* its entity. D'you see?
|
| But can a bee be said to be
| or not to be an entire bee,
| when half the bee is not a bee,
| due to some ancient injury?
|
| Singing...
Pseudo-XML fragment from simple parsing:
<paragraph>
Take it away, Eric the Orchestra Leader!
<line_block>
<line>
A one, two, a one two three four
<line>
<line>
Half a bee, philosophically,
<line_block>
<line>
must,
<emphasis>
ipso facto
, half not be.
<line>
But half the bee has got to be,
<line_block>
<line>
<emphasis>
vis a vis
its entity. D'you see?
<line>
<line>
But can a bee be said to be
<line_block>
<line>
or not to be an entire bee,
<line_block>
<line>
when half the bee is not a bee,
<line_block>
<line>
due to some ancient injury?
<line>
<line>
Singing...
list_item
¶
The list_item
element is a container for the elements of a list
item.
Details¶
Category: | Body Subelements (compound) |
---|---|
Parents: | The bullet_list and enumerated_list elements contain
list_item . |
Children: | list_item elements may contain `body elements`_. |
Analogues: | list_item is analogous to the HTML "li" element and to the
DocBook "listitem" element. |
Processing: | See bullet_list or enumerated_list. |
Content Model¶
(%body.elements;)*
Attributes: | The list_item element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
reStructuredText source:
1. Outer list, item 1.
* Inner list, item 1.
* Inner list, item 2.
2. Outer list, item 2.
Pseudo-XML fragment from simple parsing:
<enumerated_list enumtype="arabic" prefix="" suffix=".">
<list_item>
<paragraph>
Outer list, item 1.
<bullet_list bullet="*">
<list_item>
<paragraph>
Inner list, item 1.
<list_item>
<paragraph>
Inner list, item 2.
<list_item>
<paragraph>
Outer list, item 2.
See bullet_list or enumerated_list for further examples.
literal_block
¶
The literal_block
element contains a block of text where line
breaks and whitespace are significant and must be preserved.
literal_block
elements are commonly used for program listings and
interactive computer sessions. See line_block for an alternative
useful for verse and addresses.
Details¶
Category: | Simple Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain literal_block . |
Children: | literal_block elements may contain text data plus inline
elements. |
Analogues: | literal_block is analogous to the HTML "pre" element and to
the DocBook "programlisting" and "screen" elements. |
Processing: | literal_block elements are typically rendered in a monospaced
typeface. It is crucial that all whitespace and line breaks are
preserved in the rendered form. |
Content Model¶
%text.model;
Attributes: | The literal_block element contains the common attributes
(ids, names, dupnames, source, and classes), plus xml:space. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
literal_block . The %structure.model; parameter entity
indirectly includes literal_block . |
Examples¶
reStructuredText source:
Here is a literal block::
if literal_block:
text = 'is left as-is'
spaces_and_linebreaks = 'are preserved'
markup_processing = None
Pseudo-XML fragment from simple parsing:
<paragraph>
Here is a literal block:
<literal_block xml:space="preserve">
if literal_block:
text = 'is left as-is'
spaces_and_linebreaks = 'are preserved'
markup_processing = None
math
¶
The math
element contains text in LaTeX math format [1]
that is typeset as mathematical notation (inline formula).
If the output format does not support math typesetting, the content is inserted verbatim.
Details¶
Category: | Inline Elements |
---|---|
Parents: | All elements employing the %inline.elements; parameter entities in
their content models may contain math . |
Children: | math elements may contain text data. |
Analogues: | math is analogous to a MathML "math" element or
the LaTeX ($ math $ ) mode. |
Processing: | Rendered as mathematical notation. |
Content Model¶
%text.model;
Attributes: | The math element contains the common attributes
(ids, names, dupnames, source, and classes). |
---|
[1] | (1, 2) For details of the supported mathematical language, see the "math" directive |
math_block
¶
The math_block
element contains a block of text in LaTeX math
format [1] that is typeset as mathematical notation
(display formula). The math_block
element is generated during
the initial parse from a "math" directive.
If the output format does not support math typesetting, the content is inserted verbatim.
Details¶
Category: | Simple Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain math_block . |
Children: | math_block elements may contain text data. |
Analogues: | math_block is analogous to a LaTeX "equation*" environment or
a MathML "math" element displayed as block-level element. |
Processing: | Rendered in a block as mathematical notation, typically centered or with indentation |
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.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain note . |
Children: | note elements contain one or more `body elements`_. |
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). |
Content Model¶
(%body.elements;)+
Attributes: | The note element contains only the common attributes: ids,
names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
note . The %structure.model; parameter entity indirectly
includes note . |
Examples¶
reStructuredText source:
.. Note:: Admonitions can be handy to break up a
long boring technical document.
Pseudo-XML fragment from simple parsing:
<note>
<paragraph>
Admonitions can be handy to break up a
long boring technical document.
option
¶
The option
element groups an option string together with zero or
more option argument placeholders. Note that reStructuredText
currently supports only one argument per option.
Details¶
Category: | Body Subelements |
---|---|
Parents: | Only the option_group element contains option . |
Children: | Each option element contains one option_string and zero or
more option_argument elements. |
Analogues: | option has no direct analogues in common DTDs. |
Processing: | See option_list. |
Content Model¶
(option_string, option_argument *)
Attributes: | The option element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
See the examples for the option_list element.
option_argument
¶
The option_argument
element contains placeholder text for option
arguments.
Details¶
Category: | Body Subelements |
---|---|
Parents: | Only the option element contains option_argument . |
Children: | option_argument elements contain text data only. |
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. |
Content Model¶
(#PCDATA)
Attributes: | The
|
---|
Examples¶
See the examples for the option_list element.
option_group
¶
The option_group
element groups together one or more option
elements, all synonyms.
Details¶
Category: | |
---|---|
Parents: | Only the option_list_item element contains |
Children: |
Each |
Analogues: |
|
Processing: | Typically option elements within an |
Content Model¶
(option_group, description)
Attributes: | The option_group element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
See the examples for the option_list element.
option_list
¶
Each option_list
element contains a two-column list of
command-line options and descriptions, documenting a program's
options.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain option_list . |
Children: | option_list elements contain one or more option_list_item
elements. |
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. |
Content Model¶
(option_list_item +)
Attributes: | The option_list element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
option_list . The %structure.model; parameter entity
indirectly includes option_list . |
Examples¶
reStructuredText source:
-a command-line option "a"
-1 file, --one=file, --two file
Multiple options with arguments.
Pseudo-XML fragment from simple parsing:
<option_list>
<option_list_item>
<option_group>
<option>
<option_string>
-a
<description>
<paragraph>
command-line option "a"
<option_list_item>
<option_group>
<option>
<option_string>
-1
<option_argument delimiter=" ">
file
<option>
<option_string>
--one
<option_argument delimiter="=">
file
<option>
<option_string>
--two
<option_argument delimiter=" ">
file
<description>
<paragraph>
Multiple options with arguments.
option_list_item
¶
The option_list_item
element is a container for a pair of
option_group and description elements.
Details¶
Category: | Body Subelements |
---|---|
Parents: | Only the option_list element contains option_list_item . |
Children: | Each option_list_item element contains one option_group and
one description element. |
Analogues: | option_list_item has no direct analogues in common DTDs. |
Processing: | See option_list. |
Content Model¶
(option_group, description)
Attributes: | The option_list_item element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
See the examples for the option_list element.
option_string
¶
The option_string
element contains the text of a command-line
option.
Details¶
Category: | Body Subelements |
---|---|
Parents: | Only the option element contains option_string . |
Children: | option_string elements contain text data only. |
Analogues: | option_string has no direct analogues in common DTDs. |
Processing: | The option_string text is typically rendered in a monospaced
typeface. |
Content Model¶
(#PCDATA)
Attributes: | The option_string element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
See the examples for the option_list element.
organization
¶
The organization
element contains the name of document author's
organization, or the organization responsible for the document.
Details¶
Category: | Bibliographic Elements |
---|---|
Parents: | Only the docinfo element contains organization . |
Children: | organization elements may contain text data plus inline
elements. |
Analogues: | organization is analogous to the DocBook "orgname",
"corpname", or "publishername" elements. |
Processing: | See docinfo. |
Content Model¶
%text.model;
Attributes: | The organization element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %bibliographic.elements; parameter entity directly includes
organization . |
Examples¶
reStructuredText source:
Document Title
==============
:Organization: Humankind
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<organization>
Humankind
See docinfo for a more complete example, including processing context.
paragraph
¶
The paragraph
element contains the text and inline elements of a
single paragraph, a fundamental building block of documents.
Details¶
Category: | Simple Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain paragraph . |
Children: | paragraph elements may contain text data plus inline
elements. |
Analogues: | paragraph is analogous to the HTML "p" element and to the
DocBook "para" elements. |
Content Model¶
%text.model;
Attributes: | The paragraph element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
paragraph . The %structure.model; parameter entity
indirectly includes paragraph . |
Examples¶
reStructuredText source:
A paragraph.
Pseudo-XML fragment from simple parsing:
<paragraph>
A paragraph.
revision
¶
The revision
element contains the revision number of the document.
It can be used alone or in conjunction with version.
Details¶
Category: | Bibliographic Elements |
---|---|
Parents: | Only the docinfo element contains revision . |
Children: | revision elements may contain text data plus inline
elements. |
Analogues: | revision is analogous to but simpler than the DocBook
"revision" element. It closely matches the DocBook "revnumber"
element, but in a simpler context. |
Processing: | Often used with the RCS/CVS keyword "Revision". See docinfo. |
Content Model¶
%text.model;
Attributes: | The revision element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %bibliographic.elements; parameter entity directly includes
revision . |
Examples¶
reStructuredText source:
Document Title
==============
:Version: 1
:Revision: b
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<version>
1
<revision>
b
See docinfo for a more complete example, including processing context.
rubric
¶
rubric n. 1. 原稿、本、法令のなかのタイトル、頭書き。赤字や本文テキストよりも目立つように書かれている。
—Random House Webster's College Dictionary, 1991
A rubric is like an informal heading that doesn't correspond to the document's structure.
section
¶
The section
element is the main unit of hierarchy for Docutils
documents. Docutils section
elements are a recursive structure; a
section
may contain other section
elements, without limit.
Paragraphs and other body elements may occur before a section
, but
not after it.
Details¶
Category: | Structural Elements |
---|---|
Parents: | The following elements may contain section : document,
section |
Children: | section elements begin with a title, and may contain `body
elements`_ as well as transition, topic, and sidebar elements. |
Analogues: | section is analogous to DocBook recursive "section" elements,
and to HTML "div" elements combined with "h1" etc. title elements. |
Content Model¶
(title, %structure.model;)
See the %structure.model; parameter entity for details of the body
of a section
.
Attributes: | The section element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %section.elements; parameter entity directly includes
section . The %structure.model; parameter entity indirectly
includes section . |
Examples¶
reStructuredText source:
Title 1
=======
Paragraph 1.
Title 2
-------
Paragraph 2.
Title 3
=======
Paragraph 3.
Title 4
-------
Paragraph 4.
Complete pseudo-XML result after parsing:
<document>
<section ids="title-1" names="title 1">
<title>
Title 1
<paragraph>
Paragraph 1.
<section ids="title-2" names="title 2">
<title>
Title 2
<paragraph>
Paragraph 2.
<section ids="title-3" names="title 3">
<title>
Title 3
<paragraph>
Paragraph 3.
<section ids="title-4" names="title 4">
<title>
Title 4
<paragraph>
Paragraph 4.
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).
Details¶
Category: | Structural Elements |
---|---|
Parents: | The following elements may contain sidebar : document,
section |
Children: | sidebar elements begin with a title and an optional subtitle
and contain `body elements`_ and topic elements. |
Analogues: | sidebar is analogous to the DocBook "sidebar" element. |
Processing: | A sidebar element should be set off from the rest of the
document somehow, typically with a border. Sidebars typically
"float" to the side of the page and the document's main text flows
around them. |
Content Model¶
(title, subtitle?, (%body.elements; | topic)+)
Attributes: | The sidebar element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %structure.model; parameter entity directly includes
sidebar . |
Examples¶
The "sidebar" directive is used to create a sidebar
element.
reStructuredText source:
.. sidebar:: Title
:subtitle: If Desired
Body.
Pseudo-XML fragment from simple parsing:
<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.
Details¶
Category: | Bibliographic Elements |
---|---|
Parents: | Only the docinfo element contains status . |
Children: | status elements may contain text data plus inline elements. |
Analogues: | status is analogous to the DocBook "status" element. |
Processing: | See docinfo. |
Content Model¶
%text.model;
Attributes: | The status element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %bibliographic.elements; parameter entity directly includes
status . |
Examples¶
reStructuredText source:
Document Title
==============
:Status: Work In Progress
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<status>
Work In Progress
See docinfo for a more complete example, including processing context.
subtitle
¶
The subtitle
element stores the subtitle of a document.
Details¶
Category: | Structural Subelements |
---|---|
Parents: | The document and sidebar elements may contain subtitle . |
Children: | subtitle elements may contain text data plus inline
elements. |
Analogues: | subtitle is analogous to HTML header elements ("h2" etc.) and
to the DocBook "subtitle" element. |
Processing: | A document's subtitle is usually rendered smaller than its title. |
Content Model¶
%text.model;
Attributes: | The subtitle element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
reStructuredText source:
=======
Title
=======
----------
Subtitle
----------
A paragraph.
Complete pseudo-XML result after parsing and applying transforms:
<document ids="title" names="title">
<title>
Title
<subtitle ids="subtitle" names="subtitle">
Subtitle
<paragraph>
A paragraph.
Note how two section levels have collapsed, promoting their titles to
become the document's title and subtitle. Since there is only one
structural element (document), the subsection's ids
and names
attributes are stored in the subtitle
element.
table
¶
Docutils tables are based on the Exchange subset of the CALS-table model (OASIS Technical Memorandum 9901:1999 "XML Exchange Table Model DTD", http://www.oasis-open.org/html/tm9901.htm).
term
¶
The term
element contains a word or phrase being defined in a
definition_list.
Details¶
Category: | Body Subelements (simple) |
---|---|
Parents: | Only the definition_list_item element contains term . |
Children: | term elements may contain text data plus inline elements. |
Analogues: | term is analogous to the HTML "dt" element and to the DocBook
"term" element. |
Processing: | See definition_list_item. |
Content Model¶
%text.model;
Attributes: | The term element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|
Examples¶
See the examples for the definition_list, definition_list_item, and classifier elements.
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.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain tip . |
Children: | tip elements contain one or more `body elements`_. |
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). |
Content Model¶
(%body.elements;)+
Attributes: | The tip element contains only the common attributes: ids,
names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes tip .
The %structure.model; parameter entity indirectly includes
tip . |
Examples¶
reStructuredText source:
.. Tip:: 15% if the service is good.
Pseudo-XML fragment from simple parsing:
<tip>
<paragraph>
15% if the service is good.
title
¶
The title
element stores the title of a document, section,
topic, sidebar, or generic admonition.
Details¶
Category: | Structural Subelements |
---|---|
Parents: | The following elements may contain title : document, section,
topic, sidebar, admonition |
Children: | title elements may contain text data plus inline elements. |
Analogues: | title is analogous to HTML "title" and header ("h1" etc.)
elements, and to the DocBook "title" element. |
Content Model¶
%text.model;
Attributes: | The
|
---|
Examples¶
reStructuredText source:
A Title
=======
A paragraph.
Pseudo-XML fragment from simple parsing:
<section ids="a-title" names="a title">
<title>
A Title
<paragraph>
A paragraph.
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
.
Details¶
Category: | Structural Elements |
---|---|
Parents: | The following elements may contain topic : document, section,
sidebar |
Children: | topic elements begin with a title and may contain `body
elements`_. |
Analogues: | topic is analogous to the DocBook "simplesect" element. |
Processing: | A topic element should be set off from the rest of the
document somehow, such as with indentation or a border. |
Content Model¶
(title?, (%body.elements;)+)
Attributes: | The topic element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %structure.model; parameter entity directly includes
topic . |
Examples¶
The "topic" directive is used to create a topic
element.
reStructuredText source:
.. topic:: Title
Body.
Pseudo-XML fragment from simple parsing:
<topic>
<title>
Title
<paragraph>
Body.
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 [2] or document, nor may
two transitions be immediately adjacent.
See Doctree Representation of Transitions in A Record of reStructuredText Syntax Alternatives.
[2] | In reStructuredText markup, a transition may appear to fall at the end of a section immediately before another section. A transform recognizes this case and moves the transition so it separates the sections. |
Details¶
Category: | Structural Subelements |
---|---|
Parents: | The following elements may contain transition : document,
section |
Children: | transition is an empty element and has no children. |
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. |
Content Model¶
EMPTY
The transition
element has no content; it is a "point element".
Attributes: | The transition element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %structure.model; parameter entity directly includes
transition . |
Examples¶
reStructuredText source:
Paragraph 1.
--------
Paragraph 2.
Complete pseudo-XML result after parsing:
<document>
<paragraph>
Paragraph 1.
<transition>
<paragraph>
Paragraph 2.
version
¶
The version
element contains the version number of the document.
It can be used alone or in conjunction with revision.
Details¶
Category: | Bibliographic Elements |
---|---|
Parents: | Only the docinfo element contains version . |
Children: | version elements may contain text data plus inline
elements. |
Analogues: | version may be considered analogous to the DocBook "revision",
"revnumber", or "biblioid" elements. |
Processing: | Sometimes used with the RCS/CVS keyword "Revision". See docinfo and revision. |
Content Model¶
%text.model;
Attributes: | The version element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %bibliographic.elements; parameter entity directly includes
version . |
Examples¶
reStructuredText source:
Document Title
==============
:Version: 1.1
Complete pseudo-XML result after parsing and applying transforms:
<document ids="document-title" names="document title">
<title>
Document Title
<docinfo>
<version>
1.1
See docinfo for a more complete example, including processing context.
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.
Details¶
Category: | Compound Body Elements |
---|---|
Parents: | All elements employing the %body.elements; or
%structure.model; parameter entities in their content models
may contain warning . |
Children: | warning elements contain one or more `body elements`_. |
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). |
Content Model¶
(%body.elements;)+
Attributes: | The warning element contains only the common attributes:
ids, names, dupnames, source, and classes. |
---|---|
Parameter Entities: | |
The %body.elements; parameter entity directly includes
warning . The %structure.model; parameter entity indirectly
includes warning . |
Examples¶
reStructuredText source:
.. WARNING:: Reader discretion is strongly advised.
Pseudo-XML fragment from simple parsing:
<warning>
<paragraph>
Reader discretion is strongly advised.
Attribute Reference¶
Common Attributes: Through the %basic.atts; parameter entity, all elements contain the following attributes: ids, names, dupnames, source, and classes.
Attribute types:
CDATA
- Character data.
CDATA
attributes may contain arbitrary text. ID
- Like a
NMTOKEN
, but it must begin with a letter (a "name production"). IdenticalID
values must not appear more than once in a document; i.e., ID values must uniquely identify their elements. IDREF
- A reference to an
ID
value (a name production) of another element. IDREFS
- One or more space-separated
ID
references (name productions). NMTOKEN
- A "name token". One or more of letters, digits, ".", "-", and "_".
NMTOKENS
- One or more space-separated
NMTOKEN
names. %yesorno;
- No if zero ("0"), yes if any other value. This is a parameter
entity which resolves to a
NMTOKEN
attribute type. %number;
- This emphasizes that the attribute value must be a number. This
is a parameter entity which resolves to a
NMTOKEN
attribute type. - enumeration
- The attribute value may be one of a specified list of values.
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 zero or more names used
to classify an element. The names are converted to conform to the
regular expression [a-z](-?[a-z0-9]+)*
(see the "class"
directive description for details and rationale).
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.
Parameter Entity Reference¶
Parameter entities are used to simplify the DTD (to share definitions and reduce duplication) and to allow the DTD to be customized by wrapper DTDs (external client DTDs that use or import the Docutils DTD). Parameter entities may be overridden by wrapper DTDs, replacing the definitions below with custom definitions. Parameter entities whose names begin with "additional" are meant to allow easy extension by wrapper DTDs.
%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:
admonition | attention | block_quote | bullet_list | caution | citation | compound | comment | container | danger | definition_list | doctest_block | enumerated_list | error | field_list | figure | footnote | hint | image | important | line_block | literal_block | note | option_list | paragraph | pending | raw reference | rubric | substitution_definition | system_message | table | target | tip | warning %additional.body.elements;
The %additional.body.elements;
parameter entity can be used by
wrapper DTDs to extend %body.elements;
.
The %body.elements;
parameter entity is directly employed in the
content models of the following elements: admonition, attention,
block_quote, caution, citation, compound, danger, definition,
description, entry, error, field_body, footer, footnote,
header, hint, important, legend, list_item, note, sidebar,
system_message, tip, topic, warning
Via %structure.model;, the %body.elements;
parameter entity is
indirectly employed in the content models of the document and
section elements.
%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:
abbreviation | acronym | citation_reference | emphasis | footnote_reference | generated | image | inline | literal | problematic | raw | reference | strong | substitution_reference | subscript | superscript | target | title_reference %additional.inline.elements;
The %additional.inline.elements;
parameter entity can be used by
wrapper DTDs to extend %inline.elements;
.
Via %text.model;, the %inline.elements;
parameter entity is
indirectly employed in the content models of the following elements:
abbreviation, acronym, address, attribution, author, caption,
classifier, contact, copyright, date, doctest_block, emphasis,
generated, inline, line_block, literal_block, math, math_block,
organization,
paragraph, problematic, raw, reference, revision, rubric,
status, strong, subscript, substitution_definition,
substitution_reference, subtitle, superscript, target, term,
title, title_reference, version
%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