1 ============================
2 The Docutils Document Tree
3 ============================
5 A Guide to the Docutils DTD
6 ***************************
9 :Contact: goodger@python.org
12 :Copyright: This document has been placed in the public domain.
15 .. contents:: :depth: 1
18 This document describes the XML data structure of Docutils_ documents:
19 the relationships and semantics of elements and attributes. The
20 Docutils document structure is formally defined by the `Docutils
21 Generic DTD`_ XML document type definition, docutils.dtd_, which is
22 the definitive source for details of element structural relationships.
24 This document does not discuss implementation details. Those can be
25 found in internal documentation (docstrings) for the
26 ``docutils.nodes`` module, where the document tree data structure is
27 implemented in a class library.
29 The reader is assumed to have some familiarity with XML or SGML, and
30 an understanding of the data structure meaning of "tree". For a list
31 of introductory articles, see `Introducing the Extensible Markup
34 The reStructuredText_ markup is used for illustrative examples
35 throughout this document. For a gentle introduction, see `A
36 ReStructuredText Primer`_. For complete technical details, see the
37 `reStructuredText Markup Specification`_.
40 .. _Docutils: http://docutils.sourceforge.net/
41 .. _Docutils Generic DTD:
43 .. _docutils.dtd: docutils.dtd
44 .. _Introducing the Extensible Markup Language (XML):
45 http://xml.coverpages.org/xmlIntro.html
46 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
47 .. _A ReStructuredText Primer: ../user/rst/quickstart.html
48 .. _reStructuredText Markup Specification: rst/restructuredtext.html
57 Below is a simplified diagram of the hierarchy of elements in the
58 Docutils document tree structure. An element may contain any other
59 elements immediately below it in the diagram. Notes are written in
60 square brackets. Element types in parentheses indicate recursive or
61 one-to-many relationships; sections may contain (sub)sections, tables
62 contain further body elements, etc. ::
64 +--------------------------------------------------------------------+
65 | document [may begin with a title, subtitle, decoration, docinfo] |
66 | +--------------------------------------+
67 | | sections [each begins with a title] |
68 +-----------------------------+-------------------------+------------+
69 | [body elements:] | (sections) |
70 | | - literal | - lists | | - hyperlink +------------+
71 | | blocks | - tables | | targets |
72 | para- | - doctest | - block | foot- | - sub. defs |
73 | graphs | blocks | quotes | notes | - comments |
74 +---------+-----------+----------+-------+--------------+
75 | [text]+ | [text] | (body elements) | [text] |
76 | (inline +-----------+------------------+--------------+
80 The Docutils document model uses a simple, recursive model for section
81 structure. A document_ node may contain body elements and section_
82 elements. Sections in turn may contain body elements and sections.
83 The level (depth) of a section element is determined from its physical
84 nesting level; unlike other document models (``<h1>`` in HTML_,
85 ``<sect1>`` in DocBook_, ``<div1>`` in XMLSpec_) the level is not
86 incorporated into the element name.
88 The Docutils document model uses strict element content models. Every
89 element has a unique structure and semantics, but elements may be
90 classified into general categories (below). Only elements which are
91 meant to directly contain text data have a mixed content model, where
92 text data and inline elements may be intermixed. This is unlike the
93 much looser HTML_ document model, where paragraphs and text data may
94 occur at the same level.
100 Structural elements may only contain child elements; they do not
101 directly contain text data. Structural elements may contain body
102 elements or further structural elements. Structural elements can only
103 be child elements of other structural elements.
105 Category members: document_, section_, topic_, sidebar_
108 Structural Subelements
109 ----------------------
111 Structural subelements are child elements of structural elements.
112 Simple structuctural subelements (title_, subtitle_) contain text
113 data; the others are compound and do not directly contain text data.
115 Category members: title_, subtitle_, decoration_, docinfo_,
119 Bibliographic Elements
120 ``````````````````````
122 The docinfo_ element is an optional child of document_. It groups
123 bibliographic elements together. All bibliographic elements except
124 authors_ and field_ contain text data. authors_ contains further
125 bibliographic elements (most notably author_). field_ contains
126 field_name_ and field_body_ body subelements.
128 Category members: address_, author_, authors_, contact_, copyright_,
129 date_, field_, organization_, revision_, status_, version_
135 The decoration_ element is also an optional child of document_. It
136 groups together elements used to generate page headers and footers.
138 Category members: footer_, header_
144 Body elements are contained within structural elements and compound
145 body elements. There are two subcategories of body elements: simple
148 Category members: admonition_, attention_, block_quote_, bullet_list_,
149 caution_, citation_, comment_, compound_, container_, danger_,
150 definition_list_, doctest_block_, enumerated_list_, error_,
151 field_list_, figure_, footnote_, hint_, image_, important_,
152 line_block_, literal_block_, note_, option_list_, paragraph_,
153 pending_, raw_, rubric_, substitution_definition_, system_message_,
154 table_, target_, tip_, warning_
160 Simple body elements are empty or directly contain text data. Those
161 that contain text data may also contain inline elements. Such
162 elements therefore have a "mixed content model".
164 Category members: comment_, doctest_block_, image_, literal_block_,
165 math_block_, paragraph_, pending_, raw_, rubric_, substitution_definition_,
169 Compound Body Elements
170 ----------------------
172 Compound body elements contain local substructure (body subelements)
173 and further body elements. They do not directly contain text data.
175 Category members: admonition_, attention_, block_quote_, bullet_list_,
176 caution_, citation_, compound_, container_, danger_, definition_list_,
177 enumerated_list_, error_, field_list_, figure_, footnote_, hint_,
178 important_, line_block, note_, option_list_, system_message_, table_,
185 Compound body elements contain specific subelements (e.g. bullet_list_
186 contains list_item_). Subelements may themselves be compound elements
187 (containing further child elements, like field_) or simple data
188 elements (containing text data, like field_name_). These subelements
189 always occur within specific parent elements, never at the body
190 element level (beside paragraphs, etc.).
192 Category members (simple): attribution_, caption_, classifier_,
193 colspec_, field_name_, label_, line_, option_argument_,
194 option_string_, term_
196 Category members (compound): definition_, definition_list_item_,
197 description_, entry_, field_, field_body_, legend_, list_item_,
198 option_, option_group_, option_list_item_, row_, tbody_, tgroup_,
205 Inline elements directly contain text data, and may also contain
206 further inline elements. Inline elements are contained within simple
207 body elements. Most inline elements have a "mixed content model".
209 Category members: abbreviation_, acronym_, citation_reference_,
210 emphasis_, footnote_reference_, generated_, image_, inline_, literal_,
211 math_, problematic_, reference_, strong_, subscript_,
212 substitution_reference_, superscript_, target_, title_reference_, raw_
215 .. _HTML: http://www.w3.org/MarkUp/
216 .. _DocBook: http://docbook.org/tdg/en/html/docbook.html
217 .. _XMLSpec: http://www.w3.org/XML/1998/06/xmlspec-report.htm
224 .. contents:: :local:
227 Each element in the DTD (document type definition) is described in its
228 own section below. Each section contains an introduction plus the
229 following subsections:
231 * Details (of element relationships and semantics):
233 - Category: One or more references to the element categories in
234 `Element Hierarchy`_ above. Some elements belong to more than one
237 - Parents: A list of elements which may contain the element.
239 - Children: A list of elements which may occur within the element.
241 - Analogues: Describes analogous elements in well-known document
242 models such as HTML_ or DocBook_. Lists similarities and
245 - Processing: Lists formatting or rendering recommendations for the
250 The formal XML content model from the `Docutils DTD`_, followed by:
252 - Attributes: Describes (or refers to descriptions of) the possible
253 values and semantics of each attribute.
255 - Parameter Entities: Lists the parameter entities which directly or
256 indirectly include the element.
258 * Examples: reStructuredText_ examples are shown along with
259 fragments of the document trees resulting from parsing.
260 _`Pseudo-XML` is used for the results of parsing and processing.
261 Pseudo-XML is a representation of XML where nesting is indicated by
262 indentation and end-tags are not shown. Some of the precision of
263 real XML is given up in exchange for easier readability. For
264 example, the following are equivalent:
269 <section ids="a-title" names="a title">
270 <title>A Title</title>
271 <paragraph>A paragraph.</paragraph>
278 <section ids="a-title" names="a title">
286 Many of the element reference sections below are marked "_`to be
287 completed`". Please help complete this document by contributing to
306 The ``address`` element holds the surface mailing address information
307 for the author (individual or group) of the document, or a third-party
308 contact address. Its structure is identical to that of the
309 literal_block_ element: whitespace is significant, especially
317 `Bibliographic Elements`_
320 The following elements may contain ``address``: docinfo_, authors_
323 ``address`` elements contain text data plus `inline elements`_.
326 ``address`` is analogous to the DocBook "address" element.
329 As with the literal_block_ element, newlines and other whitespace
330 is significant and must be preserved. However, a monospaced
331 typeface need not be used.
344 The ``address`` element contains the `common attributes`_ (ids_,
345 names_, dupnames_, source_, and classes_), plus `xml:space`_.
348 The `%bibliographic.elements;`_ parameter entity directly includes
355 reStructuredText_ source::
360 :Address: 123 Example Ave.
363 Complete pseudo-XML_ result after parsing and applying transforms::
365 <document ids="document-title" names="document title">
373 See docinfo_ for a more complete example, including processing
380 This element is a generic, titled admonition. Also see the specific
381 admonition elements Docutils offers (in alphabetical order): caution_,
382 danger_, error_, hint_, important_, note_, tip_, warning_.
389 `Compound Body Elements`_
392 All elements employing the `%body.elements;`_ or
393 `%structure.model;`_ parameter entities in their content models
394 may contain ``admonition``.
397 ``admonition`` elements begin with a title_ and may contain one or
398 more `body elements`_.
401 ``admonition`` has no direct analogues in common DTDs. It can be
402 emulated with primitives and type effects.
405 Rendered distinctly (inset and/or in a box, etc.).
413 (title_, (`%body.elements;`_)+)
416 The ``admonition`` element contains only the `common attributes`_:
417 ids_, names_, dupnames_, source_, and classes_.
420 The `%body.elements;`_ parameter entity directly includes
421 ``admonition``. The `%structure.model;`_ parameter entity
422 indirectly includes ``admonition``.
428 reStructuredText source::
430 .. admonition:: And, by the way...
432 You can make up your own admonition too.
434 Pseudo-XML_ fragment from simple parsing::
436 <admonition class="admonition-and-by-the-way">
440 You can make up your own admonition too.
446 The ``attention`` element is an admonition, a distinctive and
447 self-contained notice. Also see the other admonition elements
448 Docutils offers (in alphabetical order): caution_, danger_, error_,
449 hint_, important_, note_, tip_, warning_, and the generic admonition_.
456 `Compound Body Elements`_
459 All elements employing the `%body.elements;`_ or
460 `%structure.model;`_ parameter entities in their content models
461 may contain ``attention``.
464 ``attention`` elements contain one or more `body elements`_.
467 ``attention`` has no direct analogues in common DTDs. It can be
468 emulated with primitives and type effects.
471 Rendered distinctly (inset and/or in a box, etc.), with the
472 generated title "Attention!" (or similar).
480 (`%body.elements;`_)+
483 The ``attention`` element contains only the `common attributes`_:
484 ids_, names_, dupnames_, source_, and classes_.
487 The `%body.elements;`_ parameter entity directly includes
488 ``attention``. The `%structure.model;`_ parameter entity
489 indirectly includes ``attention``.
495 reStructuredText source::
497 .. Attention:: All your base are belong to us.
499 Pseudo-XML_ fragment from simple parsing::
503 All your base are belong to us.
515 The ``author`` element holds the name of the author of the document.
522 `Bibliographic Elements`_
525 The following elements may contain ``author``: docinfo_, authors_
528 ``author`` elements may contain text data plus `inline elements`_.
531 ``author`` is analogous to the DocBook "author" element.
545 The ``author`` element contains only the `common attributes`_:
546 ids_, names_, dupnames_, source_, and classes_.
549 The `%bibliographic.elements;`_ parameter entity directly includes
556 reStructuredText_ source::
561 :Author: J. Random Hacker
563 Complete pseudo-XML_ result after parsing and applying transforms::
565 <document ids="document-title" names="document title">
572 See docinfo_ for a more complete example, including processing
579 The ``authors`` element is a container for author information for
580 documents with multiple authors.
587 `Bibliographic Elements`_
590 Only the docinfo_ element contains ``authors``.
593 ``authors`` elements may contain the following elements: author_,
594 organization_, address_, contact_
597 ``authors`` is analogous to the DocBook "authors" element.
608 ((author_, organization_?, address_?, contact_?)+)
611 The ``authors`` element contains only the `common attributes`_:
612 ids_, names_, dupnames_, source_, and classes_.
615 The `%bibliographic.elements;`_ parameter entity directly includes
622 reStructuredText_ source::
627 :Authors: J. Random Hacker; Jane Doe
629 Complete pseudo-XML_ result after parsing and applying transforms::
631 <document ids="document-title" names="document title">
641 In reStructuredText, multiple author's names are separated with
642 semicolons (";") or commas (","); semicolons take precedence. There
643 is currently no way to represent the author's organization, address,
644 or contact in a reStructuredText "Authors" field.
646 See docinfo_ for a more complete example, including processing
653 The ``block_quote`` element is used for quotations set off from the
654 main text (standalone).
661 `Compound Body Elements`_
664 All elements employing the `%body.elements;`_ or
665 `%structure.model;`_ parameter entities in their content models
666 may contain ``block_quote``.
669 ``block_quote`` elements contain `body elements`_ followed by an
670 optional attribution_ element.
673 ``block_quote`` is analogous to the "blockquote" element in both
677 ``block_quote`` elements serve to set their contents off from the
678 main text, typically with indentation and/or other decoration.
686 ((`%body.elements;`_)+, attribution_?)
689 The ``block_quote`` element contains only the `common
690 attributes`_: ids_, names_, dupnames_, source_, and classes_.
693 The `%body.elements;`_ parameter entity directly includes
694 ``block_quote``. The `%structure.model;`_ parameter entity
695 indirectly includes ``block_quote``.
701 reStructuredText source::
703 As a great paleontologist once said,
705 This theory, that is mine, is mine.
709 Pseudo-XML_ fragment from simple parsing::
712 As a great paleontologist once said,
715 This theory, that is mine, is mine.
723 The ``bullet_list`` element contains list_item_ elements which are
724 uniformly marked with bullets. Bullets are typically simple dingbats
725 (symbols) such as circles and squares.
732 `Compound Body Elements`_
735 All elements employing the `%body.elements;`_ or
736 `%structure.model;`_ parameter entities in their content models
737 may contain ``bullet_list``.
740 ``bullet_list`` elements contain one or more list_item_ elements.
743 ``bullet_list`` is analogous to the HTML "ul" element and to the
744 DocBook "itemizedlist" element. HTML's "ul" is short for
745 "unordered list", which we consider to be a misnomer. "Unordered"
746 implies that the list items may be randomly rearranged without
747 affecting the meaning of the list. Bullet lists *are* often
748 ordered; the ordering is simply left implicit.
751 Each list item should begin a new vertical block, prefaced by a
763 The ``bullet_list`` element contains the `common attributes`_
764 (ids_, names_, dupnames_, source_, and classes_), plus bullet_.
766 ``bullet`` is used to record the style of bullet from the input
767 data. In documents processed from reStructuredText_, it contains
768 one of "-", "+", or "*". It may be ignored in processing.
771 The `%body.elements;`_ parameter entity directly includes
772 ``bullet_list``. The `%structure.model;`_ parameter entity
773 indirectly includes ``bullet_list``.
779 reStructuredText_ source::
781 - Item 1, paragraph 1.
787 Pseudo-XML_ fragment from simple parsing::
789 <bullet_list bullet="-">
799 See list_item_ for another example.
811 The ``caution`` element is an admonition, a distinctive and
812 self-contained notice. Also see the other admonition elements
813 Docutils offers (in alphabetical order): attention_, danger_, error_,
814 hint_, important_, note_, tip_, warning_, and the generic admonition_.
821 `Compound Body Elements`_
824 All elements employing the `%body.elements;`_ or
825 `%structure.model;`_ parameter entities in their content models
826 may contain ``caution``.
829 ``caution`` elements contain one or more `body elements`_.
832 ``caution`` is analogous to the DocBook "caution" element.
835 Rendered distinctly (inset and/or in a box, etc.), with the
836 generated title "Caution" (or similar).
844 (`%body.elements;`_)+
847 The ``caution`` element contains only the `common attributes`_:
848 ids_, names_, dupnames_, source_, and classes_.
851 The `%body.elements;`_ parameter entity directly includes
852 ``caution``. The `%structure.model;`_ parameter entity
853 indirectly includes ``caution``.
859 reStructuredText source::
861 .. Caution:: Don't take any wooden nickels.
863 Pseudo-XML_ fragment from simple parsing::
867 Don't take any wooden nickels.
876 ``citation_reference``
877 ======================
885 The ``classifier`` element contains the classification or type of the
886 term_ being defined in a definition_list_. For example, it can be
887 used to indicate the type of a variable.
894 `Body Subelements`_ (simple)
897 Only the definition_list_item_ element contains ``classifier``.
900 ``classifier`` elements may contain text data plus `inline elements`_.
903 ``classifier`` has no direct analogues in common DTDs. It can be
904 emulated with primitives or type effects.
907 See definition_list_item_.
918 The ``classifier`` element contains only the `common attributes`_:
919 ids_, names_, dupnames_, source_, and classes_.
925 Here is a hypothetical data dictionary. reStructuredText_ source::
930 Temporary index variable.
932 Pseudo-XML_ fragment from simple parsing::
935 <definition_list_item>
943 <definition_list_item>
950 Temporary index variable.
974 The ``contact`` element holds contact information for the author
975 (individual or group) of the document, or a third-party contact. It
976 is typically used for an email or web address.
983 `Bibliographic Elements`_
986 The following elements may contain ``contact``: docinfo_, authors_
989 ``contact`` elements may contain text data plus `inline
993 ``contact`` is analogous to the DocBook "email" element. The HTML
994 "address" element serves a similar purpose.
1008 The ``contact`` element contains only the `common attributes`_:
1009 ids_, names_, dupnames_, source_, and classes_.
1011 :Parameter Entities:
1012 The `%bibliographic.elements;`_ parameter entity directly includes
1019 reStructuredText_ source::
1024 :Contact: jrh@example.com
1026 Complete pseudo-XML_ result after parsing and applying transforms::
1028 <document ids="document-title" names="document title">
1033 <reference refuri="mailto:jrh@example.com">
1036 See docinfo_ for a more complete example, including processing
1049 The ``copyright`` element contains the document's copyright statement.
1056 `Bibliographic Elements`_
1059 Only the docinfo_ element contains ``copyright``.
1062 ``copyright`` elements may contain text data plus `inline
1066 ``copyright`` is analogous to the DocBook "copyright" element.
1080 The ``copyright`` element contains only the `common attributes`_:
1081 ids_, names_, dupnames_, source_, and classes_.
1083 :Parameter Entities:
1084 The `%bibliographic.elements;`_ parameter entity directly includes
1091 reStructuredText_ source::
1096 :Copyright: This document has been placed in the public domain.
1098 Complete pseudo-XML_ result after parsing and applying transforms::
1100 <document ids="document-title" names="document title">
1105 This document has been placed in the public domain.
1107 See docinfo_ for a more complete example, including processing
1114 The ``danger`` element is an admonition, a distinctive and
1115 self-contained notice. Also see the other admonition elements
1116 Docutils offers (in alphabetical order): attention_, caution_, error_,
1117 hint_, important_, note_, tip_, warning_, and the generic admonition_.
1124 `Compound Body Elements`_
1127 All elements employing the `%body.elements;`_ or
1128 `%structure.model;`_ parameter entities in their content models
1129 may contain ``danger``.
1132 ``danger`` elements contain one or more `body elements`_.
1135 ``danger`` has no direct analogues in common DTDs. It can be
1136 emulated with primitives and type effects.
1139 Rendered distinctly (inset and/or in a box, etc.), with the
1140 generated title "!DANGER!" (or similar).
1148 (`%body.elements;`_)+
1151 The ``danger`` element contains only the `common attributes`_:
1152 ids_, names_, dupnames_, source_, and classes_.
1154 :Parameter Entities:
1155 The `%body.elements;`_ parameter entity directly includes
1156 ``danger``. The `%structure.model;`_ parameter entity
1157 indirectly includes ``danger``.
1163 reStructuredText source::
1165 .. DANGER:: Mad scientist at work!
1167 Pseudo-XML_ fragment from simple parsing::
1171 Mad scientist at work!
1177 The ``date`` element contains the date of publication, release, or
1178 last modification of the document.
1185 `Bibliographic Elements`_
1188 Only the docinfo_ element contains ``date``.
1191 ``date`` elements may contain text data plus `inline elements`_.
1194 ``date`` is analogous to the DocBook "date" element.
1197 Often used with the RCS/CVS keyword "Date". See docinfo_.
1208 The ``date`` element contains only the `common attributes`_:
1209 ids_, names_, dupnames_, source_, and classes_.
1211 :Parameter Entities:
1212 The `%bibliographic.elements;`_ parameter entity directly includes
1219 reStructuredText_ source::
1226 Complete pseudo-XML_ result after parsing and applying transforms::
1228 <document ids="document-title" names="document title">
1235 See docinfo_ for a more complete example, including processing
1242 The ``decoration`` element is a container for header_ and footer_
1243 elements and potential future extensions. These elements are used for
1244 notes, time/datestamp, processing information, etc.
1251 `Structural Subelements`_
1254 Only the document_ element contains ``decoration``.
1257 ``decoration`` elements may contain `decorative elements`_.
1260 There are no direct analogies to ``decoration`` in HTML or in
1261 DocBook. Equivalents are typically constructed from primitives
1262 and/or generated by the processing system.
1265 See the individual `decorative elements`_.
1273 (header_?, footer_?)
1275 Although the content model doesn't specifically require contents, no
1276 empty ``decoration`` elements are ever created.
1279 The ``decoration`` element contains only the `common attributes`_:
1280 ids_, names_, dupnames_, source_, and classes_.
1286 reStructuredText_ source::
1290 Complete pseudo-XML_ result after parsing and applying transforms,
1291 assuming that the datestamp command-line option or configuration
1292 setting has been supplied::
1298 Generated on: 2002-08-20.
1306 The ``definition`` element is a container for the body elements used
1307 to define a term_ in a definition_list_.
1314 `Body Subelements`_ (compound)
1317 Only definition_list_item_ elements contain ``definition``.
1320 ``definition`` elements may contain `body elements`_.
1323 ``definition`` is analogous to the HTML "dd" element and to the
1324 DocBook "listitem" element (inside a "variablelistentry" element).
1327 See definition_list_item_.
1335 (`%body.elements;`_)+
1338 The ``definition`` element contains only the `common attributes`_:
1339 ids_, names_, dupnames_, source_, and classes_.
1345 See the examples for the definition_list_, definition_list_item_, and
1346 classifier_ elements.
1352 The ``definition_list`` element contains a list of terms and their
1353 definitions. It can be used for glossaries or dictionaries, to
1354 describe or classify things, for dialogues, or to itemize subtopics
1355 (such as in this reference).
1362 `Compound Body Elements`_
1365 All elements employing the `%body.elements;`_ or
1366 `%structure.model;`_ parameter entities in their content models
1367 may contain ``definition_list``.
1370 ``definition_list`` elements contain one or more
1371 definition_list_item_ elements.
1374 ``definition_list`` is analogous to the HTML "dl" element and to
1375 the DocBook "variablelist" element.
1378 See definition_list_item_.
1386 (definition_list_item_ +)
1389 The ``definition_list`` element contains only the `common
1390 attributes`_: ids_, names_, dupnames_, source_, and classes_.
1392 :Parameter Entities:
1393 The `%body.elements;`_ parameter entity directly includes
1394 ``definition_list``. The `%structure.model;`_ parameter entity
1395 indirectly includes ``definition_list``.
1401 reStructuredText_ source::
1407 The ' : ' indicates a classifier in
1408 definition list item terms only.
1410 Pseudo-XML_ fragment from simple parsing::
1413 <definition_list_item>
1419 <definition_list_item>
1426 The ' : ' indicates a classifier in
1427 definition list item terms only.
1429 See definition_list_item_ and classifier_ for further examples.
1432 ``definition_list_item``
1433 ========================
1435 The ``definition_list_item`` element contains a single
1436 term_/definition_ pair (with optional classifier_).
1443 `Body Subelements`_ (compound)
1446 Only the definition_list_ element contains
1447 ``definition_list_item``.
1450 ``definition_list_item`` elements each contain a single term_,
1451 an optional classifier_, and a definition_.
1454 ``definition_list_item`` is analogous to the DocBook
1455 "variablelistentry" element.
1458 The optional classifier_ can be rendered differently from the
1459 term_. They should be separated visually, typically by spaces
1460 plus a colon or dash.
1468 (term_, classifier_?, definition_)
1471 The ``definition_list_item`` element contains only the `common
1472 attributes`_: ids_, names_, dupnames_, source_, and classes_.
1478 reStructuredText_ source::
1480 Tyrannosaurus Rex : carnivore
1481 Big and scary; the "Tyrant King".
1483 Brontosaurus : herbivore
1484 All brontosauruses are thin at one end,
1485 much much thicker in the middle
1486 and then thin again at the far end.
1490 Pseudo-XML_ fragment from simple parsing::
1493 <definition_list_item>
1500 Big and scary; the "Tyrant King".
1501 <definition_list_item>
1508 All brontosauruses are thin at one end,
1509 much much thicker in the middle
1510 and then thin again at the far end.
1514 See definition_list_ and classifier_ for further examples.
1520 The ``description`` element contains body elements, describing the
1521 purpose or effect of a command-line option or group of options.
1531 Only the option_list_item_ element contains ``description``.
1534 ``description`` elements may contain `body elements`_.
1537 ``description`` has no direct analogues in common DTDs.
1548 (`%body.elements;`_)+
1551 The ``description`` element contains only the `common attributes`_:
1552 ids_, names_, dupnames_, source_, and classes_.
1558 See the examples for the option_list_ element.
1564 The ``docinfo`` element is a container for document bibliographic
1565 data, or meta-data (data about the document). It corresponds to the
1566 front matter of a book, such as the title page and copyright page.
1573 `Structural Subelements`_
1576 Only the document_ element contains ``docinfo``.
1579 ``docinfo`` elements contain `bibliographic elements`_.
1582 ``docinfo`` is analogous to DocBook "info" elements ("bookinfo"
1583 etc.). There are no directly analogous HTML elements; the "meta"
1584 element carries some of the same information, albeit invisibly.
1587 The ``docinfo`` element may be rendered as a two-column table or
1588 in other styles. It may even be invisible or omitted from the
1589 processed output. Meta-data may be extracted from ``docinfo``
1590 children; for example, HTML ``<meta>`` tags may be constructed.
1592 When Docutils_ transforms a reStructuredText_ field_list_ into a
1593 ``docinfo`` element (see the examples below), RCS/CVS keywords are
1594 normally stripped from simple (one paragraph) field bodies. For
1595 complete details, please see `RCS Keywords`_ in the
1596 `reStructuredText Markup Specification`_.
1598 .. _RCS Keywords: rst/restructuredtext.html#rcs-keywords
1606 (`%bibliographic.elements;`_)+
1609 The ``docinfo`` element contains only the `common attributes`_:
1610 ids_, names_, dupnames_, source_, and classes_.
1616 Docinfo is represented in reStructuredText_ by a field_list_ in a
1617 bibliographic context: the first non-comment element of a document_,
1618 after any document title_/subtitle_. The field list is transformed
1619 into a ``docinfo`` element and its children by a transform. Source::
1624 :Author: J. Random Hacker
1625 :Contact: jrh@example.com
1627 :Status: Work In Progress
1629 :Filename: $RCSfile$
1630 :Copyright: This document has been placed in the public domain.
1632 Complete pseudo-XML_ result after parsing and applying transforms::
1634 <document ids="docinfo-example" names="docinfo example">
1641 <reference refuri="mailto:jrh@example.com">
1656 This document has been placed in the public domain.
1658 Note that "Filename" is a non-standard ``docinfo`` field, so becomes a
1659 generic ``field`` element. Also note that the "RCSfile" keyword
1660 syntax has been stripped from the "Filename" data.
1662 See field_list_ for an example in a non-bibliographic context. Also
1663 see the individual examples for the various `bibliographic elements`_.
1669 The ``doctest_block`` element is a Python-specific variant of
1670 literal_block_. It is a block of text where line breaks and
1671 whitespace are significant and must be preserved. ``doctest_block``
1672 elements are used for interactive Python interpreter sessions, which
1673 are distinguished by their input prompt: ``>>>``. They are meant to
1674 illustrate usage by example, and provide an elegant and powerful
1675 testing environment via the `doctest module`_ in the Python standard
1679 http://www.python.org/doc/current/lib/module-doctest.html
1686 `Simple Body Elements`_
1689 All elements employing the `%body.elements;`_ or
1690 `%structure.model;`_ parameter entities in their content models
1691 may contain ``doctest_block``.
1694 ``doctest_block`` elements may contain text data plus `inline
1698 ``doctest_block`` is analogous to the HTML "pre" element and to
1699 the DocBook "programlisting" and "screen" elements.
1702 As with literal_block_, ``doctest_block`` elements are typically
1703 rendered in a monospaced typeface. It is crucial that all
1704 whitespace and line breaks are preserved in the rendered form.
1715 The ``doctest_block`` element contains the `common attributes`_
1716 (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_.
1718 :Parameter Entities:
1719 The `%body.elements;`_ parameter entity directly includes
1720 ``doctest_block``. The `%structure.model;`_ parameter entity
1721 indirectly includes ``doctest_block``.
1727 reStructuredText source::
1729 This is an ordinary paragraph.
1731 >>> print 'this is a Doctest block'
1732 this is a Doctest block
1734 Pseudo-XML_ fragment from simple parsing::
1737 This is an ordinary paragraph.
1738 <doctest_block xml:space="preserve">
1739 >>> print 'this is a Doctest block'
1740 this is a Doctest block
1746 The ``document`` element is the root (topmost) element of the Docutils
1747 document tree. ``document`` is the direct or indirect ancestor of
1748 every other element in the tree. It encloses the entire document
1749 tree. It is the starting point for a document.
1756 `Structural Elements`_
1759 The ``document`` element has no parents.
1762 ``document`` elements may contain `structural subelements`_,
1763 `structural elements`_, and `body elements`_.
1766 ``document`` is analogous to the HTML "html" element and to
1767 several DocBook elements such as "book".
1775 ( (title_, subtitle_?)?,
1777 (docinfo_, transition_?)?,
1778 `%structure.model;`_ )
1780 Depending on the source of the data and the stage of processing, the
1781 "document" may not initially contain a "title". A document title is
1782 not directly representable in reStructuredText_. Instead, a lone
1783 top-level section may have its title promoted to become the document
1784 title_, and similarly for a lone second-level (sub)section's title to
1785 become the document subtitle_.
1787 The contents of "decoration_" may be specified in a document,
1788 constructed programmatically, or both. The "docinfo_" may be
1789 transformed from an initial field_list_.
1791 See the `%structure.model;`_ parameter entity for details of the body
1795 The ``document`` element contains the `common attributes`_ (ids_,
1796 names_, dupnames_, source_, and classes_), plus an optional title__
1797 attribute which stores the document title metadata.
1799 __ `title (attribute)`_
1805 reStructuredText_ source::
1812 Complete pseudo-XML_ result from simple parsing::
1815 <section ids="a-title" names="a title">
1821 After applying transforms, the section title is promoted to become the
1824 <document ids="a-title" names="a title">
1846 The ``enumerated_list`` element contains list_item_ elements which are
1847 uniformly marked with enumerator labels.
1854 `Compound Body Elements`_
1857 All elements employing the `%body.elements;`_ or
1858 `%structure.model;`_ parameter entities in their content models
1859 may contain ``enumerated_list``.
1862 ``enumerated_list`` elements contain one or more list_item_
1866 ``enumerated_list`` is analogous to the HTML "ol" element and to
1867 the DocBook "orderedlist" element.
1870 Each list item should begin a new vertical block, prefaced by a
1871 enumeration marker (such as "1.").
1882 The ``enumerated_list`` element contains the `common attributes`_
1883 (ids_, names_, dupnames_, source_, and classes_), plus enumtype_,
1884 prefix_, suffix_, and start_.
1886 ``enumtype`` is used to record the intended enumeration sequence,
1887 one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z),
1888 "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ...,
1889 mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ...,
1892 ``prefix`` stores the formatting characters used before the
1893 enumerator. In documents originating from reStructuredText_ data,
1894 it will contain either "" (empty string) or "(" (left
1895 parenthesis). It may or may not affect processing.
1897 ``suffix`` stores the formatting characters used after the
1898 enumerator. In documents originating from reStructuredText_ data,
1899 it will contain either "." (period) or ")" (right parenthesis).
1900 Depending on the capabilities of the output format, this attribute
1901 may or may not affect processing.
1903 ``start`` contains the ordinal value of the first item in the
1904 list, in decimal. For lists beginning at value 1 ("1", "a", "A",
1905 "i", or "I"), this attribute may be omitted.
1907 :Parameter Entities:
1908 The `%body.elements;`_ parameter entity directly includes
1909 ``enumerated_list``. The `%structure.model;`_ parameter entity
1910 indirectly includes ``enumerated_list``.
1916 reStructuredText_ source::
1926 Pseudo-XML_ fragment from simple parsing::
1928 <enumerated_list enumtype="arabic" prefix="" suffix=".">
1932 <enumerated_list enumtype="upperalpha" prefix="(" suffix=")">
1946 See list_item_ for another example.
1952 The ``error`` element is an admonition, a distinctive and
1953 self-contained notice. Also see the other admonition elements
1954 Docutils offers (in alphabetical order): attention_, caution_,
1955 danger_, hint_, important_, note_, tip_, warning_, and the generic
1963 `Compound Body Elements`_
1966 All elements employing the `%body.elements;`_ or
1967 `%structure.model;`_ parameter entities in their content models
1968 may contain ``error``.
1971 ``error`` elements contain one or more `body elements`_.
1974 ``error`` has no direct analogues in common DTDs. It can be
1975 emulated with primitives and type effects.
1978 Rendered distinctly (inset and/or in a box, etc.), with the
1979 generated title "Error" (or similar).
1987 (`%body.elements;`_)+
1990 The ``error`` element contains only the `common attributes`_: ids_,
1991 names_, dupnames_, source_, and classes_.
1993 :Parameter Entities:
1994 The `%body.elements;`_ parameter entity directly includes
1995 ``error``. The `%structure.model;`_ parameter entity indirectly
2002 reStructuredText source::
2004 .. Error:: Does not compute.
2006 Pseudo-XML_ fragment from simple parsing::
2016 The ``field`` element contains a pair of field_name_ and field_body_
2027 The following elements may contain ``field``: docinfo_,
2031 Each ``field`` element contains one field_name_ and one
2032 field_body_ element.
2035 ``field`` has no direct analogues in common DTDs.
2046 (field_name_, field_body_)
2049 The ``field`` element contains only the `common attributes`_:
2050 ids_, names_, dupnames_, source_, and classes_.
2052 :Parameter Entities:
2053 The `%bibliographic.elements;`_ parameter entity directly includes
2060 See the examples for the field_list_ and docinfo_ elements.
2066 The ``field_body`` element contains body elements. It is analogous to
2067 a database field's data.
2077 Only the field_ element contains ``field_body``.
2080 ``field_body`` elements may contain `body elements`_.
2083 ``field_body`` has no direct analogues in common DTDs.
2094 (`%body.elements;`_)*
2097 The ``field_body`` element contains only the `common attributes`_:
2098 ids_, names_, dupnames_, source_, and classes_.
2104 See the examples for the field_list_ and docinfo_ elements.
2110 The ``field_list`` element contains two-column table-like structures
2111 resembling database records (label & data pairs). Field lists are
2112 often meant for further processing. In reStructuredText_, field lists
2113 are used to represent bibliographic fields (contents of the docinfo_
2114 element) and directive options.
2121 `Compound Body Elements`_
2124 All elements employing the `%body.elements;`_ or
2125 `%structure.model;`_ parameter entities in their content models
2126 may contain ``field_list``.
2129 ``field_list`` elements contain one or more field_ elements.
2132 ``field_list`` has no direct analogues in common DTDs. It can be
2133 emulated with primitives such as tables.
2136 A ``field_list`` is typically rendered as a two-column list, where
2137 the first column contains "labels" (usually with a colon suffix).
2138 However, field lists are often used for extension syntax or
2139 special processing. Such structures do not survive as field lists
2151 The ``field_list`` element contains only the `common attributes`_:
2152 ids_, names_, dupnames_, source_, and classes_.
2154 :Parameter Entities:
2155 The `%body.elements;`_ parameter entity directly includes
2156 ``field_list``. The `%structure.model;`_ parameter entity
2157 indirectly includes ``field_list``.
2163 reStructuredText_ source::
2168 :Parameter i: integer
2170 Pseudo-XML_ fragment from simple parsing::
2202 The ``field_name`` element contains text; it is analogous to a
2203 database field's name.
2210 `Body Subelements`_ (simple)
2213 Only the field_ element contains ``field_name``.
2216 ``field_name`` elements may contain text data plus `inline elements`_.
2219 ``field_name`` has no direct analogues in common DTDs.
2233 The ``field_name`` element contains only the `common attributes`_:
2234 ids_, names_, dupnames_, source_, and classes_.
2240 See the examples for the field_list_ and docinfo_ elements.
2252 The ``footer`` element is a container element whose contents are meant
2253 to appear at the bottom of a web page, or repeated at the bottom of
2254 every printed page. The ``footer`` element may contain processing
2255 information (datestamp, a link to Docutils_, etc.) as well as custom
2263 `Decorative Elements`_
2266 Only the decoration_ element contains ``footer``.
2269 ``footer`` elements may contain `body elements`_.
2272 There are no direct analogies to ``footer`` in HTML or DocBook.
2273 Equivalents are typically constructed from primitives and/or
2274 generated by the processing system.
2282 (`%body.elements;`_)+
2285 The ``footer`` element contains only the `common attributes`_:
2286 ids_, names_, dupnames_, source_, and classes_.
2292 reStructuredText_ source::
2296 Complete pseudo-XML_ result after parsing and applying transforms,
2297 assuming that the datestamp command-line option or configuration
2298 setting has been supplied::
2304 Generated on: 2002-08-20.
2315 ``footnote_reference``
2316 ======================
2324 Docutils wraps ``generated`` elements around text that is inserted
2325 (generated) by Docutils; i.e., text that was not in the document, like
2326 section numbers inserted by the "sectnum" directive.
2334 The ``header`` element is a container element whose contents are meant
2335 to appear at the top of a web page, or at the top of every printed
2343 `Decorative Elements`_
2346 Only the decoration_ element contains ``header``.
2349 ``header`` elements may contain `body elements`_.
2352 There are no direct analogies to ``header`` in HTML or DocBook.
2353 Equivalents are typically constructed from primitives and/or
2354 generated by the processing system.
2362 (`%body.elements;`_)+
2365 The ``header`` element contains only the `common attributes`_:
2366 ids_, names_, dupnames_, source_, and classes_.
2372 reStructuredText source fragment::
2374 .. header:: This space for rent.
2376 Pseudo-XML_ fragment from simple parsing::
2382 This space for rent.
2388 The ``hint`` element is an admonition, a distinctive and
2389 self-contained notice. Also see the other admonition elements
2390 Docutils offers (in alphabetical order): attention_, caution_,
2391 danger_, error_, important_, note_, tip_, warning_, and the generic
2399 `Compound Body Elements`_
2402 All elements employing the `%body.elements;`_ or
2403 `%structure.model;`_ parameter entities in their content models
2404 may contain ``hint``.
2407 ``hint`` elements contain one or more `body elements`_.
2410 ``hint`` has no direct analogues in common DTDs. It can be
2411 emulated with primitives and type effects.
2414 Rendered distinctly (inset and/or in a box, etc.), with the
2415 generated title "Hint" (or similar).
2423 (`%body.elements;`_)+
2426 The ``hint`` element contains only the `common attributes`_: ids_,
2427 names_, dupnames_, source_, and classes_.
2429 :Parameter Entities:
2430 The `%body.elements;`_ parameter entity directly includes
2431 ``hint``. The `%structure.model;`_ parameter entity indirectly
2438 reStructuredText source::
2440 .. Hint:: It's bigger than a bread box.
2442 Pseudo-XML_ fragment from simple parsing::
2446 It's bigger than a bread box.
2458 The ``important`` element is an admonition, a distinctive and
2459 self-contained notice. Also see the other admonition elements
2460 Docutils offers (in alphabetical order): attention_, caution_,
2461 danger_, error_, hint_, note_, tip_, warning_, and the generic
2469 `Compound Body Elements`_
2472 All elements employing the `%body.elements;`_ or
2473 `%structure.model;`_ parameter entities in their content models
2474 may contain ``important``.
2477 ``important`` elements contain one or more `body elements`_.
2480 ``important`` is analogous to the DocBook "important" element.
2483 Rendered distinctly (inset and/or in a box, etc.), with the
2484 generated title "Important" (or similar).
2492 (`%body.elements;`_)+
2495 The ``important`` element contains only the `common attributes`_:
2496 ids_, names_, dupnames_, source_, and classes_.
2498 :Parameter Entities:
2499 The `%body.elements;`_ parameter entity directly includes
2500 ``important``. The `%structure.model;`_ parameter entity
2501 indirectly includes ``important``.
2507 reStructuredText source::
2511 * Wash behind your ears.
2512 * Clean up your room.
2513 * Back up your data.
2516 Pseudo-XML_ fragment from simple parsing::
2522 Wash behind your ears.
2555 The ``line`` element contains a single line of text, part of a
2563 `Body Subelements`_ (simple)
2566 Only the `line_block`_ element contains ``line``.
2569 ``line`` elements may contain text data plus `inline elements`_.
2572 ``line`` has no direct analogues in common DTDs. It can be
2573 emulated with primitives or type effects.
2587 The ``line`` element contains the `common attributes`_ (ids_,
2588 names_, dupnames_, source_, and classes_), plus `xml:space`_.
2600 The ``line_block`` element contains a sequence of lines and nested
2601 line blocks. Line breaks (implied between elements) and leading
2602 whitespace (indicated by nesting) is significant and must be
2603 preserved. ``line_block`` elements are commonly used for verse and
2604 addresses. See `literal_block`_ for an alternative useful for program
2605 listings and interactive computer sessions.
2612 `Compound Body Elements`_
2615 All elements employing the `%body.elements;`_ or
2616 `%structure.model;`_ parameter entities in their content models
2617 may contain ``line_block``.
2620 ``line_block`` elements may contain line_ elements and nested
2621 ``line_block`` elements.
2624 ``line_block`` is analogous to the DocBook "literallayout" element
2625 and to the HTML "pre" element (with modifications to typeface
2629 Unlike ``literal_block``, ``line_block`` elements are typically
2630 rendered in an ordinary text typeface. It is crucial that leading
2631 whitespace and line breaks are preserved in the rendered form.
2639 (line_ | line_block_)+
2642 The ``line_block`` element contains the `common attributes`_ (ids_,
2643 names_, dupnames_, source_, and classes_), plus `xml:space`_.
2645 :Parameter Entities:
2646 The `%body.elements;`_ parameter entity directly includes
2647 ``line_block``. The `%structure.model;`_ parameter entity
2648 indirectly includes ``line_block``.
2654 reStructuredText uses a directive to indicate a ``line_block``.
2657 Take it away, Eric the Orchestra Leader!
2659 | A one, two, a one two three four
2661 | Half a bee, philosophically,
2662 | must, *ipso facto*, half not be.
2663 | But half the bee has got to be,
2664 | *vis a vis* its entity. D'you see?
2666 | But can a bee be said to be
2667 | or not to be an entire bee,
2668 | when half the bee is not a bee,
2669 | due to some ancient injury?
2673 Pseudo-XML_ fragment from simple parsing::
2676 Take it away, Eric the Orchestra Leader!
2679 A one, two, a one two three four
2682 Half a bee, philosophically,
2690 But half the bee has got to be,
2695 its entity. D'you see?
2698 But can a bee be said to be
2701 or not to be an entire bee,
2704 when half the bee is not a bee,
2707 due to some ancient injury?
2716 The ``list_item`` element is a container for the elements of a list
2724 `Body Subelements`_ (compound)
2727 The bullet_list_ and enumerated_list_ elements contain
2731 ``list_item`` elements may contain `body elements`_.
2734 ``list_item`` is analogous to the HTML "li" element and to the
2735 DocBook "listitem" element.
2738 See bullet_list_ or enumerated_list_.
2746 (`%body.elements;`_)*
2749 The ``list_item`` element contains only the `common attributes`_:
2750 ids_, names_, dupnames_, source_, and classes_.
2756 reStructuredText_ source::
2758 1. Outer list, item 1.
2760 * Inner list, item 1.
2761 * Inner list, item 2.
2763 2. Outer list, item 2.
2765 Pseudo-XML_ fragment from simple parsing::
2767 <enumerated_list enumtype="arabic" prefix="" suffix=".">
2771 <bullet_list bullet="*">
2782 See bullet_list_ or enumerated_list_ for further examples.
2794 The ``literal_block`` element contains a block of text where line
2795 breaks and whitespace are significant and must be preserved.
2796 ``literal_block`` elements are commonly used for program listings and
2797 interactive computer sessions. See `line_block`_ for an alternative
2798 useful for verse and addresses.
2805 `Simple Body Elements`_
2808 All elements employing the `%body.elements;`_ or
2809 `%structure.model;`_ parameter entities in their content models
2810 may contain ``literal_block``.
2813 ``literal_block`` elements may contain text data plus `inline
2817 ``literal_block`` is analogous to the HTML "pre" element and to
2818 the DocBook "programlisting" and "screen" elements.
2821 ``literal_block`` elements are typically rendered in a monospaced
2822 typeface. It is crucial that all whitespace and line breaks are
2823 preserved in the rendered form.
2834 The ``literal_block`` element contains the `common attributes`_
2835 (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_.
2837 :Parameter Entities:
2838 The `%body.elements;`_ parameter entity directly includes
2839 ``literal_block``. The `%structure.model;`_ parameter entity
2840 indirectly includes ``literal_block``.
2846 reStructuredText source::
2848 Here is a literal block::
2851 text = 'is left as-is'
2852 spaces_and_linebreaks = 'are preserved'
2853 markup_processing = None
2855 Pseudo-XML_ fragment from simple parsing::
2858 Here is a literal block:
2859 <literal_block xml:space="preserve">
2861 text = 'is left as-is'
2862 spaces_and_linebreaks = 'are preserved'
2863 markup_processing = None
2868 The ``math`` element contains text in `LaTeX math format` that is typeset
2869 as mathematical notation (inline formula).
2871 If the output format does not support math typesetting, the content is
2881 All elements employing the `%inline.elements;`_ parameter entities in
2882 their content models may contain ``math``.
2885 ``math`` elements may contain text data.
2888 ``math`` is analogous to a MathML "math" element or
2889 the LaTeX (``$ math $``) mode.
2892 Rendered as mathematical notation.
2902 The ``math`` element contains the `common attributes`_
2903 (ids_, names_, dupnames_, source_, and classes_).
2909 The ``math_block`` element contains a block of text in `LaTeX math
2910 format` that is typeset as mathematical notation (display formula).
2911 The ``math_block`` element is generated during the initial parse from a
2914 If the output format does not support math typesetting, the content is
2921 `Simple Body Elements`_
2924 All elements employing the `%body.elements;`_ or
2925 `%structure.model;`_ parameter entities in their content models
2926 may contain ``math_block``.
2929 ``math_block`` elements may contain text data.
2932 ``math_block`` is analogous to a LaTeX "equation*" environment or
2933 a MathML "math" element displayed as block-level element.
2936 Rendered in a block as mathematical notation, typically centered or with
2947 The ``math`` element contains the `common attributes`_
2948 (ids_, names_, dupnames_, source_, and classes_).
2954 The ``note`` element is an admonition, a distinctive and
2955 self-contained notice. Also see the other admonition elements
2956 Docutils offers (in alphabetical order): attention_, caution_,
2957 danger_, error_, hint_, important_, tip_, warning_, and the generic
2965 `Compound Body Elements`_
2968 All elements employing the `%body.elements;`_ or
2969 `%structure.model;`_ parameter entities in their content models
2970 may contain ``note``.
2973 ``note`` elements contain one or more `body elements`_.
2976 ``note`` is analogous to the DocBook "note" element.
2979 Rendered distinctly (inset and/or in a box, etc.), with the
2980 generated title "Note" (or similar).
2988 (`%body.elements;`_)+
2991 The ``note`` element contains only the `common attributes`_: ids_,
2992 names_, dupnames_, source_, and classes_.
2994 :Parameter Entities:
2995 The `%body.elements;`_ parameter entity directly includes
2996 ``note``. The `%structure.model;`_ parameter entity indirectly
3003 reStructuredText source::
3005 .. Note:: Admonitions can be handy to break up a
3006 long boring technical document.
3008 Pseudo-XML_ fragment from simple parsing::
3012 Admonitions can be handy to break up a
3013 long boring technical document.
3018 The ``option`` element groups an option string together with zero or
3019 more option argument placeholders. Note that reStructuredText_
3020 currently supports only one argument per option.
3030 Only the option_group_ element contains ``option``.
3033 Each ``option`` element contains one option_string_ and zero or
3034 more option_argument_ elements.
3037 ``option`` has no direct analogues in common DTDs.
3048 (option_string_, option_argument_ \*)
3051 The ``option`` element contains only the `common attributes`_:
3052 ids_, names_, dupnames_, source_, and classes_.
3058 See the examples for the option_list_ element.
3064 The ``option_argument`` element contains placeholder text for option
3075 Only the option_ element contains ``option_argument``.
3078 ``option_argument`` elements contain text data only.
3081 ``option_argument`` has no direct analogues in common DTDs.
3084 The value of the "delimiter" attribute is prefixed to the
3085 ``option_argument``, separating it from its option_string_ or a
3086 preceding ``option_argument``. The ``option_argument`` text is
3087 typically rendered in a monospaced typeface, possibly italicized
3088 or otherwise altered to indicate its placeholder nature.
3099 The ``option_argument`` element contains the `common attributes`_ (ids_,
3100 names_, dupnames_, source_, and classes_), plus delimiter_.
3102 ``delimiter`` contains the text preceding the ``option_argument``:
3103 either the text separating it from the option_string_ (typically
3104 either "=" or " ") or the text between option arguments (typically
3111 See the examples for the option_list_ element.
3117 The ``option_group`` element groups together one or more option_
3118 elements, all synonyms.
3128 Only the option_list_item_ element contains ``option_group``.
3131 ``option_group`` elements contain one or more option_ elements.
3133 ``option_group`` is an empty element and has no children.
3135 Each ``option_group`` element contains one _ and
3139 ``option_group`` has no direct analogues in common DTDs.
3142 Typically option_ elements within an ``option_group`` are joined
3143 together in a comma-separated list.
3151 (option_group_, description_)
3154 The ``option_group`` element contains only the `common attributes`_:
3155 ids_, names_, dupnames_, source_, and classes_.
3161 See the examples for the option_list_ element.
3167 Each ``option_list`` element contains a two-column list of
3168 command-line options and descriptions, documenting a program's
3176 `Compound Body Elements`_
3179 All elements employing the `%body.elements;`_ or
3180 `%structure.model;`_ parameter entities in their content models
3181 may contain ``option_list``.
3184 ``option_list`` elements contain one or more option_list_item_
3188 ``option_list`` has no direct analogues in common DTDs. It can be
3189 emulated with primitives such as tables.
3192 An ``option_list`` is typically rendered as a two-column list,
3193 where the first column contains option strings and arguments, and
3194 the second column contains descriptions.
3202 (option_list_item_ +)
3205 The ``option_list`` element contains only the `common attributes`_:
3206 ids_, names_, dupnames_, source_, and classes_.
3208 :Parameter Entities:
3209 The `%body.elements;`_ parameter entity directly includes
3210 ``option_list``. The `%structure.model;`_ parameter entity
3211 indirectly includes ``option_list``.
3217 reStructuredText_ source::
3219 -a command-line option "a"
3220 -1 file, --one=file, --two file
3221 Multiple options with arguments.
3223 Pseudo-XML_ fragment from simple parsing::
3233 command-line option "a"
3239 <option_argument delimiter=" ">
3244 <option_argument delimiter="=">
3249 <option_argument delimiter=" ">
3253 Multiple options with arguments.
3256 ``option_list_item``
3257 ====================
3259 The ``option_list_item`` element is a container for a pair of
3260 option_group_ and description_ elements.
3270 Only the option_list_ element contains ``option_list_item``.
3273 Each ``option_list_item`` element contains one option_group_ and
3274 one description_ element.
3277 ``option_list_item`` has no direct analogues in common DTDs.
3288 (option_group_, description_)
3291 The ``option_list_item`` element contains only the `common attributes`_:
3292 ids_, names_, dupnames_, source_, and classes_.
3298 See the examples for the option_list_ element.
3304 The ``option_string`` element contains the text of a command-line
3315 Only the option_ element contains ``option_string``.
3318 ``option_string`` elements contain text data only.
3321 ``option_string`` has no direct analogues in common DTDs.
3324 The ``option_string`` text is typically rendered in a monospaced
3336 The ``option_string`` element contains only the `common attributes`_:
3337 ids_, names_, dupnames_, source_, and classes_.
3343 See the examples for the option_list_ element.
3349 The ``organization`` element contains the name of document author's
3350 organization, or the organization responsible for the document.
3357 `Bibliographic Elements`_
3360 Only the docinfo_ element contains ``organization``.
3363 ``organization`` elements may contain text data plus `inline
3367 ``organization`` is analogous to the DocBook "orgname",
3368 "corpname", or "publishername" elements.
3382 The ``organization`` element contains only the `common attributes`_:
3383 ids_, names_, dupnames_, source_, and classes_.
3385 :Parameter Entities:
3386 The `%bibliographic.elements;`_ parameter entity directly includes
3393 reStructuredText_ source::
3398 :Organization: Humankind
3400 Complete pseudo-XML_ result after parsing and applying transforms::
3402 <document ids="document-title" names="document title">
3409 See docinfo_ for a more complete example, including processing
3416 The ``paragraph`` element contains the text and inline elements of a
3417 single paragraph, a fundamental building block of documents.
3424 `Simple Body Elements`_
3427 All elements employing the `%body.elements;`_ or
3428 `%structure.model;`_ parameter entities in their content models
3429 may contain ``paragraph``.
3432 ``paragraph`` elements may contain text data plus `inline
3436 ``paragraph`` is analogous to the HTML "p" element and to the
3437 DocBook "para" elements.
3448 The ``paragraph`` element contains only the `common attributes`_:
3449 ids_, names_, dupnames_, source_, and classes_.
3451 :Parameter Entities:
3452 The `%body.elements;`_ parameter entity directly includes
3453 ``paragraph``. The `%structure.model;`_ parameter entity
3454 indirectly includes ``paragraph``.
3460 reStructuredText_ source::
3464 Pseudo-XML_ fragment from simple parsing::
3497 The ``revision`` element contains the revision number of the document.
3498 It can be used alone or in conjunction with version_.
3505 `Bibliographic Elements`_
3508 Only the docinfo_ element contains ``revision``.
3511 ``revision`` elements may contain text data plus `inline
3515 ``revision`` is analogous to but simpler than the DocBook
3516 "revision" element. It closely matches the DocBook "revnumber"
3517 element, but in a simpler context.
3520 Often used with the RCS/CVS keyword "Revision". See docinfo_.
3531 The ``revision`` element contains only the `common attributes`_:
3532 ids_, names_, dupnames_, source_, and classes_.
3534 :Parameter Entities:
3535 The `%bibliographic.elements;`_ parameter entity directly includes
3542 reStructuredText_ source::
3550 Complete pseudo-XML_ result after parsing and applying transforms::
3552 <document ids="document-title" names="document title">
3561 See docinfo_ for a more complete example, including processing
3574 rubric n. 1. a title, heading, or the like, in a manuscript,
3575 book, statute, etc., written or printed in red or otherwise
3576 distinguished from the rest of the text. ...
3578 -- Random House Webster's College Dictionary, 1991
3580 A rubric is like an informal heading that doesn't correspond to the
3581 document's structure.
3589 The ``section`` element is the main unit of hierarchy for Docutils
3590 documents. Docutils ``section`` elements are a recursive structure; a
3591 ``section`` may contain other ``section`` elements, without limit.
3592 Paragraphs and other body elements may occur before a ``section``, but
3600 `Structural Elements`_
3603 The following elements may contain ``section``: document_,
3607 ``section`` elements begin with a title_, and may contain `body
3608 elements`_ as well as transition_, topic_, and sidebar_ elements.
3611 ``section`` is analogous to DocBook recursive "section" elements,
3612 and to HTML "div" elements combined with "h1" etc. title elements.
3621 `%structure.model;`_)
3623 See the `%structure.model;`_ parameter entity for details of the body
3627 The ``section`` element contains only the `common attributes`_:
3628 ids_, names_, dupnames_, source_, and classes_.
3630 :Parameter Entities:
3631 The `%section.elements;`_ parameter entity directly includes
3632 ``section``. The `%structure.model;`_ parameter entity indirectly
3633 includes ``section``.
3639 reStructuredText_ source::
3657 Complete pseudo-XML_ result after parsing::
3660 <section ids="title-1" names="title 1">
3665 <section ids="title-2" names="title 2">
3670 <section ids="title-3" names="title 3">
3675 <section ids="title-4" names="title 4">
3685 Sidebars are like miniature, parallel documents that occur inside
3686 other documents, providing related or reference material. A
3687 ``sidebar`` is typically offset by a border and "floats" to the side
3688 of the page; the document's main text may flow around it. Sidebars
3689 can also be likened to super-footnotes; their content is outside of
3690 the flow of the document's main text.
3692 The ``sidebar`` element is a nonrecursive section_-like construct
3693 which may occur at the top level of a section_ wherever a body element
3694 (list, table, etc.) is allowed. In other words, ``sidebar`` elements
3695 cannot nest inside body elements, so you can't have a ``sidebar``
3696 inside a ``table`` or a ``list``, or inside another ``sidebar`` (or
3704 `Structural Elements`_
3707 The following elements may contain ``sidebar``: document_,
3711 ``sidebar`` elements begin with a title_ and an optional subtitle_
3712 and contain `body elements`_ and topic_ elements.
3715 ``sidebar`` is analogous to the DocBook "sidebar" element.
3718 A ``sidebar`` element should be set off from the rest of the
3719 document somehow, typically with a border. Sidebars typically
3720 "float" to the side of the page and the document's main text flows
3729 (title_, subtitle_?,
3730 (`%body.elements;`_ | topic_)+)
3733 The ``sidebar`` element contains only the `common attributes`_:
3734 ids_, names_, dupnames_, source_, and classes_.
3736 :Parameter Entities:
3737 The `%structure.model;`_ parameter entity directly includes
3744 The `"sidebar" directive`_ is used to create a ``sidebar`` element.
3745 reStructuredText_ source::
3748 :subtitle: If Desired
3752 Pseudo-XML_ fragment from simple parsing::
3762 .. _"sidebar" directive: rst/directives.html#sidebar
3768 The ``status`` element contains a status statement for the document,
3769 such as "Draft", "Final", "Work In Progress", etc.
3776 `Bibliographic Elements`_
3779 Only the docinfo_ element contains ``status``.
3782 ``status`` elements may contain text data plus `inline elements`_.
3785 ``status`` is analogous to the DocBook "status" element.
3799 The ``status`` element contains only the `common attributes`_:
3800 ids_, names_, dupnames_, source_, and classes_.
3802 :Parameter Entities:
3803 The `%bibliographic.elements;`_ parameter entity directly includes
3810 reStructuredText_ source::
3815 :Status: Work In Progress
3817 Complete pseudo-XML_ result after parsing and applying transforms::
3819 <document ids="document-title" names="document title">
3826 See docinfo_ for a more complete example, including processing
3842 ``substitution_definition``
3843 ===========================
3848 ``substitution_reference``
3849 ==========================
3857 The ``subtitle`` element stores the subtitle of a document_.
3864 `Structural Subelements`_
3867 The document_ and sidebar_ elements may contain ``subtitle``.
3870 ``subtitle`` elements may contain text data plus `inline
3874 ``subtitle`` is analogous to HTML header elements ("h2" etc.) and
3875 to the DocBook "subtitle" element.
3878 A document's subtitle is usually rendered smaller than its title_.
3889 The ``subtitle`` element contains only the `common attributes`_:
3890 ids_, names_, dupnames_, source_, and classes_.
3896 reStructuredText_ source::
3907 Complete pseudo-XML_ result after parsing and applying transforms::
3909 <document ids="title" names="title">
3912 <subtitle ids="subtitle" names="subtitle">
3917 Note how two section levels have collapsed, promoting their titles to
3918 become the document's title and subtitle. Since there is only one
3919 structural element (document), the subsection's ``ids`` and ``names``
3920 attributes are stored in the ``subtitle`` element.
3956 The ``term`` element contains a word or phrase being defined in a
3964 `Body Subelements`_ (simple)
3967 Only the definition_list_item_ element contains ``term``.
3970 ``term`` elements may contain text data plus `inline elements`_.
3973 ``term`` is analogous to the HTML "dt" element and to the DocBook
3977 See definition_list_item_.
3988 The ``term`` element contains only the `common attributes`_:
3989 ids_, names_, dupnames_, source_, and classes_.
3995 See the examples for the definition_list_, definition_list_item_, and
3996 classifier_ elements.
4014 The ``tip`` element is an admonition, a distinctive and self-contained
4015 notice. Also see the other admonition elements Docutils offers (in
4016 alphabetical order): attention_, caution_, danger_, error_, hint_,
4017 important_, note_, warning_, and the generic admonition_.
4024 `Compound Body Elements`_
4027 All elements employing the `%body.elements;`_ or
4028 `%structure.model;`_ parameter entities in their content models
4029 may contain ``tip``.
4032 ``tip`` elements contain one or more `body elements`_.
4035 ``tip`` is analogous to the DocBook "tip" element.
4038 Rendered distinctly (inset and/or in a box, etc.), with the
4039 generated title "Tip" (or similar).
4047 (`%body.elements;`_)+
4050 The ``tip`` element contains only the `common attributes`_: ids_,
4051 names_, dupnames_, source_, and classes_.
4053 :Parameter Entities:
4054 The `%body.elements;`_ parameter entity directly includes ``tip``.
4055 The `%structure.model;`_ parameter entity indirectly includes
4062 reStructuredText source::
4064 .. Tip:: 15% if the service is good.
4066 Pseudo-XML_ fragment from simple parsing::
4070 15% if the service is good.
4078 The ``title`` element stores the title of a document_, section_,
4079 topic_, sidebar_, or generic admonition_.
4086 `Structural Subelements`_
4089 The following elements may contain ``title``: document_, section_,
4090 topic_, sidebar_, admonition_
4093 ``title`` elements may contain text data plus `inline elements`_.
4096 ``title`` is analogous to HTML "title" and header ("h1" etc.)
4097 elements, and to the DocBook "title" element.
4108 The ``title`` element contains the `common attributes`_ (ids_,
4109 names_, dupnames_, source_, and classes_), plus refid_ and auto_.
4111 ``refid`` is used as a backlink to a table of contents entry.
4113 ``auto`` is used to indicate (with value "1") that the ``title``
4114 has been numbered automatically.
4120 reStructuredText_ source::
4127 Pseudo-XML_ fragment from simple parsing::
4129 <section ids="a-title" names="a title">
4145 The ``topic`` element is a nonrecursive section_-like construct which
4146 may occur at the top level of a section_ wherever a body element
4147 (list, table, etc.) is allowed. In other words, ``topic`` elements
4148 cannot nest inside body elements, so you can't have a ``topic`` inside
4149 a ``table`` or a ``list``, or inside another ``topic``.
4156 `Structural Elements`_
4159 The following elements may contain ``topic``: document_, section_,
4163 ``topic`` elements begin with a title_ and may contain `body
4167 ``topic`` is analogous to the DocBook "simplesect" element.
4170 A ``topic`` element should be set off from the rest of the
4171 document somehow, such as with indentation or a border.
4180 (`%body.elements;`_)+)
4183 The ``topic`` element contains only the `common attributes`_:
4184 ids_, names_, dupnames_, source_, and classes_.
4186 :Parameter Entities:
4187 The `%structure.model;`_ parameter entity directly includes
4194 The `"topic" directive`_ is used to create a ``topic`` element.
4195 reStructuredText_ source::
4201 Pseudo-XML_ fragment from simple parsing::
4209 .. _"topic" directive: rst/directives.html#topic
4215 The ``transition`` element is commonly seen in novels and short
4216 fiction, as a gap spanning one or more lines, with or without a type
4217 ornament such as a row of asterisks. Transitions separate body
4218 elements and sections, dividing a section into untitled divisions. A
4219 transition may not begin or end a section [#]_ or document, nor may
4220 two transitions be immediately adjacent.
4222 See `Doctree Representation of Transitions`__ in `A Record of
4223 reStructuredText Syntax Alternatives`__.
4225 .. [#] In reStructuredText markup, a transition may appear to fall at
4226 the end of a section immediately before another section. A
4227 transform recognizes this case and moves the transition so it
4228 separates the sections.
4230 __ ../dev/rst/alternatives.html#doctree-representation-of-transitions
4231 __ ../dev/rst/alternatives.html
4238 `Structural Subelements`_
4241 The following elements may contain ``transition``: document_,
4245 ``transition`` is an empty element and has no children.
4248 ``transition`` is analogous to the HTML "hr" element.
4251 The ``transition`` element is typically rendered as vertical
4252 whitespace (more than that separating paragraphs), with or without
4253 a horizontal line or row of asterisks. In novels, transitions are
4254 often represented as a row of three well-spaced asterisks with
4255 vertical space above and below.
4265 The ``transition`` element has no content; it is a "point element".
4268 The ``transition`` element contains only the `common attributes`_:
4269 ids_, names_, dupnames_, source_, and classes_.
4271 :Parameter Entities:
4272 The `%structure.model;`_ parameter entity directly includes
4279 reStructuredText_ source::
4287 Complete pseudo-XML_ result after parsing::
4300 The ``version`` element contains the version number of the document.
4301 It can be used alone or in conjunction with revision_.
4308 `Bibliographic Elements`_
4311 Only the docinfo_ element contains ``version``.
4314 ``version`` elements may contain text data plus `inline
4318 ``version`` may be considered analogous to the DocBook "revision",
4319 "revnumber", or "biblioid" elements.
4322 Sometimes used with the RCS/CVS keyword "Revision". See docinfo_
4334 The ``version`` element contains only the `common attributes`_:
4335 ids_, names_, dupnames_, source_, and classes_.
4337 :Parameter Entities:
4338 The `%bibliographic.elements;`_ parameter entity directly includes
4345 reStructuredText_ source::
4352 Complete pseudo-XML_ result after parsing and applying transforms::
4354 <document ids="document-title" names="document title">
4361 See docinfo_ for a more complete example, including processing
4368 The ``warning`` element is an admonition, a distinctive and
4369 self-contained notice. Also see the other admonition elements
4370 Docutils offers (in alphabetical order): attention_, caution_,
4371 danger_, error_, hint_, important_, note_, tip_.
4378 `Compound Body Elements`_
4381 All elements employing the `%body.elements;`_ or
4382 `%structure.model;`_ parameter entities in their content models
4383 may contain ``warning``.
4386 ``warning`` elements contain one or more `body elements`_.
4389 ``warning`` is analogous to the DocBook "warning" element.
4392 Rendered distinctly (inset and/or in a box, etc.), with the
4393 generated title "Warning" (or similar).
4401 (`%body.elements;`_)+
4404 The ``warning`` element contains only the `common attributes`_:
4405 ids_, names_, dupnames_, source_, and classes_.
4407 :Parameter Entities:
4408 The `%body.elements;`_ parameter entity directly includes
4409 ``warning``. The `%structure.model;`_ parameter entity indirectly
4410 includes ``warning``.
4416 reStructuredText source::
4418 .. WARNING:: Reader discretion is strongly advised.
4420 Pseudo-XML_ fragment from simple parsing::
4424 Reader discretion is strongly advised.
4427 ---------------------
4429 ---------------------
4431 .. contents:: :local:
4434 _`Common Attributes`: Through the `%basic.atts;`_ parameter entity,
4435 all elements contain the following attributes: ids_, names_, dupnames_,
4436 source_, and classes_.
4443 Character data. ``CDATA`` attributes may contain arbitrary text.
4446 Like a ``NMTOKEN``, but it must begin with a letter (a "name
4447 production"). Identical ``ID`` values must not appear more than
4448 once in a document; i.e., ID values must uniquely identify their
4452 A reference to an ``ID`` value (a name production) of another
4456 One or more space-separated ``ID`` references (name productions).
4459 A "name token". One or more of letters, digits, ".", "-", and
4463 One or more space-separated ``NMTOKEN`` names.
4466 No if zero ("0"), yes if any other value. This is a parameter
4467 entity which resolves to a ``NMTOKEN`` attribute type.
4470 This emphasizes that the attribute value must be a number. This
4471 is a parameter entity which resolves to a ``NMTOKEN`` attribute
4475 The attribute value may be one of a specified list of values.
4481 `Attribute type`_: ``%yesorno;``. Default value: none (implies no).
4483 The ``anonymous`` attribute is used for unnamed hyperlinks in the
4484 target_ and reference_ elements (via the `%anonymous.att;`_ parameter
4491 `Attribute type`_: ``CDATA``. Default value: none.
4493 The ``auto`` attribute is used to indicate automatically-numbered
4494 footnote_, footnote_reference_ and title_ elements (via the
4495 `%auto.att;`_ parameter entity).
4501 `Attribute type`_: ``IDREFS``. Default value: none.
4503 The ``backrefs`` attribute contains a space-separated list of ids_
4504 references, used for backlinks from footnote_, citation_, and
4505 system_message_ elements (via the `%backrefs.att;`_ parameter entity).
4511 `Attribute type`_: ``CDATA``. Default value: none.
4513 The ``bullet`` attribute is used in the bullet_list_ element.
4519 `Attribute type`_: ``NMTOKENS``. Default value: none.
4521 The ``classes`` attribute is a list containing zero or more names used
4522 to classify an element. The names are converted to conform to the
4523 regular expression ``[a-z](-?[a-z0-9]+)*`` (see the `"class"
4524 directive`_ description for details and rationale_).
4526 The purpose of the attribute is to indicate
4527 an "is-a" variant relationship, to allow an extensible way of defining
4528 sub-classes of existing elements. It can be used to carry context
4529 forward between a Docutils Reader and Writer, when a custom structure
4530 is reduced to a standardized document tree. One common use is in
4531 conjunction with stylesheets, to add selection criteria. It should
4532 not be used to carry formatting instructions or arbitrary content.
4534 The ``classes`` attribute's contents should be ignorable. Writers that
4535 are not familiar with the variant expressed should be able to ignore
4538 ``classes`` is one of the `common attributes`_, shared by all Docutils
4541 .. _"class" directive: rst/directives.html#class
4542 .. _rationale: rst/directives.html#rationale
4547 `Attribute type`_: ``CDATA``. Default value: none.
4549 The ``delimiter`` attribute is used in the option_argument_ element.
4555 `Attribute type`_: ``CDATA``. Default value: none.
4557 The ``dupnames`` attribute is a list containing the names of an
4558 element when there has been a naming conflict. The contents of the
4559 ``dupnames`` attribute would have been transferred from the `names`_
4560 attribute. An element may have at most one of the ``names`` or
4561 ``dupnames`` attributes, but not both. ``dupnames`` is one of the
4562 `common attributes`_, shared by all Docutils elements.
4568 `Attribute type`_: enumeration, one of "arabic", "loweralpha",
4569 "upperalpha", "lowerroman", or "upperroman". Default value: none.
4571 The ``enumtype`` attribute is used in the enumerated_list_ element.
4577 `Attribute type`_: ``NMTOKENS``. Default value: none.
4579 The ``ids`` attribute is a list containing one or more unique
4580 identifier keys. ``ids`` is one of the `common attributes`_, shared
4581 by all Docutils elements.
4587 `Attribute type`_: ``CDATA``. Default value: none.
4589 The ``names`` attribute is a list containing the names of an element,
4590 typically originating from the element's title or content. Each name
4591 in ``names`` must be unique; if there are name conflicts (two or more
4592 elements want to the same name), the contents will be transferred to
4593 the `dupnames`_ attribute on the duplicate elements. An element may
4594 have at most one of the ``names`` or ``dupnames`` attributes, but not
4595 both. ``names`` is one of the `common attributes`_, shared by all
4602 `Attribute type`_: ``CDATA``. Default value: none.
4604 The ``prefix`` attribute is used in the enumerated_list_ element.
4610 `Attribute type`_: ``IDREF``. Default value: none.
4612 The ``refid`` attribute contains references to `ids`_ attributes in
4613 other elements. It is used by the target_, reference_,
4614 footnote_reference_, citation_reference_, title_ and problematic_
4615 elements (via the `%refid.att;`_ and `%reference.atts;`_ parameter
4622 `Attribute type`_: ``NMTOKENS``. Default value: none.
4624 The ``refname`` attribute contains an internal reference to the
4625 `names`_ attribute of another element. On a `target`_ element,
4626 ``refname`` indicates an indirect target which may resolve to either
4627 an internal or external reference. ``refname`` is used by the
4628 target_, reference_, footnote_reference_, citation_reference_, and
4629 substitution_reference_ elements (via the `%refname.att;`_ and
4630 `%reference.atts;`_ parameter entities).
4636 `Attribute type`_: ``CDATA``. Default value: none.
4638 The ``refuri`` attribute contains an external reference to a URI/URL.
4639 It is used by the target_, reference_, footnote_reference_, and
4640 citation_reference_ elements (via the `%reference.atts;`_ parameter
4647 `Attribute type`_: ``CDATA``. Default value: none.
4649 The ``source`` attribute is used to store the path or URL to the
4650 source text that was used to produce the document tree. It is one of
4651 the `common attributes`_, shared by all Docutils elements.
4657 `Attribute type`_: ``%number;``. Default value: none.
4659 The ``start`` attribute is used in the enumerated_list_ element.
4665 `Attribute type`_: ``CDATA``. Default value: none.
4667 The ``suffix`` attribute is used in the enumerated_list_ element.
4673 `Attribute type`_: one of "default" or "preserve". Default value:
4676 The ``xml:space`` attribute is a standard XML attribute for
4677 whitespace-preserving elements. It is used by the literal_block_,
4678 line_block_, doctest_block_, comment_, and raw_ elements (via the
4679 `%fixedspace.att;`_ parameter entity). It is a fixed attribute, meant
4680 to communicate to an XML parser that the element contains significant
4681 whitespace. The attribute value should not be set in a document
4685 .. _title (attribute):
4690 `Attribute type`_: ``CDATA``. Default value: none.
4692 The ``title`` attribute stores the title metadata of a document. This
4693 title is typically not part of the rendered document. It may for
4694 example be used in HTML's ``title`` element.
4697 ----------------------------
4698 Parameter Entity Reference
4699 ----------------------------
4701 .. contents:: :local:
4704 Parameter entities are used to simplify the DTD (to share definitions
4705 and reduce duplication) and to allow the DTD to be customized by
4706 wrapper DTDs (external client DTDs that use or import the Docutils
4707 DTD). Parameter entities may be overridden by wrapper DTDs, replacing
4708 the definitions below with custom definitions. Parameter entities
4709 whose names begin with "additional" are meant to allow easy extension
4716 The ``%anonymous.att;`` parameter entity contains the anonymous_
4717 attribute, used for unnamed hyperlinks.
4723 anonymous_ %yesorno; #IMPLIED
4725 The reference_ and target_ elements directly employ the
4726 ``%anonymous.att;`` parameter entity in their attribute lists.
4732 The ``%auto.att;`` parameter entity contains the auto_ attribute, used
4733 to indicate an automatically-numbered footnote or title.
4739 auto_ CDATA #IMPLIED
4741 The footnote_, footnote_reference_, and title_ elements directly
4742 employ the ``%auto.att;`` parameter entity in their attribute lists.
4748 The ``%backrefs.att;`` parameter entity contains the backrefs_
4749 attribute, a space-separated list of id references, for backlinks.
4755 backrefs_ IDREFS #IMPLIED
4757 The citation_, footnote_, and system_message_ elements directly employ
4758 the ``%backrefs.att;`` parameter entity in their attribute lists.
4764 The ``%basic.atts;`` parameter entity lists attributes common to all
4765 Docutils elements. See `Common Attributes`_.
4771 ids_ NMTOKENS #IMPLIED
4772 names_ CDATA #IMPLIED
4773 dupnames_ CDATA #IMPLIED
4774 source_ CDATA #IMPLIED
4775 classes_ NMTOKENS #IMPLIED
4776 %additional.basic.atts;
4778 The ``%additional.basic.atts;`` parameter entity can be used by
4779 wrapper DTDs to extend ``%basic.atts;``.
4782 ``%bibliographic.elements;``
4783 ============================
4785 The ``%bibliographic.elements;`` parameter entity contains an OR-list of all
4786 `bibliographic elements`_.
4792 author_ | authors_ | organization_ | contact_ | address_
4793 | version_ | revision_ | status_ | date_ | copyright_
4795 %additional.bibliographic.elements;
4797 The ``%additional.bibliographic.elements;`` parameter entity can be used by
4798 wrapper DTDs to extend ``%bibliographic.elements;``.
4800 Only the docinfo_ element directly employs the
4801 ``%bibliographic.elements;`` parameter entity in its content model.
4807 The ``%body.elements;`` parameter entity contains an OR-list of all
4808 `body elements`_. ``%body.elements;`` is itself contained within the
4809 `%structure.model;`_ parameter entity.
4815 admonition_ | attention_ | block_quote_ | bullet_list_ | caution_
4816 | citation_ | compound_ | comment_ | container_ | danger_ |
4817 definition_list_ | doctest_block_ | enumerated_list_ | error_ |
4818 field_list_ | figure_ | footnote_ | hint_ | image_ | important_
4819 | line_block_ | literal_block_ | note_ | option_list_ |
4820 paragraph_ | pending_ | raw_ reference_ | rubric_ |
4821 substitution_definition_ | system_message_ | table_ | target_ |
4822 tip_ | warning_ %additional.body.elements;
4824 The ``%additional.body.elements;`` parameter entity can be used by
4825 wrapper DTDs to extend ``%body.elements;``.
4827 The ``%body.elements;`` parameter entity is directly employed in the
4828 content models of the following elements: admonition_, attention_,
4829 block_quote_, caution_, citation_, compound_, danger_, definition_,
4830 description_, entry_, error_, field_body_, footer_, footnote_,
4831 header_, hint_, important_, legend_, list_item_, note_, sidebar_,
4832 system_message_, tip_, topic_, warning_
4834 Via `%structure.model;`_, the ``%body.elements;`` parameter entity is
4835 indirectly employed in the content models of the document_ and
4839 ``%fixedspace.att;``
4840 ====================
4842 The ``%fixedspace.att;`` parameter entity contains the `xml:space`_
4843 attribute, a standard XML attribute for whitespace-preserving
4850 `xml:space`_ (default | preserve) #FIXED 'preserve'
4852 The ``%fixedspace.att;`` parameter entity is directly employed in the
4853 attribute lists of the following elements: address_, comment_,
4854 doctest_block_, line_block_, literal_block_, raw_
4857 ``%inline.elements;``
4858 =====================
4860 The ``%inline.elements;`` parameter entity contains an OR-list of all
4867 abbreviation_ | acronym_ | citation_reference_ | emphasis_ |
4868 footnote_reference_ | generated_ | image_ | inline_ | literal_ |
4869 problematic_ | raw_ | reference_ | strong_ | substitution_reference_ |
4870 subscript_ | superscript_ | target_ | title_reference_
4871 %additional.inline.elements;
4873 The ``%additional.inline.elements;`` parameter entity can be used by
4874 wrapper DTDs to extend ``%inline.elements;``.
4876 Via `%text.model;`_, the ``%inline.elements;`` parameter entity is
4877 indirectly employed in the content models of the following elements:
4878 abbreviation_, acronym_, address_, attribution_, author_, caption_,
4879 classifier_, contact_, copyright_, date_, doctest_block_, emphasis_,
4880 generated_, inline_, line_block_, literal_block_, math_, math_block_,
4882 paragraph_, problematic_, raw_, reference_, revision_, rubric_,
4883 status_, strong_, subscript_, substitution_definition_,
4884 substitution_reference_, subtitle_, superscript_, target_, term_,
4885 title_, title_reference_, version_
4888 ``%reference.atts;``
4889 ====================
4891 The ``%reference.atts;`` parameter entity groups together the refuri_,
4892 refid_, and refname_ attributes.
4901 %additional.reference.atts;
4903 The ``%additional.reference.atts;`` parameter entity can be used by
4904 wrapper DTDs to extend ``%additional.reference.atts;``.
4906 The citation_reference_, footnote_reference_, reference_, and target_
4907 elements directly employ the ``%reference.att;`` parameter entity in
4908 their attribute lists.
4914 The ``%refid.att;`` parameter entity contains the refid_ attribute, an
4915 internal reference to the `ids`_ attribute of another element.
4921 refid_ CDATA #IMPLIED
4923 The title_ and problematic_ elements directly employ the
4924 ``%refid.att;`` parameter entity in their attribute lists.
4926 Via `%reference.atts;`_, the ``%refid.att;`` parameter entity is
4927 indirectly employed in the attribute lists of the citation_reference_,
4928 footnote_reference_, reference_, and target_ elements.
4934 The ``%refname.att;`` parameter entity contains the refname_
4935 attribute, an internal reference to the `names`_ attribute of another
4936 element. On a `target`_ element, ``refname`` indicates an indirect
4937 target which may resolve to either an internal or external
4944 refname_ NMTOKENS #IMPLIED
4946 The substitution_reference_ element directly employs the
4947 ``%refname.att;`` parameter entity in its attribute list.
4949 Via `%reference.atts;`_, the ``%refname.att;`` parameter entity is
4950 indirectly employed in the attribute lists of the citation_reference_,
4951 footnote_reference_, reference_, and target_ elements.
4957 The ``%refuri.att;`` parameter entity contains the refuri_ attribute,
4958 an external reference to a URI/URL.
4964 refuri_ CDATA #IMPLIED
4966 Via `%reference.atts;`_, the ``%refuri.att;`` parameter entity is
4967 indirectly employed in the attribute lists of the citation_reference_,
4968 footnote_reference_, reference_, and target_ elements.
4971 ``%section.elements;``
4972 ======================
4974 The ``%section.elements;`` parameter entity contains an OR-list of all
4975 section_-equivalent elements. ``%section.elements;`` is itself
4976 contained within the `%structure.model;`_ parameter entity.
4983 %additional.section.elements;
4985 The ``%additional.section.elements;`` parameter entity can be used
4986 by wrapper DTDs to extend ``%section.elements;``.
4988 Via `%structure.model;`_, the ``%section.elements;`` parameter entity
4989 is indirectly employed in the content models of the document_ and
4993 ``%structure.model;``
4994 =====================
4996 The ``%structure.model;`` parameter entity encapsulates the
4997 hierarchical structure of a document and of its constituent parts.
4998 See the discussion of the `element hierarchy`_ above.
5004 ( ( (`%body.elements;`_ | topic_ | sidebar_)+, transition_? )*,
5005 ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? )
5007 Each document_ or section_ contains zero or more body elements,
5008 topics, and/or sidebars, optionally interspersed with single
5009 transitions, followed by zero or more sections (whose contents are
5010 recursively the same as this model) optionally interspersed with
5013 The following restrictions are imposed by this model:
5015 * Transitions must be separated by other elements (body elements,
5016 sections, etc.). In other words, a transition may not be
5017 immediately adjacent to another transition.
5019 * A transition may not occur at the beginning of a document or
5022 An additional restriction, which cannot be expressed in the language
5023 of DTDs, is imposed by software:
5025 * A transition may not occur at the end of a document or section.
5027 The `%structure.model;`_ parameter entity is directly employed in the
5028 content models of the document_ and section_ elements.
5034 The ``%text.model;`` parameter entity is used by many elements to
5035 represent text data mixed with `inline elements`_.
5041 (#PCDATA | `%inline.elements;`_)*
5043 The ``%text.model;`` parameter entity is directly employed in the
5044 content models of the following elements: abbreviation_, acronym_,
5045 address_, author_, caption_, classifier_, contact_, copyright_, date_,
5046 doctest_block_, emphasis_, field_name_, generated_, line_block_,
5047 literal_block_, organization_, paragraph_, problematic_, raw_,
5048 reference_, revision_, status_, strong_, substitution_definition_,
5049 substitution_reference_, subtitle_, target_, term_, title_, version_
5056 indent-tabs-mode: nil
5057 sentence-end-double-space: t