1 ============================
2 The Docutils Document Tree
3 ============================
5 A Guide to the Docutils DTD
6 ***************************
9 :Contact: docutils-develop@lists.sourceforge.net
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
294 The ``abbreviation`` element is an inline element used to represent an
295 abbreviation being used in the document. An example of an abbreviation is 'St'
296 being used instead of 'Street'.
305 All elements employing the %inline.elements; parameter entities in their
306 content models may contain ``abbreviation``.
309 ``abbreviation`` elements may contain text data plus `inline elements`_.
312 ``abbreviation`` is analogous to the HTML "abbr" element.
322 The ``abbreviation`` element contains only the `common attributes`_:
323 ids_, names_, dupnames_, source_, and classes_.
328 The ``abbreviation`` element is not exposed in default restructured text. It
329 can only be accessed through custom roles.
331 Pseudo-XML_ example from a custom `:abbr:` role::
334 <abbreviation explanation="Street">
336 is a common abbreviation for "street".
348 The ``address`` element holds the surface mailing address information
349 for the author (individual or group) of the document, or a third-party
350 contact address. Its structure is identical to that of the
351 literal_block_ element: whitespace is significant, especially
359 `Bibliographic Elements`_
362 The following elements may contain ``address``: docinfo_, authors_
365 ``address`` elements contain text data plus `inline elements`_.
368 ``address`` is analogous to the DocBook "address" element.
371 As with the literal_block_ element, newlines and other whitespace
372 is significant and must be preserved. However, a monospaced
373 typeface need not be used.
386 The ``address`` element contains the `common attributes`_ (ids_,
387 names_, dupnames_, source_, and classes_), plus `xml:space`_.
390 The `%bibliographic.elements;`_ parameter entity directly includes
397 reStructuredText_ source::
402 :Address: 123 Example Ave.
405 Complete pseudo-XML_ result after parsing and applying transforms::
407 <document ids="document-title" names="document title">
415 See docinfo_ for a more complete example, including processing
422 This element is a generic, titled admonition. Also see the specific
423 admonition elements Docutils offers (in alphabetical order): caution_,
424 danger_, error_, hint_, important_, note_, tip_, warning_.
431 `Compound Body Elements`_
434 All elements employing the `%body.elements;`_ or
435 `%structure.model;`_ parameter entities in their content models
436 may contain ``admonition``.
439 ``admonition`` elements begin with a title_ and may contain one or
440 more `body elements`_.
443 ``admonition`` has no direct analogues in common DTDs. It can be
444 emulated with primitives and type effects.
447 Rendered distinctly (inset and/or in a box, etc.).
455 (title_, (`%body.elements;`_)+)
458 The ``admonition`` element contains only the `common attributes`_:
459 ids_, names_, dupnames_, source_, and classes_.
462 The `%body.elements;`_ parameter entity directly includes
463 ``admonition``. The `%structure.model;`_ parameter entity
464 indirectly includes ``admonition``.
470 reStructuredText source::
472 .. admonition:: And, by the way...
474 You can make up your own admonition too.
476 Pseudo-XML_ fragment from simple parsing::
478 <admonition class="admonition-and-by-the-way">
482 You can make up your own admonition too.
488 The ``attention`` element is an admonition, a distinctive and
489 self-contained notice. Also see the other admonition elements
490 Docutils offers (in alphabetical order): caution_, danger_, error_,
491 hint_, important_, note_, tip_, warning_, and the generic admonition_.
498 `Compound Body Elements`_
501 All elements employing the `%body.elements;`_ or
502 `%structure.model;`_ parameter entities in their content models
503 may contain ``attention``.
506 ``attention`` elements contain one or more `body elements`_.
509 ``attention`` has no direct analogues in common DTDs. It can be
510 emulated with primitives and type effects.
513 Rendered distinctly (inset and/or in a box, etc.), with the
514 generated title "Attention!" (or similar).
522 (`%body.elements;`_)+
525 The ``attention`` element contains only the `common attributes`_:
526 ids_, names_, dupnames_, source_, and classes_.
529 The `%body.elements;`_ parameter entity directly includes
530 ``attention``. The `%structure.model;`_ parameter entity
531 indirectly includes ``attention``.
537 reStructuredText source::
539 .. Attention:: All your base are belong to us.
541 Pseudo-XML_ fragment from simple parsing::
545 All your base are belong to us.
557 The ``author`` element holds the name of the author of the document.
564 `Bibliographic Elements`_
567 The following elements may contain ``author``: docinfo_, authors_
570 ``author`` elements may contain text data plus `inline elements`_.
573 ``author`` is analogous to the DocBook "author" element.
587 The ``author`` element contains only the `common attributes`_:
588 ids_, names_, dupnames_, source_, and classes_.
591 The `%bibliographic.elements;`_ parameter entity directly includes
598 reStructuredText_ source::
603 :Author: J. Random Hacker
605 Complete pseudo-XML_ result after parsing and applying transforms::
607 <document ids="document-title" names="document title">
614 See docinfo_ for a more complete example, including processing
621 The ``authors`` element is a container for author information for
622 documents with multiple authors.
629 `Bibliographic Elements`_
632 Only the docinfo_ element contains ``authors``.
635 ``authors`` elements may contain the following elements: author_,
636 organization_, address_, contact_
639 ``authors`` is analogous to the DocBook "authors" element.
650 ((author_, organization_?, address_?, contact_?)+)
653 The ``authors`` element contains only the `common attributes`_:
654 ids_, names_, dupnames_, source_, and classes_.
657 The `%bibliographic.elements;`_ parameter entity directly includes
664 reStructuredText_ source::
669 :Authors: J. Random Hacker; Jane Doe
671 Complete pseudo-XML_ result after parsing and applying transforms::
673 <document ids="document-title" names="document title">
683 In reStructuredText, multiple author's names are separated with
684 semicolons (";") or commas (","); semicolons take precedence. There
685 is currently no way to represent the author's organization, address,
686 or contact in a reStructuredText "Authors" field.
688 See docinfo_ for a more complete example, including processing
695 The ``block_quote`` element is used for quotations set off from the
696 main text (standalone).
703 `Compound Body Elements`_
706 All elements employing the `%body.elements;`_ or
707 `%structure.model;`_ parameter entities in their content models
708 may contain ``block_quote``.
711 ``block_quote`` elements contain `body elements`_ followed by an
712 optional attribution_ element.
715 ``block_quote`` is analogous to the "blockquote" element in both
719 ``block_quote`` elements serve to set their contents off from the
720 main text, typically with indentation and/or other decoration.
728 ((`%body.elements;`_)+, attribution_?)
731 The ``block_quote`` element contains only the `common
732 attributes`_: ids_, names_, dupnames_, source_, and classes_.
735 The `%body.elements;`_ parameter entity directly includes
736 ``block_quote``. The `%structure.model;`_ parameter entity
737 indirectly includes ``block_quote``.
743 reStructuredText source::
745 As a great paleontologist once said,
747 This theory, that is mine, is mine.
751 Pseudo-XML_ fragment from simple parsing::
754 As a great paleontologist once said,
757 This theory, that is mine, is mine.
765 The ``bullet_list`` element contains list_item_ elements which are
766 uniformly marked with bullets. Bullets are typically simple dingbats
767 (symbols) such as circles and squares.
774 `Compound Body Elements`_
777 All elements employing the `%body.elements;`_ or
778 `%structure.model;`_ parameter entities in their content models
779 may contain ``bullet_list``.
782 ``bullet_list`` elements contain one or more list_item_ elements.
785 ``bullet_list`` is analogous to the HTML "ul" element and to the
786 DocBook "itemizedlist" element. HTML's "ul" is short for
787 "unordered list", which we consider to be a misnomer. "Unordered"
788 implies that the list items may be randomly rearranged without
789 affecting the meaning of the list. Bullet lists *are* often
790 ordered; the ordering is simply left implicit.
793 Each list item should begin a new vertical block, prefaced by a
805 The ``bullet_list`` element contains the `common attributes`_
806 (ids_, names_, dupnames_, source_, and classes_), plus bullet_.
808 ``bullet`` is used to record the style of bullet from the input
809 data. In documents processed from reStructuredText_, it contains
810 one of "-", "+", or "*". It may be ignored in processing.
813 The `%body.elements;`_ parameter entity directly includes
814 ``bullet_list``. The `%structure.model;`_ parameter entity
815 indirectly includes ``bullet_list``.
821 reStructuredText_ source::
823 - Item 1, paragraph 1.
829 Pseudo-XML_ fragment from simple parsing::
831 <bullet_list bullet="-">
841 See list_item_ for another example.
853 The ``caution`` element is an admonition, a distinctive and
854 self-contained notice. Also see the other admonition elements
855 Docutils offers (in alphabetical order): attention_, danger_, error_,
856 hint_, important_, note_, tip_, warning_, and the generic admonition_.
863 `Compound Body Elements`_
866 All elements employing the `%body.elements;`_ or
867 `%structure.model;`_ parameter entities in their content models
868 may contain ``caution``.
871 ``caution`` elements contain one or more `body elements`_.
874 ``caution`` is analogous to the DocBook "caution" element.
877 Rendered distinctly (inset and/or in a box, etc.), with the
878 generated title "Caution" (or similar).
886 (`%body.elements;`_)+
889 The ``caution`` element contains only the `common attributes`_:
890 ids_, names_, dupnames_, source_, and classes_.
893 The `%body.elements;`_ parameter entity directly includes
894 ``caution``. The `%structure.model;`_ parameter entity
895 indirectly includes ``caution``.
901 reStructuredText source::
903 .. Caution:: Don't take any wooden nickels.
905 Pseudo-XML_ fragment from simple parsing::
909 Don't take any wooden nickels.
918 ``citation_reference``
919 ======================
927 The ``classifier`` element contains the classification or type of the
928 term_ being defined in a definition_list_. For example, it can be
929 used to indicate the type of a variable.
936 `Body Subelements`_ (simple)
939 Only the definition_list_item_ element contains ``classifier``.
942 ``classifier`` elements may contain text data plus `inline elements`_.
945 ``classifier`` has no direct analogues in common DTDs. It can be
946 emulated with primitives or type effects.
949 See definition_list_item_.
960 The ``classifier`` element contains only the `common attributes`_:
961 ids_, names_, dupnames_, source_, and classes_.
967 Here is a hypothetical data dictionary. reStructuredText_ source::
972 Temporary index variable.
974 Pseudo-XML_ fragment from simple parsing::
977 <definition_list_item>
985 <definition_list_item>
992 Temporary index variable.
1016 The ``contact`` element holds contact information for the author
1017 (individual or group) of the document, or a third-party contact. It
1018 is typically used for an email or web address.
1025 `Bibliographic Elements`_
1028 The following elements may contain ``contact``: docinfo_, authors_
1031 ``contact`` elements may contain text data plus `inline
1035 ``contact`` is analogous to the DocBook "email" element. The HTML
1036 "address" element serves a similar purpose.
1050 The ``contact`` element contains only the `common attributes`_:
1051 ids_, names_, dupnames_, source_, and classes_.
1053 :Parameter Entities:
1054 The `%bibliographic.elements;`_ parameter entity directly includes
1061 reStructuredText_ source::
1066 :Contact: jrh@example.com
1068 Complete pseudo-XML_ result after parsing and applying transforms::
1070 <document ids="document-title" names="document title">
1075 <reference refuri="mailto:jrh@example.com">
1078 See docinfo_ for a more complete example, including processing
1091 The ``copyright`` element contains the document's copyright statement.
1098 `Bibliographic Elements`_
1101 Only the docinfo_ element contains ``copyright``.
1104 ``copyright`` elements may contain text data plus `inline
1108 ``copyright`` is analogous to the DocBook "copyright" element.
1122 The ``copyright`` element contains only the `common attributes`_:
1123 ids_, names_, dupnames_, source_, and classes_.
1125 :Parameter Entities:
1126 The `%bibliographic.elements;`_ parameter entity directly includes
1133 reStructuredText_ source::
1138 :Copyright: This document has been placed in the public domain.
1140 Complete pseudo-XML_ result after parsing and applying transforms::
1142 <document ids="document-title" names="document title">
1147 This document has been placed in the public domain.
1149 See docinfo_ for a more complete example, including processing
1156 The ``danger`` element is an admonition, a distinctive and
1157 self-contained notice. Also see the other admonition elements
1158 Docutils offers (in alphabetical order): attention_, caution_, error_,
1159 hint_, important_, note_, tip_, warning_, and the generic admonition_.
1166 `Compound Body Elements`_
1169 All elements employing the `%body.elements;`_ or
1170 `%structure.model;`_ parameter entities in their content models
1171 may contain ``danger``.
1174 ``danger`` elements contain one or more `body elements`_.
1177 ``danger`` has no direct analogues in common DTDs. It can be
1178 emulated with primitives and type effects.
1181 Rendered distinctly (inset and/or in a box, etc.), with the
1182 generated title "!DANGER!" (or similar).
1190 (`%body.elements;`_)+
1193 The ``danger`` element contains only the `common attributes`_:
1194 ids_, names_, dupnames_, source_, and classes_.
1196 :Parameter Entities:
1197 The `%body.elements;`_ parameter entity directly includes
1198 ``danger``. The `%structure.model;`_ parameter entity
1199 indirectly includes ``danger``.
1205 reStructuredText source::
1207 .. DANGER:: Mad scientist at work!
1209 Pseudo-XML_ fragment from simple parsing::
1213 Mad scientist at work!
1219 The ``date`` element contains the date of publication, release, or
1220 last modification of the document.
1227 `Bibliographic Elements`_
1230 Only the docinfo_ element contains ``date``.
1233 ``date`` elements may contain text data plus `inline elements`_.
1236 ``date`` is analogous to the DocBook "date" element.
1239 Often used with the RCS/CVS keyword "Date". See docinfo_.
1250 The ``date`` element contains only the `common attributes`_:
1251 ids_, names_, dupnames_, source_, and classes_.
1253 :Parameter Entities:
1254 The `%bibliographic.elements;`_ parameter entity directly includes
1261 reStructuredText_ source::
1268 Complete pseudo-XML_ result after parsing and applying transforms::
1270 <document ids="document-title" names="document title">
1277 See docinfo_ for a more complete example, including processing
1284 The ``decoration`` element is a container for header_ and footer_
1285 elements and potential future extensions. These elements are used for
1286 notes, time/datestamp, processing information, etc.
1293 `Structural Subelements`_
1296 Only the document_ element contains ``decoration``.
1299 ``decoration`` elements may contain `decorative elements`_.
1302 There are no direct analogies to ``decoration`` in HTML or in
1303 DocBook. Equivalents are typically constructed from primitives
1304 and/or generated by the processing system.
1307 See the individual `decorative elements`_.
1315 (header_?, footer_?)
1317 Although the content model doesn't specifically require contents, no
1318 empty ``decoration`` elements are ever created.
1321 The ``decoration`` element contains only the `common attributes`_:
1322 ids_, names_, dupnames_, source_, and classes_.
1328 reStructuredText_ source::
1332 Complete pseudo-XML_ result after parsing and applying transforms,
1333 assuming that the datestamp command-line option or configuration
1334 setting has been supplied::
1340 Generated on: 2002-08-20.
1348 The ``definition`` element is a container for the body elements used
1349 to define a term_ in a definition_list_.
1356 `Body Subelements`_ (compound)
1359 Only definition_list_item_ elements contain ``definition``.
1362 ``definition`` elements may contain `body elements`_.
1365 ``definition`` is analogous to the HTML "dd" element and to the
1366 DocBook "listitem" element (inside a "variablelistentry" element).
1369 See definition_list_item_.
1377 (`%body.elements;`_)+
1380 The ``definition`` element contains only the `common attributes`_:
1381 ids_, names_, dupnames_, source_, and classes_.
1387 See the examples for the definition_list_, definition_list_item_, and
1388 classifier_ elements.
1394 The ``definition_list`` element contains a list of terms and their
1395 definitions. It can be used for glossaries or dictionaries, to
1396 describe or classify things, for dialogues, or to itemize subtopics
1397 (such as in this reference).
1404 `Compound Body Elements`_
1407 All elements employing the `%body.elements;`_ or
1408 `%structure.model;`_ parameter entities in their content models
1409 may contain ``definition_list``.
1412 ``definition_list`` elements contain one or more
1413 definition_list_item_ elements.
1416 ``definition_list`` is analogous to the HTML "dl" element and to
1417 the DocBook "variablelist" element.
1420 See definition_list_item_.
1428 (definition_list_item_ +)
1431 The ``definition_list`` element contains only the `common
1432 attributes`_: ids_, names_, dupnames_, source_, and classes_.
1434 :Parameter Entities:
1435 The `%body.elements;`_ parameter entity directly includes
1436 ``definition_list``. The `%structure.model;`_ parameter entity
1437 indirectly includes ``definition_list``.
1443 reStructuredText_ source::
1449 The ' : ' indicates a classifier in
1450 definition list item terms only.
1452 Pseudo-XML_ fragment from simple parsing::
1455 <definition_list_item>
1461 <definition_list_item>
1468 The ' : ' indicates a classifier in
1469 definition list item terms only.
1471 See definition_list_item_ and classifier_ for further examples.
1474 ``definition_list_item``
1475 ========================
1477 The ``definition_list_item`` element contains a single
1478 term_/definition_ pair (with optional classifier_).
1485 `Body Subelements`_ (compound)
1488 Only the definition_list_ element contains
1489 ``definition_list_item``.
1492 ``definition_list_item`` elements each contain a single term_,
1493 an optional classifier_, and a definition_.
1496 ``definition_list_item`` is analogous to the DocBook
1497 "variablelistentry" element.
1500 The optional classifier_ can be rendered differently from the
1501 term_. They should be separated visually, typically by spaces
1502 plus a colon or dash.
1510 (term_, classifier_?, definition_)
1513 The ``definition_list_item`` element contains only the `common
1514 attributes`_: ids_, names_, dupnames_, source_, and classes_.
1520 reStructuredText_ source::
1522 Tyrannosaurus Rex : carnivore
1523 Big and scary; the "Tyrant King".
1525 Brontosaurus : herbivore
1526 All brontosauruses are thin at one end,
1527 much much thicker in the middle
1528 and then thin again at the far end.
1532 Pseudo-XML_ fragment from simple parsing::
1535 <definition_list_item>
1542 Big and scary; the "Tyrant King".
1543 <definition_list_item>
1550 All brontosauruses are thin at one end,
1551 much much thicker in the middle
1552 and then thin again at the far end.
1556 See definition_list_ and classifier_ for further examples.
1562 The ``description`` element contains body elements, describing the
1563 purpose or effect of a command-line option or group of options.
1573 Only the option_list_item_ element contains ``description``.
1576 ``description`` elements may contain `body elements`_.
1579 ``description`` has no direct analogues in common DTDs.
1590 (`%body.elements;`_)+
1593 The ``description`` element contains only the `common attributes`_:
1594 ids_, names_, dupnames_, source_, and classes_.
1600 See the examples for the option_list_ element.
1606 The ``docinfo`` element is a container for document bibliographic
1607 data, or meta-data (data about the document). It corresponds to the
1608 front matter of a book, such as the title page and copyright page.
1615 `Structural Subelements`_
1618 Only the document_ element contains ``docinfo``.
1621 ``docinfo`` elements contain `bibliographic elements`_.
1624 ``docinfo`` is analogous to DocBook "info" elements ("bookinfo"
1625 etc.). There are no directly analogous HTML elements; the "meta"
1626 element carries some of the same information, albeit invisibly.
1629 The ``docinfo`` element may be rendered as a two-column table or
1630 in other styles. It may even be invisible or omitted from the
1631 processed output. Meta-data may be extracted from ``docinfo``
1632 children; for example, HTML ``<meta>`` tags may be constructed.
1634 When Docutils_ transforms a reStructuredText_ field_list_ into a
1635 ``docinfo`` element (see the examples below), RCS/CVS keywords are
1636 normally stripped from simple (one paragraph) field bodies. For
1637 complete details, please see `RCS Keywords`_ in the
1638 `reStructuredText Markup Specification`_.
1640 .. _RCS Keywords: rst/restructuredtext.html#rcs-keywords
1648 (`%bibliographic.elements;`_)+
1651 The ``docinfo`` element contains only the `common attributes`_:
1652 ids_, names_, dupnames_, source_, and classes_.
1658 Docinfo is represented in reStructuredText_ by a field_list_ in a
1659 bibliographic context: the first non-comment element of a document_,
1660 after any document title_/subtitle_. The field list is transformed
1661 into a ``docinfo`` element and its children by a transform. Source::
1666 :Author: J. Random Hacker
1667 :Contact: jrh@example.com
1669 :Status: Work In Progress
1671 :Filename: $RCSfile$
1672 :Copyright: This document has been placed in the public domain.
1674 Complete pseudo-XML_ result after parsing and applying transforms::
1676 <document ids="docinfo-example" names="docinfo example">
1683 <reference refuri="mailto:jrh@example.com">
1698 This document has been placed in the public domain.
1700 Note that "Filename" is a non-standard ``docinfo`` field, so becomes a
1701 generic ``field`` element. Also note that the "RCSfile" keyword
1702 syntax has been stripped from the "Filename" data.
1704 See field_list_ for an example in a non-bibliographic context. Also
1705 see the individual examples for the various `bibliographic elements`_.
1711 The ``doctest_block`` element is a Python-specific variant of
1712 literal_block_. It is a block of text where line breaks and
1713 whitespace are significant and must be preserved. ``doctest_block``
1714 elements are used for interactive Python interpreter sessions, which
1715 are distinguished by their input prompt: ``>>>``. They are meant to
1716 illustrate usage by example, and provide an elegant and powerful
1717 testing environment via the `doctest module`_ in the Python standard
1721 http://www.python.org/doc/current/lib/module-doctest.html
1728 `Simple Body Elements`_
1731 All elements employing the `%body.elements;`_ or
1732 `%structure.model;`_ parameter entities in their content models
1733 may contain ``doctest_block``.
1736 ``doctest_block`` elements may contain text data plus `inline
1740 ``doctest_block`` is analogous to the HTML "pre" element and to
1741 the DocBook "programlisting" and "screen" elements.
1744 As with literal_block_, ``doctest_block`` elements are typically
1745 rendered in a monospaced typeface. It is crucial that all
1746 whitespace and line breaks are preserved in the rendered form.
1757 The ``doctest_block`` element contains the `common attributes`_
1758 (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_.
1760 :Parameter Entities:
1761 The `%body.elements;`_ parameter entity directly includes
1762 ``doctest_block``. The `%structure.model;`_ parameter entity
1763 indirectly includes ``doctest_block``.
1769 reStructuredText source::
1771 This is an ordinary paragraph.
1773 >>> print 'this is a Doctest block'
1774 this is a Doctest block
1776 Pseudo-XML_ fragment from simple parsing::
1779 This is an ordinary paragraph.
1780 <doctest_block xml:space="preserve">
1781 >>> print 'this is a Doctest block'
1782 this is a Doctest block
1788 The ``document`` element is the root (topmost) element of the Docutils
1789 document tree. ``document`` is the direct or indirect ancestor of
1790 every other element in the tree. It encloses the entire document
1791 tree. It is the starting point for a document.
1798 `Structural Elements`_
1801 The ``document`` element has no parents.
1804 ``document`` elements may contain `structural subelements`_,
1805 `structural elements`_, and `body elements`_.
1808 ``document`` is analogous to the HTML "html" element and to
1809 several DocBook elements such as "book".
1817 ( (title_, subtitle_?)?,
1819 (docinfo_, transition_?)?,
1820 `%structure.model;`_ )
1822 Depending on the source of the data and the stage of processing, the
1823 "document" may not initially contain a "title". A document title is
1824 not directly representable in reStructuredText_. Instead, a lone
1825 top-level section may have its title promoted to become the document
1826 title_, and similarly for a lone second-level (sub)section's title to
1827 become the document subtitle_.
1829 The contents of "decoration_" may be specified in a document,
1830 constructed programmatically, or both. The "docinfo_" may be
1831 transformed from an initial field_list_.
1833 See the `%structure.model;`_ parameter entity for details of the body
1837 The ``document`` element contains the `common attributes`_ (ids_,
1838 names_, dupnames_, source_, and classes_), plus an optional title__
1839 attribute which stores the document title metadata.
1841 __ `title (attribute)`_
1847 reStructuredText_ source::
1854 Complete pseudo-XML_ result from simple parsing::
1857 <section ids="a-title" names="a title">
1863 After applying transforms, the section title is promoted to become the
1866 <document ids="a-title" names="a title">
1888 The ``enumerated_list`` element contains list_item_ elements which are
1889 uniformly marked with enumerator labels.
1896 `Compound Body Elements`_
1899 All elements employing the `%body.elements;`_ or
1900 `%structure.model;`_ parameter entities in their content models
1901 may contain ``enumerated_list``.
1904 ``enumerated_list`` elements contain one or more list_item_
1908 ``enumerated_list`` is analogous to the HTML "ol" element and to
1909 the DocBook "orderedlist" element.
1912 Each list item should begin a new vertical block, prefaced by a
1913 enumeration marker (such as "1.").
1924 The ``enumerated_list`` element contains the `common attributes`_
1925 (ids_, names_, dupnames_, source_, and classes_), plus enumtype_,
1926 prefix_, suffix_, and start_.
1928 ``enumtype`` is used to record the intended enumeration sequence,
1929 one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z),
1930 "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ...,
1931 mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ...,
1934 ``prefix`` stores the formatting characters used before the
1935 enumerator. In documents originating from reStructuredText_ data,
1936 it will contain either "" (empty string) or "(" (left
1937 parenthesis). It may or may not affect processing.
1939 ``suffix`` stores the formatting characters used after the
1940 enumerator. In documents originating from reStructuredText_ data,
1941 it will contain either "." (period) or ")" (right parenthesis).
1942 Depending on the capabilities of the output format, this attribute
1943 may or may not affect processing.
1945 ``start`` contains the ordinal value of the first item in the
1946 list, in decimal. For lists beginning at value 1 ("1", "a", "A",
1947 "i", or "I"), this attribute may be omitted.
1949 :Parameter Entities:
1950 The `%body.elements;`_ parameter entity directly includes
1951 ``enumerated_list``. The `%structure.model;`_ parameter entity
1952 indirectly includes ``enumerated_list``.
1958 reStructuredText_ source::
1968 Pseudo-XML_ fragment from simple parsing::
1970 <enumerated_list enumtype="arabic" prefix="" suffix=".">
1974 <enumerated_list enumtype="upperalpha" prefix="(" suffix=")">
1988 See list_item_ for another example.
1994 The ``error`` element is an admonition, a distinctive and
1995 self-contained notice. Also see the other admonition elements
1996 Docutils offers (in alphabetical order): attention_, caution_,
1997 danger_, hint_, important_, note_, tip_, warning_, and the generic
2005 `Compound Body Elements`_
2008 All elements employing the `%body.elements;`_ or
2009 `%structure.model;`_ parameter entities in their content models
2010 may contain ``error``.
2013 ``error`` elements contain one or more `body elements`_.
2016 ``error`` has no direct analogues in common DTDs. It can be
2017 emulated with primitives and type effects.
2020 Rendered distinctly (inset and/or in a box, etc.), with the
2021 generated title "Error" (or similar).
2029 (`%body.elements;`_)+
2032 The ``error`` element contains only the `common attributes`_: ids_,
2033 names_, dupnames_, source_, and classes_.
2035 :Parameter Entities:
2036 The `%body.elements;`_ parameter entity directly includes
2037 ``error``. The `%structure.model;`_ parameter entity indirectly
2044 reStructuredText source::
2046 .. Error:: Does not compute.
2048 Pseudo-XML_ fragment from simple parsing::
2058 The ``field`` element contains a pair of field_name_ and field_body_
2069 The following elements may contain ``field``: docinfo_,
2073 Each ``field`` element contains one field_name_ and one
2074 field_body_ element.
2077 ``field`` has no direct analogues in common DTDs.
2088 (field_name_, field_body_)
2091 The ``field`` element contains only the `common attributes`_:
2092 ids_, names_, dupnames_, source_, and classes_.
2094 :Parameter Entities:
2095 The `%bibliographic.elements;`_ parameter entity directly includes
2102 See the examples for the field_list_ and docinfo_ elements.
2108 The ``field_body`` element contains body elements. It is analogous to
2109 a database field's data.
2119 Only the field_ element contains ``field_body``.
2122 ``field_body`` elements may contain `body elements`_.
2125 ``field_body`` has no direct analogues in common DTDs.
2136 (`%body.elements;`_)*
2139 The ``field_body`` element contains only the `common attributes`_:
2140 ids_, names_, dupnames_, source_, and classes_.
2146 See the examples for the field_list_ and docinfo_ elements.
2152 The ``field_list`` element contains two-column table-like structures
2153 resembling database records (label & data pairs). Field lists are
2154 often meant for further processing. In reStructuredText_, field lists
2155 are used to represent bibliographic fields (contents of the docinfo_
2156 element) and directive options.
2163 `Compound Body Elements`_
2166 All elements employing the `%body.elements;`_ or
2167 `%structure.model;`_ parameter entities in their content models
2168 may contain ``field_list``.
2171 ``field_list`` elements contain one or more field_ elements.
2174 ``field_list`` has no direct analogues in common DTDs. It can be
2175 emulated with primitives such as tables.
2178 A ``field_list`` is typically rendered as a two-column list, where
2179 the first column contains "labels" (usually with a colon suffix).
2180 However, field lists are often used for extension syntax or
2181 special processing. Such structures do not survive as field lists
2193 The ``field_list`` element contains only the `common attributes`_:
2194 ids_, names_, dupnames_, source_, and classes_.
2196 :Parameter Entities:
2197 The `%body.elements;`_ parameter entity directly includes
2198 ``field_list``. The `%structure.model;`_ parameter entity
2199 indirectly includes ``field_list``.
2205 reStructuredText_ source::
2210 :Parameter i: integer
2212 Pseudo-XML_ fragment from simple parsing::
2244 The ``field_name`` element contains text; it is analogous to a
2245 database field's name.
2252 `Body Subelements`_ (simple)
2255 Only the field_ element contains ``field_name``.
2258 ``field_name`` elements may contain text data plus `inline elements`_.
2261 ``field_name`` has no direct analogues in common DTDs.
2275 The ``field_name`` element contains only the `common attributes`_:
2276 ids_, names_, dupnames_, source_, and classes_.
2282 See the examples for the field_list_ and docinfo_ elements.
2294 The ``footer`` element is a container element whose contents are meant
2295 to appear at the bottom of a web page, or repeated at the bottom of
2296 every printed page. The ``footer`` element may contain processing
2297 information (datestamp, a link to Docutils_, etc.) as well as custom
2305 `Decorative Elements`_
2308 Only the decoration_ element contains ``footer``.
2311 ``footer`` elements may contain `body elements`_.
2314 There are no direct analogies to ``footer`` in HTML or DocBook.
2315 Equivalents are typically constructed from primitives and/or
2316 generated by the processing system.
2324 (`%body.elements;`_)+
2327 The ``footer`` element contains only the `common attributes`_:
2328 ids_, names_, dupnames_, source_, and classes_.
2334 reStructuredText_ source::
2338 Complete pseudo-XML_ result after parsing and applying transforms,
2339 assuming that the datestamp command-line option or configuration
2340 setting has been supplied::
2346 Generated on: 2002-08-20.
2357 ``footnote_reference``
2358 ======================
2366 Docutils wraps ``generated`` elements around text that is inserted
2367 (generated) by Docutils; i.e., text that was not in the document, like
2368 section numbers inserted by the "sectnum" directive.
2376 The ``header`` element is a container element whose contents are meant
2377 to appear at the top of a web page, or at the top of every printed
2385 `Decorative Elements`_
2388 Only the decoration_ element contains ``header``.
2391 ``header`` elements may contain `body elements`_.
2394 There are no direct analogies to ``header`` in HTML or DocBook.
2395 Equivalents are typically constructed from primitives and/or
2396 generated by the processing system.
2404 (`%body.elements;`_)+
2407 The ``header`` element contains only the `common attributes`_:
2408 ids_, names_, dupnames_, source_, and classes_.
2414 reStructuredText source fragment::
2416 .. header:: This space for rent.
2418 Pseudo-XML_ fragment from simple parsing::
2424 This space for rent.
2430 The ``hint`` element is an admonition, a distinctive and
2431 self-contained notice. Also see the other admonition elements
2432 Docutils offers (in alphabetical order): attention_, caution_,
2433 danger_, error_, important_, note_, tip_, warning_, and the generic
2441 `Compound Body Elements`_
2444 All elements employing the `%body.elements;`_ or
2445 `%structure.model;`_ parameter entities in their content models
2446 may contain ``hint``.
2449 ``hint`` elements contain one or more `body elements`_.
2452 ``hint`` has no direct analogues in common DTDs. It can be
2453 emulated with primitives and type effects.
2456 Rendered distinctly (inset and/or in a box, etc.), with the
2457 generated title "Hint" (or similar).
2465 (`%body.elements;`_)+
2468 The ``hint`` element contains only the `common attributes`_: ids_,
2469 names_, dupnames_, source_, and classes_.
2471 :Parameter Entities:
2472 The `%body.elements;`_ parameter entity directly includes
2473 ``hint``. The `%structure.model;`_ parameter entity indirectly
2480 reStructuredText source::
2482 .. Hint:: It's bigger than a bread box.
2484 Pseudo-XML_ fragment from simple parsing::
2488 It's bigger than a bread box.
2500 The ``important`` element is an admonition, a distinctive and
2501 self-contained notice. Also see the other admonition elements
2502 Docutils offers (in alphabetical order): attention_, caution_,
2503 danger_, error_, hint_, note_, tip_, warning_, and the generic
2511 `Compound Body Elements`_
2514 All elements employing the `%body.elements;`_ or
2515 `%structure.model;`_ parameter entities in their content models
2516 may contain ``important``.
2519 ``important`` elements contain one or more `body elements`_.
2522 ``important`` is analogous to the DocBook "important" element.
2525 Rendered distinctly (inset and/or in a box, etc.), with the
2526 generated title "Important" (or similar).
2534 (`%body.elements;`_)+
2537 The ``important`` element contains only the `common attributes`_:
2538 ids_, names_, dupnames_, source_, and classes_.
2540 :Parameter Entities:
2541 The `%body.elements;`_ parameter entity directly includes
2542 ``important``. The `%structure.model;`_ parameter entity
2543 indirectly includes ``important``.
2549 reStructuredText source::
2553 * Wash behind your ears.
2554 * Clean up your room.
2555 * Back up your data.
2558 Pseudo-XML_ fragment from simple parsing::
2564 Wash behind your ears.
2597 The ``line`` element contains a single line of text, part of a
2605 `Body Subelements`_ (simple)
2608 Only the `line_block`_ element contains ``line``.
2611 ``line`` elements may contain text data plus `inline elements`_.
2614 ``line`` has no direct analogues in common DTDs. It can be
2615 emulated with primitives or type effects.
2629 The ``line`` element contains the `common attributes`_ (ids_,
2630 names_, dupnames_, source_, and classes_), plus `xml:space`_.
2642 The ``line_block`` element contains a sequence of lines and nested
2643 line blocks. Line breaks (implied between elements) and leading
2644 whitespace (indicated by nesting) is significant and must be
2645 preserved. ``line_block`` elements are commonly used for verse and
2646 addresses. See `literal_block`_ for an alternative useful for program
2647 listings and interactive computer sessions.
2654 `Compound Body Elements`_
2657 All elements employing the `%body.elements;`_ or
2658 `%structure.model;`_ parameter entities in their content models
2659 may contain ``line_block``.
2662 ``line_block`` elements may contain line_ elements and nested
2663 ``line_block`` elements.
2666 ``line_block`` is analogous to the DocBook "literallayout" element
2667 and to the HTML "pre" element (with modifications to typeface
2671 Unlike ``literal_block``, ``line_block`` elements are typically
2672 rendered in an ordinary text typeface. It is crucial that leading
2673 whitespace and line breaks are preserved in the rendered form.
2681 (line_ | line_block_)+
2684 The ``line_block`` element contains the `common attributes`_ (ids_,
2685 names_, dupnames_, source_, and classes_), plus `xml:space`_.
2687 :Parameter Entities:
2688 The `%body.elements;`_ parameter entity directly includes
2689 ``line_block``. The `%structure.model;`_ parameter entity
2690 indirectly includes ``line_block``.
2696 reStructuredText uses a directive to indicate a ``line_block``.
2699 Take it away, Eric the Orchestra Leader!
2701 | A one, two, a one two three four
2703 | Half a bee, philosophically,
2704 | must, *ipso facto*, half not be.
2705 | But half the bee has got to be,
2706 | *vis a vis* its entity. D'you see?
2708 | But can a bee be said to be
2709 | or not to be an entire bee,
2710 | when half the bee is not a bee,
2711 | due to some ancient injury?
2715 Pseudo-XML_ fragment from simple parsing::
2718 Take it away, Eric the Orchestra Leader!
2721 A one, two, a one two three four
2724 Half a bee, philosophically,
2732 But half the bee has got to be,
2737 its entity. D'you see?
2740 But can a bee be said to be
2743 or not to be an entire bee,
2746 when half the bee is not a bee,
2749 due to some ancient injury?
2758 The ``list_item`` element is a container for the elements of a list
2766 `Body Subelements`_ (compound)
2769 The bullet_list_ and enumerated_list_ elements contain
2773 ``list_item`` elements may contain `body elements`_.
2776 ``list_item`` is analogous to the HTML "li" element and to the
2777 DocBook "listitem" element.
2780 See bullet_list_ or enumerated_list_.
2788 (`%body.elements;`_)*
2791 The ``list_item`` element contains only the `common attributes`_:
2792 ids_, names_, dupnames_, source_, and classes_.
2798 reStructuredText_ source::
2800 1. Outer list, item 1.
2802 * Inner list, item 1.
2803 * Inner list, item 2.
2805 2. Outer list, item 2.
2807 Pseudo-XML_ fragment from simple parsing::
2809 <enumerated_list enumtype="arabic" prefix="" suffix=".">
2813 <bullet_list bullet="*">
2824 See bullet_list_ or enumerated_list_ for further examples.
2836 The ``literal_block`` element contains a block of text where line
2837 breaks and whitespace are significant and must be preserved.
2838 ``literal_block`` elements are commonly used for program listings and
2839 interactive computer sessions. See `line_block`_ for an alternative
2840 useful for verse and addresses.
2847 `Simple Body Elements`_
2850 All elements employing the `%body.elements;`_ or
2851 `%structure.model;`_ parameter entities in their content models
2852 may contain ``literal_block``.
2855 ``literal_block`` elements may contain text data plus `inline
2859 ``literal_block`` is analogous to the HTML "pre" element and to
2860 the DocBook "programlisting" and "screen" elements.
2863 ``literal_block`` elements are typically rendered in a monospaced
2864 typeface. It is crucial that all whitespace and line breaks are
2865 preserved in the rendered form.
2876 The ``literal_block`` element contains the `common attributes`_
2877 (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_.
2879 :Parameter Entities:
2880 The `%body.elements;`_ parameter entity directly includes
2881 ``literal_block``. The `%structure.model;`_ parameter entity
2882 indirectly includes ``literal_block``.
2888 reStructuredText source::
2890 Here is a literal block::
2893 text = 'is left as-is'
2894 spaces_and_linebreaks = 'are preserved'
2895 markup_processing = None
2897 Pseudo-XML_ fragment from simple parsing::
2900 Here is a literal block:
2901 <literal_block xml:space="preserve">
2903 text = 'is left as-is'
2904 spaces_and_linebreaks = 'are preserved'
2905 markup_processing = None
2910 The ``math`` element contains text in `LaTeX math format` that is typeset
2911 as mathematical notation (inline formula).
2913 If the output format does not support math typesetting, the content is
2923 All elements employing the `%inline.elements;`_ parameter entities in
2924 their content models may contain ``math``.
2927 ``math`` elements may contain text data.
2930 ``math`` is analogous to a MathML "math" element or
2931 the LaTeX (``$ math $``) mode.
2934 Rendered as mathematical notation.
2944 The ``math`` element contains the `common attributes`_
2945 (ids_, names_, dupnames_, source_, and classes_).
2951 The ``math_block`` element contains a block of text in `LaTeX math
2952 format` that is typeset as mathematical notation (display formula).
2953 The ``math_block`` element is generated during the initial parse from a
2956 If the output format does not support math typesetting, the content is
2963 `Simple Body Elements`_
2966 All elements employing the `%body.elements;`_ or
2967 `%structure.model;`_ parameter entities in their content models
2968 may contain ``math_block``.
2971 ``math_block`` elements may contain text data.
2974 ``math_block`` is analogous to a LaTeX "equation*" environment or
2975 a MathML "math" element displayed as block-level element.
2978 Rendered in a block as mathematical notation, typically centered or with
2989 The ``math`` element contains the `common attributes`_
2990 (ids_, names_, dupnames_, source_, and classes_).
2996 The ``note`` element is an admonition, a distinctive and
2997 self-contained notice. Also see the other admonition elements
2998 Docutils offers (in alphabetical order): attention_, caution_,
2999 danger_, error_, hint_, important_, tip_, warning_, and the generic
3007 `Compound Body Elements`_
3010 All elements employing the `%body.elements;`_ or
3011 `%structure.model;`_ parameter entities in their content models
3012 may contain ``note``.
3015 ``note`` elements contain one or more `body elements`_.
3018 ``note`` is analogous to the DocBook "note" element.
3021 Rendered distinctly (inset and/or in a box, etc.), with the
3022 generated title "Note" (or similar).
3030 (`%body.elements;`_)+
3033 The ``note`` element contains only the `common attributes`_: ids_,
3034 names_, dupnames_, source_, and classes_.
3036 :Parameter Entities:
3037 The `%body.elements;`_ parameter entity directly includes
3038 ``note``. The `%structure.model;`_ parameter entity indirectly
3045 reStructuredText source::
3047 .. Note:: Admonitions can be handy to break up a
3048 long boring technical document.
3050 Pseudo-XML_ fragment from simple parsing::
3054 Admonitions can be handy to break up a
3055 long boring technical document.
3060 The ``option`` element groups an option string together with zero or
3061 more option argument placeholders. Note that reStructuredText_
3062 currently supports only one argument per option.
3072 Only the option_group_ element contains ``option``.
3075 Each ``option`` element contains one option_string_ and zero or
3076 more option_argument_ elements.
3079 ``option`` has no direct analogues in common DTDs.
3090 (option_string_, option_argument_ \*)
3093 The ``option`` element contains only the `common attributes`_:
3094 ids_, names_, dupnames_, source_, and classes_.
3100 See the examples for the option_list_ element.
3106 The ``option_argument`` element contains placeholder text for option
3117 Only the option_ element contains ``option_argument``.
3120 ``option_argument`` elements contain text data only.
3123 ``option_argument`` has no direct analogues in common DTDs.
3126 The value of the "delimiter" attribute is prefixed to the
3127 ``option_argument``, separating it from its option_string_ or a
3128 preceding ``option_argument``. The ``option_argument`` text is
3129 typically rendered in a monospaced typeface, possibly italicized
3130 or otherwise altered to indicate its placeholder nature.
3141 The ``option_argument`` element contains the `common attributes`_ (ids_,
3142 names_, dupnames_, source_, and classes_), plus delimiter_.
3144 ``delimiter`` contains the text preceding the ``option_argument``:
3145 either the text separating it from the option_string_ (typically
3146 either "=" or " ") or the text between option arguments (typically
3153 See the examples for the option_list_ element.
3159 The ``option_group`` element groups together one or more option_
3160 elements, all synonyms.
3170 Only the option_list_item_ element contains ``option_group``.
3173 ``option_group`` elements contain one or more option_ elements.
3175 ``option_group`` is an empty element and has no children.
3177 Each ``option_group`` element contains one _ and
3181 ``option_group`` has no direct analogues in common DTDs.
3184 Typically option_ elements within an ``option_group`` are joined
3185 together in a comma-separated list.
3193 (option_group_, description_)
3196 The ``option_group`` element contains only the `common attributes`_:
3197 ids_, names_, dupnames_, source_, and classes_.
3203 See the examples for the option_list_ element.
3209 Each ``option_list`` element contains a two-column list of
3210 command-line options and descriptions, documenting a program's
3218 `Compound Body Elements`_
3221 All elements employing the `%body.elements;`_ or
3222 `%structure.model;`_ parameter entities in their content models
3223 may contain ``option_list``.
3226 ``option_list`` elements contain one or more option_list_item_
3230 ``option_list`` has no direct analogues in common DTDs. It can be
3231 emulated with primitives such as tables.
3234 An ``option_list`` is typically rendered as a two-column list,
3235 where the first column contains option strings and arguments, and
3236 the second column contains descriptions.
3244 (option_list_item_ +)
3247 The ``option_list`` element contains only the `common attributes`_:
3248 ids_, names_, dupnames_, source_, and classes_.
3250 :Parameter Entities:
3251 The `%body.elements;`_ parameter entity directly includes
3252 ``option_list``. The `%structure.model;`_ parameter entity
3253 indirectly includes ``option_list``.
3259 reStructuredText_ source::
3261 -a command-line option "a"
3262 -1 file, --one=file, --two file
3263 Multiple options with arguments.
3265 Pseudo-XML_ fragment from simple parsing::
3275 command-line option "a"
3281 <option_argument delimiter=" ">
3286 <option_argument delimiter="=">
3291 <option_argument delimiter=" ">
3295 Multiple options with arguments.
3298 ``option_list_item``
3299 ====================
3301 The ``option_list_item`` element is a container for a pair of
3302 option_group_ and description_ elements.
3312 Only the option_list_ element contains ``option_list_item``.
3315 Each ``option_list_item`` element contains one option_group_ and
3316 one description_ element.
3319 ``option_list_item`` has no direct analogues in common DTDs.
3330 (option_group_, description_)
3333 The ``option_list_item`` element contains only the `common attributes`_:
3334 ids_, names_, dupnames_, source_, and classes_.
3340 See the examples for the option_list_ element.
3346 The ``option_string`` element contains the text of a command-line
3357 Only the option_ element contains ``option_string``.
3360 ``option_string`` elements contain text data only.
3363 ``option_string`` has no direct analogues in common DTDs.
3366 The ``option_string`` text is typically rendered in a monospaced
3378 The ``option_string`` element contains only the `common attributes`_:
3379 ids_, names_, dupnames_, source_, and classes_.
3385 See the examples for the option_list_ element.
3391 The ``organization`` element contains the name of document author's
3392 organization, or the organization responsible for the document.
3399 `Bibliographic Elements`_
3402 Only the docinfo_ element contains ``organization``.
3405 ``organization`` elements may contain text data plus `inline
3409 ``organization`` is analogous to the DocBook "orgname",
3410 "corpname", or "publishername" elements.
3424 The ``organization`` element contains only the `common attributes`_:
3425 ids_, names_, dupnames_, source_, and classes_.
3427 :Parameter Entities:
3428 The `%bibliographic.elements;`_ parameter entity directly includes
3435 reStructuredText_ source::
3440 :Organization: Humankind
3442 Complete pseudo-XML_ result after parsing and applying transforms::
3444 <document ids="document-title" names="document title">
3451 See docinfo_ for a more complete example, including processing
3458 The ``paragraph`` element contains the text and inline elements of a
3459 single paragraph, a fundamental building block of documents.
3466 `Simple Body Elements`_
3469 All elements employing the `%body.elements;`_ or
3470 `%structure.model;`_ parameter entities in their content models
3471 may contain ``paragraph``.
3474 ``paragraph`` elements may contain text data plus `inline
3478 ``paragraph`` is analogous to the HTML "p" element and to the
3479 DocBook "para" elements.
3490 The ``paragraph`` element contains only the `common attributes`_:
3491 ids_, names_, dupnames_, source_, and classes_.
3493 :Parameter Entities:
3494 The `%body.elements;`_ parameter entity directly includes
3495 ``paragraph``. The `%structure.model;`_ parameter entity
3496 indirectly includes ``paragraph``.
3502 reStructuredText_ source::
3506 Pseudo-XML_ fragment from simple parsing::
3539 The ``revision`` element contains the revision number of the document.
3540 It can be used alone or in conjunction with version_.
3547 `Bibliographic Elements`_
3550 Only the docinfo_ element contains ``revision``.
3553 ``revision`` elements may contain text data plus `inline
3557 ``revision`` is analogous to but simpler than the DocBook
3558 "revision" element. It closely matches the DocBook "revnumber"
3559 element, but in a simpler context.
3562 Often used with the RCS/CVS keyword "Revision". See docinfo_.
3573 The ``revision`` element contains only the `common attributes`_:
3574 ids_, names_, dupnames_, source_, and classes_.
3576 :Parameter Entities:
3577 The `%bibliographic.elements;`_ parameter entity directly includes
3584 reStructuredText_ source::
3592 Complete pseudo-XML_ result after parsing and applying transforms::
3594 <document ids="document-title" names="document title">
3603 See docinfo_ for a more complete example, including processing
3616 rubric n. 1. a title, heading, or the like, in a manuscript,
3617 book, statute, etc., written or printed in red or otherwise
3618 distinguished from the rest of the text. ...
3620 -- Random House Webster's College Dictionary, 1991
3622 A rubric is like an informal heading that doesn't correspond to the
3623 document's structure.
3631 The ``section`` element is the main unit of hierarchy for Docutils
3632 documents. Docutils ``section`` elements are a recursive structure; a
3633 ``section`` may contain other ``section`` elements, without limit.
3634 Paragraphs and other body elements may occur before a ``section``, but
3642 `Structural Elements`_
3645 The following elements may contain ``section``: document_,
3649 ``section`` elements begin with a title_, and may contain `body
3650 elements`_ as well as transition_, topic_, and sidebar_ elements.
3653 ``section`` is analogous to DocBook recursive "section" elements,
3654 and to HTML "div" elements combined with "h1" etc. title elements.
3663 `%structure.model;`_)
3665 See the `%structure.model;`_ parameter entity for details of the body
3669 The ``section`` element contains only the `common attributes`_:
3670 ids_, names_, dupnames_, source_, and classes_.
3672 :Parameter Entities:
3673 The `%section.elements;`_ parameter entity directly includes
3674 ``section``. The `%structure.model;`_ parameter entity indirectly
3675 includes ``section``.
3681 reStructuredText_ source::
3699 Complete pseudo-XML_ result after parsing::
3702 <section ids="title-1" names="title 1">
3707 <section ids="title-2" names="title 2">
3712 <section ids="title-3" names="title 3">
3717 <section ids="title-4" names="title 4">
3727 Sidebars are like miniature, parallel documents that occur inside
3728 other documents, providing related or reference material. A
3729 ``sidebar`` is typically offset by a border and "floats" to the side
3730 of the page; the document's main text may flow around it. Sidebars
3731 can also be likened to super-footnotes; their content is outside of
3732 the flow of the document's main text.
3734 The ``sidebar`` element is a nonrecursive section_-like construct
3735 which may occur at the top level of a section_ wherever a body element
3736 (list, table, etc.) is allowed. In other words, ``sidebar`` elements
3737 cannot nest inside body elements, so you can't have a ``sidebar``
3738 inside a ``table`` or a ``list``, or inside another ``sidebar`` (or
3746 `Structural Elements`_
3749 The following elements may contain ``sidebar``: document_,
3753 ``sidebar`` elements begin with a title_ and an optional subtitle_
3754 and contain `body elements`_ and topic_ elements.
3757 ``sidebar`` is analogous to the DocBook "sidebar" element.
3760 A ``sidebar`` element should be set off from the rest of the
3761 document somehow, typically with a border. Sidebars typically
3762 "float" to the side of the page and the document's main text flows
3771 (title_, subtitle_?,
3772 (`%body.elements;`_ | topic_)+)
3775 The ``sidebar`` element contains only the `common attributes`_:
3776 ids_, names_, dupnames_, source_, and classes_.
3778 :Parameter Entities:
3779 The `%structure.model;`_ parameter entity directly includes
3786 The `"sidebar" directive`_ is used to create a ``sidebar`` element.
3787 reStructuredText_ source::
3790 :subtitle: If Desired
3794 Pseudo-XML_ fragment from simple parsing::
3804 .. _"sidebar" directive: rst/directives.html#sidebar
3810 The ``status`` element contains a status statement for the document,
3811 such as "Draft", "Final", "Work In Progress", etc.
3818 `Bibliographic Elements`_
3821 Only the docinfo_ element contains ``status``.
3824 ``status`` elements may contain text data plus `inline elements`_.
3827 ``status`` is analogous to the DocBook "status" element.
3841 The ``status`` element contains only the `common attributes`_:
3842 ids_, names_, dupnames_, source_, and classes_.
3844 :Parameter Entities:
3845 The `%bibliographic.elements;`_ parameter entity directly includes
3852 reStructuredText_ source::
3857 :Status: Work In Progress
3859 Complete pseudo-XML_ result after parsing and applying transforms::
3861 <document ids="document-title" names="document title">
3868 See docinfo_ for a more complete example, including processing
3884 ``substitution_definition``
3885 ===========================
3890 ``substitution_reference``
3891 ==========================
3899 The ``subtitle`` element stores the subtitle of a document_.
3906 `Structural Subelements`_
3909 The document_ and sidebar_ elements may contain ``subtitle``.
3912 ``subtitle`` elements may contain text data plus `inline
3916 ``subtitle`` is analogous to HTML header elements ("h2" etc.) and
3917 to the DocBook "subtitle" element.
3920 A document's subtitle is usually rendered smaller than its title_.
3931 The ``subtitle`` element contains only the `common attributes`_:
3932 ids_, names_, dupnames_, source_, and classes_.
3938 reStructuredText_ source::
3949 Complete pseudo-XML_ result after parsing and applying transforms::
3951 <document ids="title" names="title">
3954 <subtitle ids="subtitle" names="subtitle">
3959 Note how two section levels have collapsed, promoting their titles to
3960 become the document's title and subtitle. Since there is only one
3961 structural element (document), the subsection's ``ids`` and ``names``
3962 attributes are stored in the ``subtitle`` element.
3980 Docutils tables are based on the Exchange subset of the CALS-table model
3981 (OASIS Technical Memorandum 9901:1999 "XML Exchange Table Model DTD",
3982 http://www.oasis-open.org/html/tm9901.htm).
4002 The ``term`` element contains a word or phrase being defined in a
4010 `Body Subelements`_ (simple)
4013 Only the definition_list_item_ element contains ``term``.
4016 ``term`` elements may contain text data plus `inline elements`_.
4019 ``term`` is analogous to the HTML "dt" element and to the DocBook
4023 See definition_list_item_.
4034 The ``term`` element contains only the `common attributes`_:
4035 ids_, names_, dupnames_, source_, and classes_.
4041 See the examples for the definition_list_, definition_list_item_, and
4042 classifier_ elements.
4060 The ``tip`` element is an admonition, a distinctive and self-contained
4061 notice. Also see the other admonition elements Docutils offers (in
4062 alphabetical order): attention_, caution_, danger_, error_, hint_,
4063 important_, note_, warning_, and the generic admonition_.
4070 `Compound Body Elements`_
4073 All elements employing the `%body.elements;`_ or
4074 `%structure.model;`_ parameter entities in their content models
4075 may contain ``tip``.
4078 ``tip`` elements contain one or more `body elements`_.
4081 ``tip`` is analogous to the DocBook "tip" element.
4084 Rendered distinctly (inset and/or in a box, etc.), with the
4085 generated title "Tip" (or similar).
4093 (`%body.elements;`_)+
4096 The ``tip`` element contains only the `common attributes`_: ids_,
4097 names_, dupnames_, source_, and classes_.
4099 :Parameter Entities:
4100 The `%body.elements;`_ parameter entity directly includes ``tip``.
4101 The `%structure.model;`_ parameter entity indirectly includes
4108 reStructuredText source::
4110 .. Tip:: 15% if the service is good.
4112 Pseudo-XML_ fragment from simple parsing::
4116 15% if the service is good.
4124 The ``title`` element stores the title of a document_, section_,
4125 topic_, sidebar_, or generic admonition_.
4132 `Structural Subelements`_
4135 The following elements may contain ``title``: document_, section_,
4136 topic_, sidebar_, admonition_
4139 ``title`` elements may contain text data plus `inline elements`_.
4142 ``title`` is analogous to HTML "title" and header ("h1" etc.)
4143 elements, and to the DocBook "title" element.
4154 The ``title`` element contains the `common attributes`_ (ids_,
4155 names_, dupnames_, source_, and classes_), plus refid_ and auto_.
4157 ``refid`` is used as a backlink to a table of contents entry.
4159 ``auto`` is used to indicate (with value "1") that the ``title``
4160 has been numbered automatically.
4166 reStructuredText_ source::
4173 Pseudo-XML_ fragment from simple parsing::
4175 <section ids="a-title" names="a title">
4191 The ``topic`` element is a nonrecursive section_-like construct which
4192 may occur at the top level of a section_ wherever a body element
4193 (list, table, etc.) is allowed. In other words, ``topic`` elements
4194 cannot nest inside body elements, so you can't have a ``topic`` inside
4195 a ``table`` or a ``list``, or inside another ``topic``.
4202 `Structural Elements`_
4205 The following elements may contain ``topic``: document_, section_,
4209 ``topic`` elements begin with a title_ and may contain `body
4213 ``topic`` is analogous to the DocBook "simplesect" element.
4216 A ``topic`` element should be set off from the rest of the
4217 document somehow, such as with indentation or a border.
4226 (`%body.elements;`_)+)
4229 The ``topic`` element contains only the `common attributes`_:
4230 ids_, names_, dupnames_, source_, and classes_.
4232 :Parameter Entities:
4233 The `%structure.model;`_ parameter entity directly includes
4240 The `"topic" directive`_ is used to create a ``topic`` element.
4241 reStructuredText_ source::
4247 Pseudo-XML_ fragment from simple parsing::
4255 .. _"topic" directive: rst/directives.html#topic
4261 The ``transition`` element is commonly seen in novels and short
4262 fiction, as a gap spanning one or more lines, with or without a type
4263 ornament such as a row of asterisks. Transitions separate body
4264 elements and sections, dividing a section into untitled divisions. A
4265 transition may not begin or end a section [#]_ or document, nor may
4266 two transitions be immediately adjacent.
4268 See `Doctree Representation of Transitions`__ in `A Record of
4269 reStructuredText Syntax Alternatives`__.
4271 .. [#] In reStructuredText markup, a transition may appear to fall at
4272 the end of a section immediately before another section. A
4273 transform recognizes this case and moves the transition so it
4274 separates the sections.
4276 __ ../dev/rst/alternatives.html#doctree-representation-of-transitions
4277 __ ../dev/rst/alternatives.html
4284 `Structural Subelements`_
4287 The following elements may contain ``transition``: document_,
4291 ``transition`` is an empty element and has no children.
4294 ``transition`` is analogous to the HTML "hr" element.
4297 The ``transition`` element is typically rendered as vertical
4298 whitespace (more than that separating paragraphs), with or without
4299 a horizontal line or row of asterisks. In novels, transitions are
4300 often represented as a row of three well-spaced asterisks with
4301 vertical space above and below.
4311 The ``transition`` element has no content; it is a "point element".
4314 The ``transition`` element contains only the `common attributes`_:
4315 ids_, names_, dupnames_, source_, and classes_.
4317 :Parameter Entities:
4318 The `%structure.model;`_ parameter entity directly includes
4325 reStructuredText_ source::
4333 Complete pseudo-XML_ result after parsing::
4346 The ``version`` element contains the version number of the document.
4347 It can be used alone or in conjunction with revision_.
4354 `Bibliographic Elements`_
4357 Only the docinfo_ element contains ``version``.
4360 ``version`` elements may contain text data plus `inline
4364 ``version`` may be considered analogous to the DocBook "revision",
4365 "revnumber", or "biblioid" elements.
4368 Sometimes used with the RCS/CVS keyword "Revision". See docinfo_
4380 The ``version`` element contains only the `common attributes`_:
4381 ids_, names_, dupnames_, source_, and classes_.
4383 :Parameter Entities:
4384 The `%bibliographic.elements;`_ parameter entity directly includes
4391 reStructuredText_ source::
4398 Complete pseudo-XML_ result after parsing and applying transforms::
4400 <document ids="document-title" names="document title">
4407 See docinfo_ for a more complete example, including processing
4414 The ``warning`` element is an admonition, a distinctive and
4415 self-contained notice. Also see the other admonition elements
4416 Docutils offers (in alphabetical order): attention_, caution_,
4417 danger_, error_, hint_, important_, note_, tip_.
4424 `Compound Body Elements`_
4427 All elements employing the `%body.elements;`_ or
4428 `%structure.model;`_ parameter entities in their content models
4429 may contain ``warning``.
4432 ``warning`` elements contain one or more `body elements`_.
4435 ``warning`` is analogous to the DocBook "warning" element.
4438 Rendered distinctly (inset and/or in a box, etc.), with the
4439 generated title "Warning" (or similar).
4447 (`%body.elements;`_)+
4450 The ``warning`` element contains only the `common attributes`_:
4451 ids_, names_, dupnames_, source_, and classes_.
4453 :Parameter Entities:
4454 The `%body.elements;`_ parameter entity directly includes
4455 ``warning``. The `%structure.model;`_ parameter entity indirectly
4456 includes ``warning``.
4462 reStructuredText source::
4464 .. WARNING:: Reader discretion is strongly advised.
4466 Pseudo-XML_ fragment from simple parsing::
4470 Reader discretion is strongly advised.
4473 ---------------------
4475 ---------------------
4477 .. contents:: :local:
4480 _`Common Attributes`: Through the `%basic.atts;`_ parameter entity,
4481 all elements contain the following attributes: ids_, names_, dupnames_,
4482 source_, and classes_.
4489 Character data. ``CDATA`` attributes may contain arbitrary text.
4492 Like a ``NMTOKEN``, but it must begin with a letter (a "name
4493 production"). Identical ``ID`` values must not appear more than
4494 once in a document; i.e., ID values must uniquely identify their
4498 A reference to an ``ID`` value (a name production) of another
4502 One or more space-separated ``ID`` references (name productions).
4505 A "name token". One or more of letters, digits, ".", "-", and
4509 One or more space-separated ``NMTOKEN`` names.
4512 No if zero ("0"), yes if any other value. This is a parameter
4513 entity which resolves to a ``NMTOKEN`` attribute type.
4516 This emphasizes that the attribute value must be a number. This
4517 is a parameter entity which resolves to a ``NMTOKEN`` attribute
4521 The attribute value may be one of a specified list of values.
4527 `Attribute type`_: ``%yesorno;``. Default value: none (implies no).
4529 The ``anonymous`` attribute is used for unnamed hyperlinks in the
4530 target_ and reference_ elements (via the `%anonymous.att;`_ parameter
4537 `Attribute type`_: ``CDATA``. Default value: none.
4539 The ``auto`` attribute is used to indicate automatically-numbered
4540 footnote_, footnote_reference_ and title_ elements (via the
4541 `%auto.att;`_ parameter entity).
4547 `Attribute type`_: ``IDREFS``. Default value: none.
4549 The ``backrefs`` attribute contains a space-separated list of ids_
4550 references, used for backlinks from footnote_, citation_, and
4551 system_message_ elements (via the `%backrefs.att;`_ parameter entity).
4557 `Attribute type`_: ``CDATA``. Default value: none.
4559 The ``bullet`` attribute is used in the bullet_list_ element.
4565 `Attribute type`_: ``NMTOKENS``. Default value: none.
4567 The ``classes`` attribute is a list containing zero or more names used
4568 to classify an element. The names are converted to conform to the
4569 regular expression ``[a-z](-?[a-z0-9]+)*`` (see the `"class"
4570 directive`_ description for details and rationale_).
4572 The purpose of the attribute is to indicate
4573 an "is-a" variant relationship, to allow an extensible way of defining
4574 sub-classes of existing elements. It can be used to carry context
4575 forward between a Docutils Reader and Writer, when a custom structure
4576 is reduced to a standardized document tree. One common use is in
4577 conjunction with stylesheets, to add selection criteria. It should
4578 not be used to carry formatting instructions or arbitrary content.
4580 The ``classes`` attribute's contents should be ignorable. Writers that
4581 are not familiar with the variant expressed should be able to ignore
4584 ``classes`` is one of the `common attributes`_, shared by all Docutils
4587 .. _"class" directive: rst/directives.html#class
4588 .. _rationale: rst/directives.html#rationale
4593 `Attribute type`_: ``CDATA``. Default value: none.
4595 The ``delimiter`` attribute is used in the option_argument_ element.
4601 `Attribute type`_: ``CDATA``. Default value: none.
4603 The ``dupnames`` attribute is a list containing the names of an
4604 element when there has been a naming conflict. The contents of the
4605 ``dupnames`` attribute would have been transferred from the `names`_
4606 attribute. An element may have at most one of the ``names`` or
4607 ``dupnames`` attributes, but not both. ``dupnames`` is one of the
4608 `common attributes`_, shared by all Docutils elements.
4614 `Attribute type`_: enumeration, one of "arabic", "loweralpha",
4615 "upperalpha", "lowerroman", or "upperroman". Default value: none.
4617 The ``enumtype`` attribute is used in the enumerated_list_ element.
4623 `Attribute type`_: ``NMTOKENS``. Default value: none.
4625 The ``ids`` attribute is a list containing one or more unique
4626 identifier keys. ``ids`` is one of the `common attributes`_, shared
4627 by all Docutils elements.
4633 `Attribute type`_: ``CDATA``. Default value: none.
4635 The ``names`` attribute is a list containing the names of an element,
4636 typically originating from the element's title or content. Each name
4637 in ``names`` must be unique; if there are name conflicts (two or more
4638 elements want to the same name), the contents will be transferred to
4639 the `dupnames`_ attribute on the duplicate elements. An element may
4640 have at most one of the ``names`` or ``dupnames`` attributes, but not
4641 both. ``names`` is one of the `common attributes`_, shared by all
4648 `Attribute type`_: ``CDATA``. Default value: none.
4650 The ``prefix`` attribute is used in the enumerated_list_ element.
4656 `Attribute type`_: ``IDREF``. Default value: none.
4658 The ``refid`` attribute contains references to `ids`_ attributes in
4659 other elements. It is used by the target_, reference_,
4660 footnote_reference_, citation_reference_, title_ and problematic_
4661 elements (via the `%refid.att;`_ and `%reference.atts;`_ parameter
4668 `Attribute type`_: ``NMTOKENS``. Default value: none.
4670 The ``refname`` attribute contains an internal reference to the
4671 `names`_ attribute of another element. On a `target`_ element,
4672 ``refname`` indicates an indirect target which may resolve to either
4673 an internal or external reference. ``refname`` is used by the
4674 target_, reference_, footnote_reference_, citation_reference_, and
4675 substitution_reference_ elements (via the `%refname.att;`_ and
4676 `%reference.atts;`_ parameter entities).
4682 `Attribute type`_: ``CDATA``. Default value: none.
4684 The ``refuri`` attribute contains an external reference to a URI/URL.
4685 It is used by the target_, reference_, footnote_reference_, and
4686 citation_reference_ elements (via the `%reference.atts;`_ parameter
4693 `Attribute type`_: ``CDATA``. Default value: none.
4695 The ``source`` attribute is used to store the path or URL to the
4696 source text that was used to produce the document tree. It is one of
4697 the `common attributes`_, shared by all Docutils elements.
4703 `Attribute type`_: ``%number;``. Default value: none.
4705 The ``start`` attribute is used in the enumerated_list_ element.
4711 `Attribute type`_: ``CDATA``. Default value: none.
4713 The ``suffix`` attribute is used in the enumerated_list_ element.
4719 `Attribute type`_: one of "default" or "preserve". Default value:
4722 The ``xml:space`` attribute is a standard XML attribute for
4723 whitespace-preserving elements. It is used by the literal_block_,
4724 line_block_, doctest_block_, comment_, and raw_ elements (via the
4725 `%fixedspace.att;`_ parameter entity). It is a fixed attribute, meant
4726 to communicate to an XML parser that the element contains significant
4727 whitespace. The attribute value should not be set in a document
4731 .. _title (attribute):
4736 `Attribute type`_: ``CDATA``. Default value: none.
4738 The ``title`` attribute stores the title metadata of a document. This
4739 title is typically not part of the rendered document. It may for
4740 example be used in HTML's ``title`` element.
4743 ----------------------------
4744 Parameter Entity Reference
4745 ----------------------------
4747 .. contents:: :local:
4750 Parameter entities are used to simplify the DTD (to share definitions
4751 and reduce duplication) and to allow the DTD to be customized by
4752 wrapper DTDs (external client DTDs that use or import the Docutils
4753 DTD). Parameter entities may be overridden by wrapper DTDs, replacing
4754 the definitions below with custom definitions. Parameter entities
4755 whose names begin with "additional" are meant to allow easy extension
4762 The ``%anonymous.att;`` parameter entity contains the anonymous_
4763 attribute, used for unnamed hyperlinks.
4769 anonymous_ %yesorno; #IMPLIED
4771 The reference_ and target_ elements directly employ the
4772 ``%anonymous.att;`` parameter entity in their attribute lists.
4778 The ``%auto.att;`` parameter entity contains the auto_ attribute, used
4779 to indicate an automatically-numbered footnote or title.
4785 auto_ CDATA #IMPLIED
4787 The footnote_, footnote_reference_, and title_ elements directly
4788 employ the ``%auto.att;`` parameter entity in their attribute lists.
4794 The ``%backrefs.att;`` parameter entity contains the backrefs_
4795 attribute, a space-separated list of id references, for backlinks.
4801 backrefs_ IDREFS #IMPLIED
4803 The citation_, footnote_, and system_message_ elements directly employ
4804 the ``%backrefs.att;`` parameter entity in their attribute lists.
4810 The ``%basic.atts;`` parameter entity lists attributes common to all
4811 Docutils elements. See `Common Attributes`_.
4817 ids_ NMTOKENS #IMPLIED
4818 names_ CDATA #IMPLIED
4819 dupnames_ CDATA #IMPLIED
4820 source_ CDATA #IMPLIED
4821 classes_ NMTOKENS #IMPLIED
4822 %additional.basic.atts;
4824 The ``%additional.basic.atts;`` parameter entity can be used by
4825 wrapper DTDs to extend ``%basic.atts;``.
4828 ``%bibliographic.elements;``
4829 ============================
4831 The ``%bibliographic.elements;`` parameter entity contains an OR-list of all
4832 `bibliographic elements`_.
4838 author_ | authors_ | organization_ | contact_ | address_
4839 | version_ | revision_ | status_ | date_ | copyright_
4841 %additional.bibliographic.elements;
4843 The ``%additional.bibliographic.elements;`` parameter entity can be used by
4844 wrapper DTDs to extend ``%bibliographic.elements;``.
4846 Only the docinfo_ element directly employs the
4847 ``%bibliographic.elements;`` parameter entity in its content model.
4853 The ``%body.elements;`` parameter entity contains an OR-list of all
4854 `body elements`_. ``%body.elements;`` is itself contained within the
4855 `%structure.model;`_ parameter entity.
4861 admonition_ | attention_ | block_quote_ | bullet_list_ | caution_
4862 | citation_ | compound_ | comment_ | container_ | danger_ |
4863 definition_list_ | doctest_block_ | enumerated_list_ | error_ |
4864 field_list_ | figure_ | footnote_ | hint_ | image_ | important_
4865 | line_block_ | literal_block_ | note_ | option_list_ |
4866 paragraph_ | pending_ | raw_ reference_ | rubric_ |
4867 substitution_definition_ | system_message_ | table_ | target_ |
4868 tip_ | warning_ %additional.body.elements;
4870 The ``%additional.body.elements;`` parameter entity can be used by
4871 wrapper DTDs to extend ``%body.elements;``.
4873 The ``%body.elements;`` parameter entity is directly employed in the
4874 content models of the following elements: admonition_, attention_,
4875 block_quote_, caution_, citation_, compound_, danger_, definition_,
4876 description_, entry_, error_, field_body_, footer_, footnote_,
4877 header_, hint_, important_, legend_, list_item_, note_, sidebar_,
4878 system_message_, tip_, topic_, warning_
4880 Via `%structure.model;`_, the ``%body.elements;`` parameter entity is
4881 indirectly employed in the content models of the document_ and
4885 ``%fixedspace.att;``
4886 ====================
4888 The ``%fixedspace.att;`` parameter entity contains the `xml:space`_
4889 attribute, a standard XML attribute for whitespace-preserving
4896 `xml:space`_ (default | preserve) #FIXED 'preserve'
4898 The ``%fixedspace.att;`` parameter entity is directly employed in the
4899 attribute lists of the following elements: address_, comment_,
4900 doctest_block_, line_block_, literal_block_, raw_
4903 ``%inline.elements;``
4904 =====================
4906 The ``%inline.elements;`` parameter entity contains an OR-list of all
4913 abbreviation_ | acronym_ | citation_reference_ | emphasis_ |
4914 footnote_reference_ | generated_ | image_ | inline_ | literal_ |
4915 problematic_ | raw_ | reference_ | strong_ | substitution_reference_ |
4916 subscript_ | superscript_ | target_ | title_reference_
4917 %additional.inline.elements;
4919 The ``%additional.inline.elements;`` parameter entity can be used by
4920 wrapper DTDs to extend ``%inline.elements;``.
4922 Via `%text.model;`_, the ``%inline.elements;`` parameter entity is
4923 indirectly employed in the content models of the following elements:
4924 abbreviation_, acronym_, address_, attribution_, author_, caption_,
4925 classifier_, contact_, copyright_, date_, doctest_block_, emphasis_,
4926 generated_, inline_, line_block_, literal_block_, math_, math_block_,
4928 paragraph_, problematic_, raw_, reference_, revision_, rubric_,
4929 status_, strong_, subscript_, substitution_definition_,
4930 substitution_reference_, subtitle_, superscript_, target_, term_,
4931 title_, title_reference_, version_
4934 ``%reference.atts;``
4935 ====================
4937 The ``%reference.atts;`` parameter entity groups together the refuri_,
4938 refid_, and refname_ attributes.
4947 %additional.reference.atts;
4949 The ``%additional.reference.atts;`` parameter entity can be used by
4950 wrapper DTDs to extend ``%additional.reference.atts;``.
4952 The citation_reference_, footnote_reference_, reference_, and target_
4953 elements directly employ the ``%reference.att;`` parameter entity in
4954 their attribute lists.
4960 The ``%refid.att;`` parameter entity contains the refid_ attribute, an
4961 internal reference to the `ids`_ attribute of another element.
4967 refid_ CDATA #IMPLIED
4969 The title_ and problematic_ elements directly employ the
4970 ``%refid.att;`` parameter entity in their attribute lists.
4972 Via `%reference.atts;`_, the ``%refid.att;`` parameter entity is
4973 indirectly employed in the attribute lists of the citation_reference_,
4974 footnote_reference_, reference_, and target_ elements.
4980 The ``%refname.att;`` parameter entity contains the refname_
4981 attribute, an internal reference to the `names`_ attribute of another
4982 element. On a `target`_ element, ``refname`` indicates an indirect
4983 target which may resolve to either an internal or external
4990 refname_ NMTOKENS #IMPLIED
4992 The substitution_reference_ element directly employs the
4993 ``%refname.att;`` parameter entity in its attribute list.
4995 Via `%reference.atts;`_, the ``%refname.att;`` parameter entity is
4996 indirectly employed in the attribute lists of the citation_reference_,
4997 footnote_reference_, reference_, and target_ elements.
5003 The ``%refuri.att;`` parameter entity contains the refuri_ attribute,
5004 an external reference to a URI/URL.
5010 refuri_ CDATA #IMPLIED
5012 Via `%reference.atts;`_, the ``%refuri.att;`` parameter entity is
5013 indirectly employed in the attribute lists of the citation_reference_,
5014 footnote_reference_, reference_, and target_ elements.
5017 ``%section.elements;``
5018 ======================
5020 The ``%section.elements;`` parameter entity contains an OR-list of all
5021 section_-equivalent elements. ``%section.elements;`` is itself
5022 contained within the `%structure.model;`_ parameter entity.
5029 %additional.section.elements;
5031 The ``%additional.section.elements;`` parameter entity can be used
5032 by wrapper DTDs to extend ``%section.elements;``.
5034 Via `%structure.model;`_, the ``%section.elements;`` parameter entity
5035 is indirectly employed in the content models of the document_ and
5039 ``%structure.model;``
5040 =====================
5042 The ``%structure.model;`` parameter entity encapsulates the
5043 hierarchical structure of a document and of its constituent parts.
5044 See the discussion of the `element hierarchy`_ above.
5050 ( ( (`%body.elements;`_ | topic_ | sidebar_)+, transition_? )*,
5051 ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? )
5053 Each document_ or section_ contains zero or more body elements,
5054 topics, and/or sidebars, optionally interspersed with single
5055 transitions, followed by zero or more sections (whose contents are
5056 recursively the same as this model) optionally interspersed with
5059 The following restrictions are imposed by this model:
5061 * Transitions must be separated by other elements (body elements,
5062 sections, etc.). In other words, a transition may not be
5063 immediately adjacent to another transition.
5065 * A transition may not occur at the beginning of a document or
5068 An additional restriction, which cannot be expressed in the language
5069 of DTDs, is imposed by software:
5071 * A transition may not occur at the end of a document or section.
5073 The `%structure.model;`_ parameter entity is directly employed in the
5074 content models of the document_ and section_ elements.
5080 The ``%text.model;`` parameter entity is used by many elements to
5081 represent text data mixed with `inline elements`_.
5087 (#PCDATA | `%inline.elements;`_)*
5089 The ``%text.model;`` parameter entity is directly employed in the
5090 content models of the following elements: abbreviation_, acronym_,
5091 address_, author_, caption_, classifier_, contact_, copyright_, date_,
5092 doctest_block_, emphasis_, field_name_, generated_, line_block_,
5093 literal_block_, organization_, paragraph_, problematic_, raw_,
5094 reference_, revision_, status_, strong_, substitution_definition_,
5095 substitution_reference_, subtitle_, target_, term_, title_, version_
5102 indent-tabs-mode: nil
5103 sentence-end-double-space: t