docutils/docs/ref/doctree.txt

   1 ============================
   2  The Docutils Document Tree
   3 ============================
   4
   5 A Guide to the Docutils DTD
   6 ***************************
   7
   8 :Author: David Goodger
   9 :Contact: docutils-develop@lists.sourceforge.net
  10 :Revision: $Revision$
  11 :Date: $Date$
  12 :Copyright: This document has been placed in the public domain.
  13
  14
  15 .. contents:: :depth: 1
  16
  17
  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.
  23
  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.
  28
  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
  32 Language (XML)`_.
  33
  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`_.
  38
  39 .. _Docutils: http://docutils.sourceforge.net/
  40 .. _Docutils Generic DTD:
  41 .. _Docutils DTD:
  42 .. _docutils.dtd: docutils.dtd
  43 .. _Introducing the Extensible Markup Language (XML):
  44    http://xml.coverpages.org/xmlIntro.html
  45 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
  46 .. _A ReStructuredText Primer: ../user/rst/quickstart.html
  47 .. _reStructuredText Markup Specification: rst/restructuredtext.html
  48
  49
  50 -------------------
  51  Element Hierarchy
  52 -------------------
  53
  54 .. contents:: :local:
  55
  56 Below is a simplified diagram of the hierarchy of elements in the
  57 Docutils document tree structure.  An element may contain any other
  58 elements immediately below it in the diagram.  Notes are written in
  59 square brackets.  Element types in parentheses indicate recursive or
  60 one-to-many relationships; sections may contain (sub)sections, tables
  61 contain further body elements, etc. ::
  62
  63   +--------------------------------------------------------------------+
  64   | document  [may begin with a title, subtitle, decoration, docinfo]  |
  65   |                             +--------------------------------------+
  66   |                             | sections  [each begins with a title] |
  67   +-----------------------------+-------------------------+------------+
  68   | [body elements:]                                      | (sections) |
  69   |         | - literal | - lists  |       | - hyperlink  +------------+
  70   |         |   blocks  | - tables |       |   targets    |
  71   | para-   | - doctest | - block  | foot- | - sub. defs  |
  72   | graphs  |   blocks  |   quotes | notes | - comments   |
  73   +---------+-----------+----------+-------+--------------+
  74   | [text]+ | [text]    | (body elements)  | [text]       |
  75   | (inline +-----------+------------------+--------------+
  76   | markup) |
  77   +---------+
  78
  79 The Docutils document model uses a simple, recursive model for section
  80 structure.  A document_ node may contain body elements and section_
  81 elements.  Sections in turn may contain body elements and sections.
  82 The level (depth) of a section element is determined from its physical
  83 nesting level; unlike other document models (``<h1>`` in HTML_,
  84 ``<sect1>`` in DocBook_, ``<div1>`` in XMLSpec_) the level is not
  85 incorporated into the element name.
  86
  87 The Docutils document model uses strict element content models.  Every
  88 element has a unique structure and semantics, but elements may be
  89 classified into general categories (below).  Only elements which are
  90 meant to directly contain text data have a mixed content model, where
  91 text data and inline elements may be intermixed.  This is unlike the
  92 much looser HTML_ document model, where paragraphs and text data may
  93 occur at the same level.
  94
  95
  96 Structural Elements
  97 ===================
  98
  99 Structural elements may only contain child elements; they do not
 100 directly contain text data.  Structural elements may contain body
 101 elements or further structural elements.  Structural elements can only
 102 be child elements of other structural elements.
 103
 104 Category members: document_, section_, topic_, sidebar_
 105
 106
 107 Structural Subelements
 108 ----------------------
 109
 110 Structural subelements are child elements of structural elements.
 111 Simple structuctural subelements (title_, subtitle_) contain text
 112 data; the others are compound and do not directly contain text data.
 113
 114 Category members: title_, subtitle_, decoration_, docinfo_,
 115 transition_
 116
 117
 118 Bibliographic Elements
 119 ``````````````````````
 120
 121 The docinfo_ element is an optional child of document_.  It groups
 122 bibliographic elements together.  All bibliographic elements except
 123 authors_ and field_ contain text data.  authors_ contains further
 124 bibliographic elements (most notably author_).  field_ contains
 125 field_name_ and field_body_ body subelements.
 126
 127 Category members: address_, author_, authors_, contact_, copyright_,
 128 date_, field_, organization_, revision_, status_, version_
 129
 130
 131 Decorative Elements
 132 ```````````````````
 133
 134 The decoration_ element is also an optional child of document_.  It
 135 groups together elements used to generate page headers and footers.
 136
 137 Category members: footer_, header_
 138
 139
 140 Body Elements
 141 =============
 142
 143 Body elements are contained within structural elements and compound
 144 body elements.  There are two subcategories of body elements: simple
 145 and compound.
 146
 147 Category members: admonition_, attention_, block_quote_, bullet_list_,
 148 caution_, citation_, comment_, compound_, container_, danger_,
 149 definition_list_, doctest_block_, enumerated_list_, error_,
 150 field_list_, figure_, footnote_, hint_, image_, important_,
 151 line_block_, literal_block_, note_, option_list_, paragraph_,
 152 pending_, raw_, rubric_, substitution_definition_, system_message_,
 153 table_, target_, tip_, warning_
 154
 155
 156 Simple Body Elements
 157 --------------------
 158
 159 Simple body elements are empty or directly contain text data.  Those
 160 that contain text data may also contain inline elements.  Such
 161 elements therefore have a "mixed content model".
 162
 163 Category members: comment_, doctest_block_, image_, literal_block_,
 164 math_block_, paragraph_, pending_, raw_, rubric_, substitution_definition_,
 165 target_
 166
 167
 168 Compound Body Elements
 169 ----------------------
 170
 171 Compound body elements contain local substructure (body subelements)
 172 and further body elements.  They do not directly contain text data.
 173
 174 Category members: admonition_, attention_, block_quote_, bullet_list_,
 175 caution_, citation_, compound_, container_, danger_, definition_list_,
 176 enumerated_list_, error_, field_list_, figure_, footnote_, hint_,
 177 important_, line_block, note_, option_list_, system_message_, table_,
 178 tip_, warning_
 179
 180
 181 Body Subelements
 182 ````````````````
 183
 184 Compound body elements contain specific subelements (e.g. bullet_list_
 185 contains list_item_).  Subelements may themselves be compound elements
 186 (containing further child elements, like field_) or simple data
 187 elements (containing text data, like field_name_).  These subelements
 188 always occur within specific parent elements, never at the body
 189 element level (beside paragraphs, etc.).
 190
 191 Category members (simple): attribution_, caption_, classifier_,
 192 colspec_, field_name_, label_, line_, option_argument_,
 193 option_string_, term_
 194
 195 Category members (compound): definition_, definition_list_item_,
 196 description_, entry_, field_, field_body_, legend_, list_item_,
 197 option_, option_group_, option_list_item_, row_, tbody_, tgroup_,
 198 thead_
 199
 200
 201 Inline Elements
 202 ===============
 203
 204 Inline elements directly contain text data, and may also contain
 205 further inline elements.  Inline elements are contained within simple
 206 body elements.  Most inline elements have a "mixed content model".
 207
 208 Category members: abbreviation_, acronym_, citation_reference_,
 209 emphasis_, footnote_reference_, generated_, image_, inline_, literal_,
 210 math_, problematic_, reference_, strong_, subscript_,
 211 substitution_reference_, superscript_, target_, title_reference_, raw_
 212
 213
 214 .. _HTML: http://www.w3.org/MarkUp/
 215 .. _DocBook: http://docbook.org/tdg/en/html/docbook.html
 216 .. _XMLSpec: http://www.w3.org/XML/1998/06/xmlspec-report.htm
 217
 218
 219 -------------------
 220  Element Reference
 221 -------------------
 222
 223 .. contents:: :local:
 224               :depth: 1
 225
 226 Each element in the DTD (document type definition) is described in its
 227 own section below.  Each section contains an introduction plus the
 228 following subsections:
 229
 230 * Details (of element relationships and semantics):
 231
 232   - Category: One or more references to the element categories in
 233     `Element Hierarchy`_ above.  Some elements belong to more than one
 234     category.
 235
 236   - Parents: A list of elements which may contain the element.
 237
 238   - Children: A list of elements which may occur within the element.
 239
 240   - Analogues: Describes analogous elements in well-known document
 241     models such as HTML_ or DocBook_.  Lists similarities and
 242     differences.
 243
 244   - Processing: Lists formatting or rendering recommendations for the
 245     element.
 246
 247 * Content Model:
 248
 249   The formal XML content model from the `Docutils DTD`_, followed by:
 250
 251   - Attributes: Describes (or refers to descriptions of) the possible
 252     values and semantics of each attribute.
 253
 254   - Parameter Entities: Lists the parameter entities which directly or
 255     indirectly include the element.
 256
 257 * Examples: reStructuredText_ examples are shown along with
 258   fragments of the document trees resulting from parsing.
 259   _`Pseudo-XML` is used for the results of parsing and processing.
 260   Pseudo-XML is a representation of XML where nesting is indicated by
 261   indentation and end-tags are not shown.  Some of the precision of
 262   real XML is given up in exchange for easier readability.  For
 263   example, the following are equivalent:
 264
 265   - Real XML::
 266
 267         <document>
 268         <section ids="a-title" names="a title">
 269         <title>A Title</title>
 270         <paragraph>A paragraph.</paragraph>
 271         </section>
 272         </document>
 273
 274   - Pseudo-XML::
 275
 276         <document>
 277             <section ids="a-title" names="a title">
 278                 <title>
 279                     A Title
 280                 <paragraph>
 281                     A paragraph.
 282
 283 --------------------
 284
 285 Many of the element reference sections below are marked "_`to be
 286 completed`".  Please help complete this document by contributing to
 287 its writing.
 288
 289
 290 ``abbreviation``
 291 ================
 292
 293 The ``abbreviation`` element is an inline element used to represent an
 294 abbreviation being used in the document. An example of an abbreviation is 'St'
 295 being used instead of 'Street'.
 296
 297 Details
 298 -------
 299
 300 :Category:
 301     `Inline Elements`_
 302
 303 :Parents:
 304      All elements employing the %inline.elements; parameter entities in their
 305      content models may contain ``abbreviation``.
 306
 307 :Children:
 308     ``abbreviation`` elements may contain text data plus `inline elements`_.
 309
 310 :Analogues:
 311     ``abbreviation`` is analogous to the HTML "abbr" element.
 312
 313 Content Model
 314 -------------
 315
 316 .. parsed-literal::
 317
 318     `%text.model;`_
 319
 320 :Attributes:
 321     The ``abbreviation`` element contains only the `common attributes`_:
 322     ids_, names_, dupnames_, source_, and classes_.
 323
 324 Examples
 325 --------
 326
 327 The ``abbreviation`` element is not exposed in default restructured text. It
 328 can only be accessed through custom roles.
 329
 330 Pseudo-XML_ example from a custom `:abbr:` role::
 331
 332     <paragraph>
 333         <abbreviation explanation="Street">
 334             St
 335         is a common abbreviation for "street".
 336
 337
 338 ``acronym``
 339 ===========
 340
 341 `To be completed`_.
 342
 343
 344 ``address``
 345 ===========
 346
 347 The ``address`` element holds the surface mailing address information
 348 for the author (individual or group) of the document, or a third-party
 349 contact address.  Its structure is identical to that of the
 350 literal_block_ element: whitespace is significant, especially
 351 newlines.
 352
 353
 354 Details
 355 -------
 356
 357 :Category:
 358     `Bibliographic Elements`_
 359
 360 :Parents:
 361     The following elements may contain ``address``: docinfo_, authors_
 362
 363 :Children:
 364     ``address`` elements contain text data plus `inline elements`_.
 365
 366 :Analogues:
 367     ``address`` is analogous to the DocBook "address" element.
 368
 369 :Processing:
 370     As with the literal_block_ element, newlines and other whitespace
 371     is significant and must be preserved.  However, a monospaced
 372     typeface need not be used.
 373
 374     See also docinfo_.
 375
 376
 377 Content Model
 378 -------------
 379
 380 .. parsed-literal::
 381
 382     `%text.model;`_
 383
 384 :Attributes:
 385     The ``address`` element contains the `common attributes`_ (ids_,
 386     names_, dupnames_, source_, and classes_), plus `xml:space`_.
 387
 388 :Parameter Entities:
 389     The `%bibliographic.elements;`_ parameter entity directly includes
 390     ``address``.
 391
 392
 393 Examples
 394 --------
 395
 396 reStructuredText_ source::
 397
 398     Document Title
 399     ==============
 400
 401     :Address: 123 Example Ave.
 402               Example, EX
 403
 404 Complete pseudo-XML_ result after parsing and applying transforms::
 405
 406     <document ids="document-title" names="document title">
 407         <title>
 408             Document Title
 409         <docinfo>
 410             <address>
 411                 123 Example Ave.
 412                 Example, EX
 413
 414 See docinfo_ for a more complete example, including processing
 415 context.
 416
 417
 418 ``admonition``
 419 ==============
 420
 421 This element is a generic, titled admonition.  Also see the specific
 422 admonition elements Docutils offers (in alphabetical order): caution_,
 423 danger_, error_, hint_, important_, note_, tip_, warning_.
 424
 425
 426 Details
 427 -------
 428
 429 :Category:
 430     `Compound Body Elements`_
 431
 432 :Parents:
 433     All elements employing the `%body.elements;`_ or
 434     `%structure.model;`_ parameter entities in their content models
 435     may contain ``admonition``.
 436
 437 :Children:
 438     ``admonition`` elements begin with a title_ and may contain one or
 439     more `body elements`_.
 440
 441 :Analogues:
 442     ``admonition`` has no direct analogues in common DTDs.  It can be
 443     emulated with primitives and type effects.
 444
 445 :Processing:
 446     Rendered distinctly (inset and/or in a box, etc.).
 447
 448
 449 Content Model
 450 -------------
 451
 452 .. parsed-literal::
 453
 454    (title_, (`%body.elements;`_)+)
 455
 456 :Attributes:
 457     The ``admonition`` element contains only the `common attributes`_:
 458     ids_, names_, dupnames_, source_, and classes_.
 459
 460 :Parameter Entities:
 461     The `%body.elements;`_ parameter entity directly includes
 462     ``admonition``.  The `%structure.model;`_ parameter entity
 463     indirectly includes ``admonition``.
 464
 465
 466 Examples
 467 --------
 468
 469 reStructuredText source::
 470
 471     .. admonition:: And, by the way...
 472
 473        You can make up your own admonition too.
 474
 475 Pseudo-XML_ fragment from simple parsing::
 476
 477     <admonition class="admonition-and-by-the-way">
 478         <title>
 479             And, by the way...
 480         <paragraph>
 481             You can make up your own admonition too.
 482
 483
 484 ``attention``
 485 =============
 486
 487 The ``attention`` element is an admonition, a distinctive and
 488 self-contained notice.  Also see the other admonition elements
 489 Docutils offers (in alphabetical order): caution_, danger_, error_,
 490 hint_, important_, note_, tip_, warning_, and the generic admonition_.
 491
 492
 493 Details
 494 -------
 495
 496 :Category:
 497     `Compound Body Elements`_
 498
 499 :Parents:
 500     All elements employing the `%body.elements;`_ or
 501     `%structure.model;`_ parameter entities in their content models
 502     may contain ``attention``.
 503
 504 :Children:
 505     ``attention`` elements contain one or more `body elements`_.
 506
 507 :Analogues:
 508     ``attention`` has no direct analogues in common DTDs.  It can be
 509     emulated with primitives and type effects.
 510
 511 :Processing:
 512     Rendered distinctly (inset and/or in a box, etc.), with the
 513     generated title "Attention!" (or similar).
 514
 515
 516 Content Model
 517 -------------
 518
 519 .. parsed-literal::
 520
 521    (`%body.elements;`_)+
 522
 523 :Attributes:
 524     The ``attention`` element contains only the `common attributes`_:
 525     ids_, names_, dupnames_, source_, and classes_.
 526
 527 :Parameter Entities:
 528     The `%body.elements;`_ parameter entity directly includes
 529     ``attention``.  The `%structure.model;`_ parameter entity
 530     indirectly includes ``attention``.
 531
 532
 533 Examples
 534 --------
 535
 536 reStructuredText source::
 537
 538     .. Attention:: All your base are belong to us.
 539
 540 Pseudo-XML_ fragment from simple parsing::
 541
 542     <attention>
 543         <paragraph>
 544             All your base are belong to us.
 545
 546
 547 ``attribution``
 548 ===============
 549
 550 `To be completed`_.
 551
 552
 553 ``author``
 554 ==========
 555
 556 The ``author`` element holds the name of the author of the document.
 557
 558
 559 Details
 560 -------
 561
 562 :Category:
 563     `Bibliographic Elements`_
 564
 565 :Parents:
 566     The following elements may contain ``author``: docinfo_, authors_
 567
 568 :Children:
 569     ``author`` elements may contain text data plus `inline elements`_.
 570
 571 :Analogues:
 572     ``author`` is analogous to the DocBook "author" element.
 573
 574 :Processing:
 575     See docinfo_.
 576
 577
 578 Content Model
 579 -------------
 580
 581 .. parsed-literal::
 582
 583     `%text.model;`_
 584
 585 :Attributes:
 586     The ``author`` element contains only the `common attributes`_:
 587     ids_, names_, dupnames_, source_, and classes_.
 588
 589 :Parameter Entities:
 590     The `%bibliographic.elements;`_ parameter entity directly includes
 591     ``author``.
 592
 593
 594 Examples
 595 --------
 596
 597 reStructuredText_ source::
 598
 599     Document Title
 600     ==============
 601
 602     :Author: J. Random Hacker
 603
 604 Complete pseudo-XML_ result after parsing and applying transforms::
 605
 606     <document ids="document-title" names="document title">
 607         <title>
 608             Document Title
 609         <docinfo>
 610             <author>
 611                 J. Random Hacker
 612
 613 See docinfo_ for a more complete example, including processing
 614 context.
 615
 616
 617 ``authors``
 618 ===========
 619
 620 The ``authors`` element is a container for author information for
 621 documents with multiple authors.
 622
 623
 624 Details
 625 -------
 626
 627 :Category:
 628     `Bibliographic Elements`_
 629
 630 :Parents:
 631     Only the docinfo_ element contains ``authors``.
 632
 633 :Children:
 634     ``authors`` elements may contain the following elements: author_,
 635     organization_, address_, contact_
 636
 637 :Analogues:
 638     ``authors`` is analogous to the DocBook "authors" element.
 639
 640 :Processing:
 641     See docinfo_.
 642
 643
 644 Content Model
 645 -------------
 646
 647 .. parsed-literal::
 648
 649     ((author_, organization_?, address_?, contact_?)+)
 650
 651 :Attributes:
 652     The ``authors`` element contains only the `common attributes`_:
 653     ids_, names_, dupnames_, source_, and classes_.
 654
 655 :Parameter Entities:
 656     The `%bibliographic.elements;`_ parameter entity directly includes
 657     ``authors``.
 658
 659
 660 Examples
 661 --------
 662
 663 reStructuredText_ source::
 664
 665     Document Title
 666     ==============
 667
 668     :Authors: J. Random Hacker; Jane Doe
 669
 670 Complete pseudo-XML_ result after parsing and applying transforms::
 671
 672     <document ids="document-title" names="document title">
 673         <title>
 674             Document Title
 675         <docinfo>
 676             <authors>
 677                 <author>
 678                     J. Random Hacker
 679                 <author>
 680                     Jane Doe
 681
 682 In reStructuredText, multiple author's names are separated with
 683 semicolons (";") or commas (","); semicolons take precedence.  There
 684 is currently no way to represent the author's organization, address,
 685 or contact in a reStructuredText "Authors" field.
 686
 687 See docinfo_ for a more complete example, including processing
 688 context.
 689
 690
 691 ``block_quote``
 692 ===============
 693
 694 The ``block_quote`` element is used for quotations set off from the
 695 main text (standalone).
 696
 697
 698 Details
 699 -------
 700
 701 :Category:
 702     `Compound Body Elements`_
 703
 704 :Parents:
 705     All elements employing the `%body.elements;`_ or
 706     `%structure.model;`_ parameter entities in their content models
 707     may contain ``block_quote``.
 708
 709 :Children:
 710     ``block_quote`` elements contain `body elements`_ followed by an
 711     optional attribution_ element.
 712
 713 :Analogues:
 714     ``block_quote`` is analogous to the "blockquote" element in both
 715     HTML and DocBook.
 716
 717 :Processing:
 718     ``block_quote`` elements serve to set their contents off from the
 719     main text, typically with indentation and/or other decoration.
 720
 721
 722 Content Model
 723 -------------
 724
 725 .. parsed-literal::
 726
 727    ((`%body.elements;`_)+, attribution_?)
 728
 729 :Attributes:
 730     The ``block_quote`` element contains only the `common
 731     attributes`_: ids_, names_, dupnames_, source_, and classes_.
 732
 733 :Parameter Entities:
 734     The `%body.elements;`_ parameter entity directly includes
 735     ``block_quote``.  The `%structure.model;`_ parameter entity
 736     indirectly includes ``block_quote``.
 737
 738
 739 Examples
 740 --------
 741
 742 reStructuredText source::
 743
 744     As a great paleontologist once said,
 745
 746         This theory, that is mine, is mine.
 747
 748         -- Anne Elk (Miss)
 749
 750 Pseudo-XML_ fragment from simple parsing::
 751
 752     <paragraph>
 753         As a great paleontologist once said,
 754     <block_quote>
 755         <paragraph>
 756             This theory, that is mine, is mine.
 757         <attribution>
 758             Anne Elk (Miss)
 759
 760
 761 ``bullet_list``
 762 ===============
 763
 764 The ``bullet_list`` element contains list_item_ elements which are
 765 uniformly marked with bullets.  Bullets are typically simple dingbats
 766 (symbols) such as circles and squares.
 767
 768
 769 Details
 770 -------
 771
 772 :Category:
 773     `Compound Body Elements`_
 774
 775 :Parents:
 776     All elements employing the `%body.elements;`_ or
 777     `%structure.model;`_ parameter entities in their content models
 778     may contain ``bullet_list``.
 779
 780 :Children:
 781     ``bullet_list`` elements contain one or more list_item_ elements.
 782
 783 :Analogues:
 784     ``bullet_list`` is analogous to the HTML "ul" element and to the
 785     DocBook "itemizedlist" element.  HTML's "ul" is short for
 786     "unordered list", which we consider to be a misnomer.  "Unordered"
 787     implies that the list items may be randomly rearranged without
 788     affecting the meaning of the list.  Bullet lists *are* often
 789     ordered; the ordering is simply left implicit.
 790
 791 :Processing:
 792     Each list item should begin a new vertical block, prefaced by a
 793     bullet/dingbat.
 794
 795
 796 Content Model
 797 -------------
 798
 799 .. parsed-literal::
 800
 801     (list_item_ +)
 802
 803 :Attributes:
 804     The ``bullet_list`` element contains the `common attributes`_
 805     (ids_, names_, dupnames_, source_, and classes_), plus bullet_.
 806
 807     ``bullet`` is used to record the style of bullet from the input
 808     data.  In documents processed from reStructuredText_, it contains
 809     one of "-", "+", or "*".  It may be ignored in processing.
 810
 811 :Parameter Entities:
 812     The `%body.elements;`_ parameter entity directly includes
 813     ``bullet_list``.  The `%structure.model;`_ parameter entity
 814     indirectly includes ``bullet_list``.
 815
 816
 817 Examples
 818 --------
 819
 820 reStructuredText_ source::
 821
 822     - Item 1, paragraph 1.
 823
 824       Item 1, paragraph 2.
 825
 826     - Item 2.
 827
 828 Pseudo-XML_ fragment from simple parsing::
 829
 830     <bullet_list bullet="-">
 831         <list_item>
 832             <paragraph>
 833                 Item 1, paragraph 1.
 834             <paragraph>
 835                 Item 1, paragraph 2.
 836         <list_item>
 837             <paragraph>
 838                 Item 2.
 839
 840 See list_item_ for another example.
 841
 842
 843 ``caption``
 844 ===========
 845
 846 `To be completed`_.
 847
 848
 849 ``caution``
 850 ===========
 851
 852 The ``caution`` element is an admonition, a distinctive and
 853 self-contained notice.  Also see the other admonition elements
 854 Docutils offers (in alphabetical order): attention_, danger_, error_,
 855 hint_, important_, note_, tip_, warning_, and the generic admonition_.
 856
 857
 858 Details
 859 -------
 860
 861 :Category:
 862     `Compound Body Elements`_
 863
 864 :Parents:
 865     All elements employing the `%body.elements;`_ or
 866     `%structure.model;`_ parameter entities in their content models
 867     may contain ``caution``.
 868
 869 :Children:
 870     ``caution`` elements contain one or more `body elements`_.
 871
 872 :Analogues:
 873     ``caution`` is analogous to the DocBook "caution" element.
 874
 875 :Processing:
 876     Rendered distinctly (inset and/or in a box, etc.), with the
 877     generated title "Caution" (or similar).
 878
 879
 880 Content Model
 881 -------------
 882
 883 .. parsed-literal::
 884
 885    (`%body.elements;`_)+
 886
 887 :Attributes:
 888     The ``caution`` element contains only the `common attributes`_:
 889     ids_, names_, dupnames_, source_, and classes_.
 890
 891 :Parameter Entities:
 892     The `%body.elements;`_ parameter entity directly includes
 893     ``caution``.  The `%structure.model;`_ parameter entity
 894     indirectly includes ``caution``.
 895
 896
 897 Examples
 898 --------
 899
 900 reStructuredText source::
 901
 902     .. Caution:: Don't take any wooden nickels.
 903
 904 Pseudo-XML_ fragment from simple parsing::
 905
 906     <caution>
 907         <paragraph>
 908             Don't take any wooden nickels.
 909
 910
 911 ``citation``
 912 ============
 913
 914 `To be completed`_.
 915
 916
 917 ``citation_reference``
 918 ======================
 919
 920 `To be completed`_.
 921
 922
 923 ``classifier``
 924 ==============
 925
 926 The ``classifier`` element contains the classification or type of the
 927 term_ being defined in a definition_list_.  For example, it can be
 928 used to indicate the type of a variable.
 929
 930
 931 Details
 932 -------
 933
 934 :Category:
 935     `Body Subelements`_ (simple)
 936
 937 :Parents:
 938     Only the definition_list_item_ element contains ``classifier``.
 939
 940 :Children:
 941     ``classifier`` elements may contain text data plus `inline elements`_.
 942
 943 :Analogues:
 944     ``classifier`` has no direct analogues in common DTDs.  It can be
 945     emulated with primitives or type effects.
 946
 947 :Processing:
 948     See definition_list_item_.
 949
 950
 951 Content Model
 952 -------------
 953
 954 .. parsed-literal::
 955
 956     `%text.model;`_
 957
 958 :Attributes:
 959     The ``classifier`` element contains only the `common attributes`_:
 960     ids_, names_, dupnames_, source_, and classes_.
 961
 962
 963 Examples
 964 --------
 965
 966 Here is a hypothetical data dictionary.  reStructuredText_ source::
 967
 968     name : string
 969         Customer name.
 970     i : int
 971         Temporary index variable.
 972
 973 Pseudo-XML_ fragment from simple parsing::
 974
 975     <definition_list>
 976         <definition_list_item>
 977             <term>
 978                 name
 979             <classifier>
 980                 string
 981             <definition>
 982                 <paragraph>
 983                     Customer name.
 984         <definition_list_item>
 985             <term>
 986                 i
 987             <classifier>
 988                 int
 989             <definition>
 990                 <paragraph>
 991                     Temporary index variable.
 992
 993
 994 ``colspec``
 995 ===========
 996
 997 :Attributes:
 998     The ``colspec`` element contains the `common attributes`_ (ids_,
 999     names_, dupnames_, source_, and classes_), plus `stub`_.
1000
1001
1002 `To be completed`_.
1003
1004
1005 ``comment``
1006 ===========
1007
1008 `To be completed`_.
1009
1010
1011 ``compound``
1012 ============
1013
1014 `To be completed`_.
1015
1016
1017 ``contact``
1018 ===========
1019
1020 The ``contact`` element holds contact information for the author
1021 (individual or group) of the document, or a third-party contact.  It
1022 is typically used for an email or web address.
1023
1024
1025 Details
1026 -------
1027
1028 :Category:
1029     `Bibliographic Elements`_
1030
1031 :Parents:
1032     The following elements may contain ``contact``: docinfo_, authors_
1033
1034 :Children:
1035     ``contact`` elements may contain text data plus `inline
1036     elements`_.
1037
1038 :Analogues:
1039     ``contact`` is analogous to the DocBook "email" element.  The HTML
1040     "address" element serves a similar purpose.
1041
1042 :Processing:
1043     See docinfo_.
1044
1045
1046 Content Model
1047 -------------
1048
1049 .. parsed-literal::
1050
1051     `%text.model;`_
1052
1053 :Attributes:
1054     The ``contact`` element contains only the `common attributes`_:
1055     ids_, names_, dupnames_, source_, and classes_.
1056
1057 :Parameter Entities:
1058     The `%bibliographic.elements;`_ parameter entity directly includes
1059     ``contact``.
1060
1061
1062 Examples
1063 --------
1064
1065 reStructuredText_ source::
1066
1067     Document Title
1068     ==============
1069
1070     :Contact: jrh@example.com
1071
1072 Complete pseudo-XML_ result after parsing and applying transforms::
1073
1074     <document ids="document-title" names="document title">
1075         <title>
1076             Document Title
1077         <docinfo>
1078             <contact>
1079                 <reference refuri="mailto:jrh@example.com">
1080                     jrh@example.com
1081
1082 See docinfo_ for a more complete example, including processing
1083 context.
1084
1085
1086 ``container``
1087 =============
1088
1089 `To be completed`_.
1090
1091
1092 ``copyright``
1093 =============
1094
1095 The ``copyright`` element contains the document's copyright statement.
1096
1097
1098 Details
1099 -------
1100
1101 :Category:
1102     `Bibliographic Elements`_
1103
1104 :Parents:
1105     Only the docinfo_ element contains ``copyright``.
1106
1107 :Children:
1108     ``copyright`` elements may contain text data plus `inline
1109     elements`_.
1110
1111 :Analogues:
1112     ``copyright`` is analogous to the DocBook "copyright" element.
1113
1114 :Processing:
1115     See docinfo_.
1116
1117
1118 Content Model
1119 -------------
1120
1121 .. parsed-literal::
1122
1123     `%text.model;`_
1124
1125 :Attributes:
1126     The ``copyright`` element contains only the `common attributes`_:
1127     ids_, names_, dupnames_, source_, and classes_.
1128
1129 :Parameter Entities:
1130     The `%bibliographic.elements;`_ parameter entity directly includes
1131     ``copyright``.
1132
1133
1134 Examples
1135 --------
1136
1137 reStructuredText_ source::
1138
1139     Document Title
1140     ==============
1141
1142     :Copyright: This document has been placed in the public domain.
1143
1144 Complete pseudo-XML_ result after parsing and applying transforms::
1145
1146     <document ids="document-title" names="document title">
1147         <title>
1148             Document Title
1149         <docinfo>
1150             <copyright>
1151                 This document has been placed in the public domain.
1152
1153 See docinfo_ for a more complete example, including processing
1154 context.
1155
1156
1157 ``danger``
1158 ==========
1159
1160 The ``danger`` element is an admonition, a distinctive and
1161 self-contained notice.  Also see the other admonition elements
1162 Docutils offers (in alphabetical order): attention_, caution_, error_,
1163 hint_, important_, note_, tip_, warning_, and the generic admonition_.
1164
1165
1166 Details
1167 -------
1168
1169 :Category:
1170     `Compound Body Elements`_
1171
1172 :Parents:
1173     All elements employing the `%body.elements;`_ or
1174     `%structure.model;`_ parameter entities in their content models
1175     may contain ``danger``.
1176
1177 :Children:
1178     ``danger`` elements contain one or more `body elements`_.
1179
1180 :Analogues:
1181     ``danger`` has no direct analogues in common DTDs.  It can be
1182     emulated with primitives and type effects.
1183
1184 :Processing:
1185     Rendered distinctly (inset and/or in a box, etc.), with the
1186     generated title "!DANGER!" (or similar).
1187
1188
1189 Content Model
1190 -------------
1191
1192 .. parsed-literal::
1193
1194    (`%body.elements;`_)+
1195
1196 :Attributes:
1197     The ``danger`` element contains only the `common attributes`_:
1198     ids_, names_, dupnames_, source_, and classes_.
1199
1200 :Parameter Entities:
1201     The `%body.elements;`_ parameter entity directly includes
1202     ``danger``.  The `%structure.model;`_ parameter entity
1203     indirectly includes ``danger``.
1204
1205
1206 Examples
1207 --------
1208
1209 reStructuredText source::
1210
1211     .. DANGER:: Mad scientist at work!
1212
1213 Pseudo-XML_ fragment from simple parsing::
1214
1215     <danger>
1216         <paragraph>
1217             Mad scientist at work!
1218
1219
1220 ``date``
1221 ========
1222
1223 The ``date`` element contains the date of publication, release, or
1224 last modification of the document.
1225
1226
1227 Details
1228 -------
1229
1230 :Category:
1231     `Bibliographic Elements`_
1232
1233 :Parents:
1234     Only the docinfo_ element contains ``date``.
1235
1236 :Children:
1237     ``date`` elements may contain text data plus `inline elements`_.
1238
1239 :Analogues:
1240     ``date`` is analogous to the DocBook "date" element.
1241
1242 :Processing:
1243     Often used with the RCS/CVS keyword "Date".  See docinfo_.
1244
1245
1246 Content Model
1247 -------------
1248
1249 .. parsed-literal::
1250
1251     `%text.model;`_
1252
1253 :Attributes:
1254     The ``date`` element contains only the `common attributes`_:
1255     ids_, names_, dupnames_, source_, and classes_.
1256
1257 :Parameter Entities:
1258     The `%bibliographic.elements;`_ parameter entity directly includes
1259     ``date``.
1260
1261
1262 Examples
1263 --------
1264
1265 reStructuredText_ source::
1266
1267     Document Title
1268     ==============
1269
1270     :Date: 2002-08-20
1271
1272 Complete pseudo-XML_ result after parsing and applying transforms::
1273
1274     <document ids="document-title" names="document title">
1275         <title>
1276             Document Title
1277         <docinfo>
1278             <date>
1279                 2002-08-20
1280
1281 See docinfo_ for a more complete example, including processing
1282 context.
1283
1284
1285 ``decoration``
1286 ==============
1287
1288 The ``decoration`` element is a container for header_ and footer_
1289 elements and potential future extensions.  These elements are used for
1290 notes, time/datestamp, processing information, etc.
1291
1292
1293 Details
1294 -------
1295
1296 :Category:
1297     `Structural Subelements`_
1298
1299 :Parents:
1300     Only the document_ element contains ``decoration``.
1301
1302 :Children:
1303     ``decoration`` elements may contain `decorative elements`_.
1304
1305 :Analogues:
1306     There are no direct analogies to ``decoration`` in HTML or in
1307     DocBook.  Equivalents are typically constructed from primitives
1308     and/or generated by the processing system.
1309
1310 :Processing:
1311     See the individual `decorative elements`_.
1312
1313
1314 Content Model
1315 -------------
1316
1317 .. parsed-literal::
1318
1319     (header_?, footer_?)
1320
1321 Although the content model doesn't specifically require contents, no
1322 empty ``decoration`` elements are ever created.
1323
1324 :Attributes:
1325     The ``decoration`` element contains only the `common attributes`_:
1326     ids_, names_, dupnames_, source_, and classes_.
1327
1328
1329 Examples
1330 --------
1331
1332 reStructuredText_ source::
1333
1334     A paragraph.
1335
1336 Complete pseudo-XML_ result after parsing and applying transforms,
1337 assuming that the datestamp command-line option or configuration
1338 setting has been supplied::
1339
1340     <document>
1341         <decoration>
1342             <footer>
1343                 <paragraph>
1344                     Generated on: 2002-08-20.
1345         <paragraph>
1346             A paragraph.
1347
1348
1349 ``definition``
1350 ==============
1351
1352 The ``definition`` element is a container for the body elements used
1353 to define a term_ in a definition_list_.
1354
1355
1356 Details
1357 -------
1358
1359 :Category:
1360     `Body Subelements`_ (compound)
1361
1362 :Parents:
1363     Only definition_list_item_ elements contain ``definition``.
1364
1365 :Children:
1366     ``definition`` elements may contain `body elements`_.
1367
1368 :Analogues:
1369     ``definition`` is analogous to the HTML "dd" element and to the
1370     DocBook "listitem" element (inside a "variablelistentry" element).
1371
1372 :Processing:
1373     See definition_list_item_.
1374
1375
1376 Content Model
1377 -------------
1378
1379 .. parsed-literal::
1380
1381     (`%body.elements;`_)+
1382
1383 :Attributes:
1384     The ``definition`` element contains only the `common attributes`_:
1385     ids_, names_, dupnames_, source_, and classes_.
1386
1387
1388 Examples
1389 --------
1390
1391 See the examples for the definition_list_, definition_list_item_, and
1392 classifier_ elements.
1393
1394
1395 ``definition_list``
1396 ===================
1397
1398 The ``definition_list`` element contains a list of terms and their
1399 definitions.  It can be used for glossaries or dictionaries, to
1400 describe or classify things, for dialogues, or to itemize subtopics
1401 (such as in this reference).
1402
1403
1404 Details
1405 -------
1406
1407 :Category:
1408     `Compound Body Elements`_
1409
1410 :Parents:
1411     All elements employing the `%body.elements;`_ or
1412     `%structure.model;`_ parameter entities in their content models
1413     may contain ``definition_list``.
1414
1415 :Children:
1416     ``definition_list`` elements contain one or more
1417     definition_list_item_ elements.
1418
1419 :Analogues:
1420     ``definition_list`` is analogous to the HTML "dl" element and to
1421     the DocBook "variablelist" element.
1422
1423 :Processing:
1424     See definition_list_item_.
1425
1426
1427 Content Model
1428 -------------
1429
1430 .. parsed-literal::
1431
1432     (definition_list_item_ +)
1433
1434 :Attributes:
1435     The ``definition_list`` element contains only the `common
1436     attributes`_: ids_, names_, dupnames_, source_, and classes_.
1437
1438 :Parameter Entities:
1439     The `%body.elements;`_ parameter entity directly includes
1440     ``definition_list``.  The `%structure.model;`_ parameter entity
1441     indirectly includes ``definition_list``.
1442
1443
1444 Examples
1445 --------
1446
1447 reStructuredText_ source::
1448
1449     Term
1450       Definition.
1451
1452     Term : classifier
1453         The ' : ' indicates a classifier in
1454         definition list item terms only.
1455
1456 Pseudo-XML_ fragment from simple parsing::
1457
1458     <definition_list>
1459         <definition_list_item>
1460             <term>
1461                 Term
1462             <definition>
1463                 <paragraph>
1464                     Definition.
1465         <definition_list_item>
1466             <term>
1467                 Term
1468             <classifier>
1469                 classifier
1470             <definition>
1471                 <paragraph>
1472                     The ' : ' indicates a classifier in
1473                     definition list item terms only.
1474
1475 See definition_list_item_ and classifier_ for further examples.
1476
1477
1478 ``definition_list_item``
1479 ========================
1480
1481 The ``definition_list_item`` element contains a single
1482 term_/definition_ pair (with optional classifier_).
1483
1484
1485 Details
1486 -------
1487
1488 :Category:
1489     `Body Subelements`_ (compound)
1490
1491 :Parents:
1492     Only the definition_list_ element contains
1493     ``definition_list_item``.
1494
1495 :Children:
1496     ``definition_list_item`` elements each contain a single term_,
1497     an optional classifier_, and a definition_.
1498
1499 :Analogues:
1500     ``definition_list_item`` is analogous to the DocBook
1501     "variablelistentry" element.
1502
1503 :Processing:
1504     The optional classifier_ can be rendered differently from the
1505     term_.  They should be separated visually, typically by spaces
1506     plus a colon or dash.
1507
1508
1509 Content Model
1510 -------------
1511
1512 .. parsed-literal::
1513
1514     (term_, classifier_?, definition_)
1515
1516 :Attributes:
1517     The ``definition_list_item`` element contains only the `common
1518     attributes`_: ids_, names_, dupnames_, source_, and classes_.
1519
1520
1521 Examples
1522 --------
1523
1524 reStructuredText_ source::
1525
1526     Tyrannosaurus Rex : carnivore
1527         Big and scary; the "Tyrant King".
1528
1529     Brontosaurus : herbivore
1530         All brontosauruses are thin at one end,
1531         much much thicker in the middle
1532         and then thin again at the far end.
1533
1534         -- Anne Elk (Miss)
1535
1536 Pseudo-XML_ fragment from simple parsing::
1537
1538     <definition_list>
1539         <definition_list_item>
1540             <term>
1541                 Tyrannosaurus Rex
1542             <classifier>
1543                 carnivore
1544             <definition>
1545                 <paragraph>
1546                     Big and scary; the "Tyrant King".
1547         <definition_list_item>
1548             <term>
1549                 Brontosaurus
1550             <classifier>
1551                 herbivore
1552             <definition>
1553                 <paragraph>
1554                     All brontosauruses are thin at one end,
1555                     much much thicker in the middle
1556                     and then thin again at the far end.
1557                 <paragraph>
1558                     -- Anne Elk (Miss)
1559
1560 See definition_list_ and classifier_ for further examples.
1561
1562
1563 ``description``
1564 ===============
1565
1566 The ``description`` element contains body elements, describing the
1567 purpose or effect of a command-line option or group of options.
1568
1569
1570 Details
1571 -------
1572
1573 :Category:
1574     `Body Subelements`_
1575
1576 :Parents:
1577     Only the option_list_item_ element contains ``description``.
1578
1579 :Children:
1580     ``description`` elements may contain `body elements`_.
1581
1582 :Analogues:
1583     ``description`` has no direct analogues in common DTDs.
1584
1585 :Processing:
1586     See option_list_.
1587
1588
1589 Content Model
1590 -------------
1591
1592 .. parsed-literal::
1593
1594    (`%body.elements;`_)+
1595
1596 :Attributes:
1597     The ``description`` element contains only the `common attributes`_:
1598     ids_, names_, dupnames_, source_, and classes_.
1599
1600
1601 Examples
1602 --------
1603
1604 See the examples for the option_list_ element.
1605
1606
1607 ``docinfo``
1608 ===========
1609
1610 The ``docinfo`` element is a container for document bibliographic
1611 data, or meta-data (data about the document).  It corresponds to the
1612 front matter of a book, such as the title page and copyright page.
1613
1614
1615 Details
1616 -------
1617
1618 :Category:
1619     `Structural Subelements`_
1620
1621 :Parents:
1622     Only the document_ element contains ``docinfo``.
1623
1624 :Children:
1625     ``docinfo`` elements contain `bibliographic elements`_.
1626
1627 :Analogues:
1628     ``docinfo`` is analogous to DocBook "info" elements ("bookinfo"
1629     etc.).  There are no directly analogous HTML elements; the "meta"
1630     element carries some of the same information, albeit invisibly.
1631
1632 :Processing:
1633     The ``docinfo`` element may be rendered as a two-column table or
1634     in other styles.  It may even be invisible or omitted from the
1635     processed output.  Meta-data may be extracted from ``docinfo``
1636     children; for example, HTML ``<meta>`` tags may be constructed.
1637
1638     When Docutils_ transforms a reStructuredText_ field_list_ into a
1639     ``docinfo`` element (see the examples below), RCS/CVS keywords are
1640     normally stripped from simple (one paragraph) field bodies.  For
1641     complete details, please see `RCS Keywords`_ in the
1642     `reStructuredText Markup Specification`_.
1643
1644     .. _RCS Keywords: rst/restructuredtext.html#rcs-keywords
1645
1646
1647 Content Model
1648 -------------
1649
1650 .. parsed-literal::
1651
1652     (`%bibliographic.elements;`_)+
1653
1654 :Attributes:
1655     The ``docinfo`` element contains only the `common attributes`_:
1656     ids_, names_, dupnames_, source_, and classes_.
1657
1658
1659 Examples
1660 --------
1661
1662 Docinfo is represented in reStructuredText_ by a field_list_ in a
1663 bibliographic context: the first non-comment element of a document_,
1664 after any document title_/subtitle_.  The field list is transformed
1665 into a ``docinfo`` element and its children by a transform.  Source::
1666
1667     Docinfo Example
1668     ===============
1669
1670     :Author: J. Random Hacker
1671     :Contact: jrh@example.com
1672     :Date: 2002-08-18
1673     :Status: Work In Progress
1674     :Version: 1
1675     :Filename: $RCSfile$
1676     :Copyright: This document has been placed in the public domain.
1677
1678 Complete pseudo-XML_ result after parsing and applying transforms::
1679
1680     <document ids="docinfo-example" names="docinfo example">
1681         <title>
1682             Docinfo Example
1683         <docinfo>
1684             <author>
1685                 J. Random Hacker
1686             <contact>
1687                 <reference refuri="mailto:jrh@example.com">
1688                     jrh@example.com
1689             <date>
1690                 2002-08-18
1691             <status>
1692                 Work In Progress
1693             <version>
1694                 1
1695             <field>
1696                 <field_name>
1697                     Filename
1698                 <field_body>
1699                     <paragraph>
1700                         doctree.txt
1701             <copyright>
1702                 This document has been placed in the public domain.
1703
1704 Note that "Filename" is a non-standard ``docinfo`` field, so becomes a
1705 generic ``field`` element.  Also note that the "RCSfile" keyword
1706 syntax has been stripped from the "Filename" data.
1707
1708 See field_list_ for an example in a non-bibliographic context.  Also
1709 see the individual examples for the various `bibliographic elements`_.
1710
1711
1712 ``doctest_block``
1713 =================
1714
1715 The ``doctest_block`` element is a Python-specific variant of
1716 literal_block_.  It is a block of text where line breaks and
1717 whitespace are significant and must be preserved.  ``doctest_block``
1718 elements are used for interactive Python interpreter sessions, which
1719 are distinguished by their input prompt: ``>>>``.  They are meant to
1720 illustrate usage by example, and provide an elegant and powerful
1721 testing environment via the `doctest module`_ in the Python standard
1722 library.
1723
1724 .. _doctest module:
1725    http://www.python.org/doc/current/lib/module-doctest.html
1726
1727
1728 Details
1729 -------
1730
1731 :Category:
1732     `Simple Body Elements`_
1733
1734 :Parents:
1735     All elements employing the `%body.elements;`_ or
1736     `%structure.model;`_ parameter entities in their content models
1737     may contain ``doctest_block``.
1738
1739 :Children:
1740     ``doctest_block`` elements may contain text data plus `inline
1741     elements`_.
1742
1743 :Analogues:
1744     ``doctest_block`` is analogous to the HTML "pre" element and to
1745     the DocBook "programlisting" and "screen" elements.
1746
1747 :Processing:
1748     As with literal_block_, ``doctest_block`` elements are typically
1749     rendered in a monospaced typeface.  It is crucial that all
1750     whitespace and line breaks are preserved in the rendered form.
1751
1752
1753 Content Model
1754 -------------
1755
1756 .. parsed-literal::
1757
1758    `%text.model;`_
1759
1760 :Attributes:
1761     The ``doctest_block`` element contains the `common attributes`_
1762     (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_.
1763
1764 :Parameter Entities:
1765     The `%body.elements;`_ parameter entity directly includes
1766     ``doctest_block``.  The `%structure.model;`_ parameter entity
1767     indirectly includes ``doctest_block``.
1768
1769
1770 Examples
1771 --------
1772
1773 reStructuredText source::
1774
1775     This is an ordinary paragraph.
1776
1777     >>> print 'this is a Doctest block'
1778     this is a Doctest block
1779
1780 Pseudo-XML_ fragment from simple parsing::
1781
1782     <paragraph>
1783         This is an ordinary paragraph.
1784     <doctest_block xml:space="preserve">
1785         >>> print 'this is a Doctest block'
1786         this is a Doctest block
1787
1788
1789 ``document``
1790 ============
1791
1792 The ``document`` element is the root (topmost) element of the Docutils
1793 document tree.  ``document`` is the direct or indirect ancestor of
1794 every other element in the tree.  It encloses the entire document
1795 tree.  It is the starting point for a document.
1796
1797
1798 Details
1799 -------
1800
1801 :Category:
1802     `Structural Elements`_
1803
1804 :Parents:
1805     The ``document`` element has no parents.
1806
1807 :Children:
1808     ``document`` elements may contain `structural subelements`_,
1809     `structural elements`_, and `body elements`_.
1810
1811 :Analogues:
1812     ``document`` is analogous to the HTML "html" element and to
1813     several DocBook elements such as "book".
1814
1815
1816 Content Model
1817 -------------
1818
1819 .. parsed-literal::
1820
1821     ( (title_, subtitle_?)?,
1822       decoration_?,
1823       (docinfo_, transition_?)?,
1824       `%structure.model;`_ )
1825
1826 Depending on the source of the data and the stage of processing, the
1827 "document" may not initially contain a "title".  A document title is
1828 not directly representable in reStructuredText_.  Instead, a lone
1829 top-level section may have its title promoted to become the document
1830 title_, and similarly for a lone second-level (sub)section's title to
1831 become the document subtitle_.
1832
1833 The contents of "decoration_" may be specified in a document,
1834 constructed programmatically, or both.  The "docinfo_" may be
1835 transformed from an initial field_list_.
1836
1837 See the `%structure.model;`_ parameter entity for details of the body
1838 of a ``document``.
1839
1840 :Attributes:
1841     The ``document`` element contains the `common attributes`_ (ids_,
1842     names_, dupnames_, source_, and classes_), plus an optional title__
1843     attribute which stores the document title metadata.
1844
1845     __ `title (attribute)`_
1846
1847
1848 Examples
1849 --------
1850
1851 reStructuredText_ source::
1852
1853     A Title
1854     =======
1855
1856     A paragraph.
1857
1858 Complete pseudo-XML_ result from simple parsing::
1859
1860     <document>
1861         <section ids="a-title" names="a title">
1862             <title>
1863                 A Title
1864             <paragraph>
1865                 A paragraph.
1866
1867 After applying transforms, the section title is promoted to become the
1868 document title::
1869
1870     <document ids="a-title" names="a title">
1871         <title>
1872             A Title
1873         <paragraph>
1874             A paragraph.
1875
1876
1877 ``emphasis``
1878 ============
1879
1880 `To be completed`_.
1881
1882
1883 ``entry``
1884 =========
1885
1886 `To be completed`_.
1887
1888
1889 ``enumerated_list``
1890 ===================
1891
1892 The ``enumerated_list`` element contains list_item_ elements which are
1893 uniformly marked with enumerator labels.
1894
1895
1896 Details
1897 -------
1898
1899 :Category:
1900     `Compound Body Elements`_
1901
1902 :Parents:
1903     All elements employing the `%body.elements;`_ or
1904     `%structure.model;`_ parameter entities in their content models
1905     may contain ``enumerated_list``.
1906
1907 :Children:
1908     ``enumerated_list`` elements contain one or more list_item_
1909     elements.
1910
1911 :Analogues:
1912     ``enumerated_list`` is analogous to the HTML "ol" element and to
1913     the DocBook "orderedlist" element.
1914
1915 :Processing:
1916     Each list item should begin a new vertical block, prefaced by a
1917     enumeration marker (such as "1.").
1918
1919
1920 Content Model
1921 -------------
1922
1923 .. parsed-literal::
1924
1925     (list_item_ +)
1926
1927 :Attributes:
1928     The ``enumerated_list`` element contains the `common attributes`_
1929     (ids_, names_, dupnames_, source_, and classes_), plus enumtype_,
1930     prefix_, suffix_, and start_.
1931
1932     ``enumtype`` is used to record the intended enumeration sequence,
1933     one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z),
1934     "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ...,
1935     mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ...,
1936     MMMMCMXCIX [4999]).
1937
1938     ``prefix`` stores the formatting characters used before the
1939     enumerator.  In documents originating from reStructuredText_ data,
1940     it will contain either "" (empty string) or "(" (left
1941     parenthesis).  It may or may not affect processing.
1942
1943     ``suffix`` stores the formatting characters used after the
1944     enumerator.  In documents originating from reStructuredText_ data,
1945     it will contain either "." (period) or ")" (right parenthesis).
1946     Depending on the capabilities of the output format, this attribute
1947     may or may not affect processing.
1948
1949     ``start`` contains the ordinal value of the first item in the
1950     list, in decimal.  For lists beginning at value 1 ("1", "a", "A",
1951     "i", or "I"), this attribute may be omitted.
1952
1953 :Parameter Entities:
1954     The `%body.elements;`_ parameter entity directly includes
1955     ``enumerated_list``.  The `%structure.model;`_ parameter entity
1956     indirectly includes ``enumerated_list``.
1957
1958
1959 Examples
1960 --------
1961
1962 reStructuredText_ source::
1963
1964     1. Item 1.
1965
1966        (A) Item A.
1967        (B) Item B.
1968        (C) Item C.
1969
1970     2. Item 2.
1971
1972 Pseudo-XML_ fragment from simple parsing::
1973
1974     <enumerated_list enumtype="arabic" prefix="" suffix=".">
1975         <list_item>
1976             <paragraph>
1977                 Item 1.
1978             <enumerated_list enumtype="upperalpha" prefix="(" suffix=")">
1979                 <list_item>
1980                     <paragraph>
1981                         Item A.
1982                 <list_item>
1983                     <paragraph>
1984                         Item B.
1985                 <list_item>
1986                     <paragraph>
1987                         Item C.
1988         <list_item>
1989             <paragraph>
1990                 Item 2.
1991
1992 See list_item_ for another example.
1993
1994
1995 ``error``
1996 =========
1997
1998 The ``error`` element is an admonition, a distinctive and
1999 self-contained notice.  Also see the other admonition elements
2000 Docutils offers (in alphabetical order): attention_, caution_,
2001 danger_, hint_, important_, note_, tip_, warning_, and the generic
2002 admonition_.
2003
2004
2005 Details
2006 -------
2007
2008 :Category:
2009     `Compound Body Elements`_
2010
2011 :Parents:
2012     All elements employing the `%body.elements;`_ or
2013     `%structure.model;`_ parameter entities in their content models
2014     may contain ``error``.
2015
2016 :Children:
2017     ``error`` elements contain one or more `body elements`_.
2018
2019 :Analogues:
2020     ``error`` has no direct analogues in common DTDs.  It can be
2021     emulated with primitives and type effects.
2022
2023 :Processing:
2024     Rendered distinctly (inset and/or in a box, etc.), with the
2025     generated title "Error" (or similar).
2026
2027
2028 Content Model
2029 -------------
2030
2031 .. parsed-literal::
2032
2033    (`%body.elements;`_)+
2034
2035 :Attributes:
2036     The ``error`` element contains only the `common attributes`_: ids_,
2037     names_, dupnames_, source_, and classes_.
2038
2039 :Parameter Entities:
2040     The `%body.elements;`_ parameter entity directly includes
2041     ``error``.  The `%structure.model;`_ parameter entity indirectly
2042     includes ``error``.
2043
2044
2045 Examples
2046 --------
2047
2048 reStructuredText source::
2049
2050     .. Error:: Does not compute.
2051
2052 Pseudo-XML_ fragment from simple parsing::
2053
2054     <error>
2055         <paragraph>
2056             Does not compute.
2057
2058
2059 ``field``
2060 =========
2061
2062 The ``field`` element contains a pair of field_name_ and field_body_
2063 elements.
2064
2065
2066 Details
2067 -------
2068
2069 :Category:
2070     `Body Subelements`_
2071
2072 :Parents:
2073     The following elements may contain ``field``: docinfo_,
2074     field_list_
2075
2076 :Children:
2077     Each ``field`` element contains one field_name_ and one
2078     field_body_ element.
2079
2080 :Analogues:
2081     ``field`` has no direct analogues in common DTDs.
2082
2083 :Processing:
2084     See field_list_.
2085
2086
2087 Content Model
2088 -------------
2089
2090 .. parsed-literal::
2091
2092    (field_name_, field_body_)
2093
2094 :Attributes:
2095     The ``field`` element contains only the `common attributes`_:
2096     ids_, names_, dupnames_, source_, and classes_.
2097
2098 :Parameter Entities:
2099     The `%bibliographic.elements;`_ parameter entity directly includes
2100     ``field``.
2101
2102
2103 Examples
2104 --------
2105
2106 See the examples for the field_list_ and docinfo_ elements.
2107
2108
2109 ``field_body``
2110 ==============
2111
2112 The ``field_body`` element contains body elements.  It is analogous to
2113 a database field's data.
2114
2115
2116 Details
2117 -------
2118
2119 :Category:
2120     `Body Subelements`_
2121
2122 :Parents:
2123     Only the field_ element contains ``field_body``.
2124
2125 :Children:
2126     ``field_body`` elements may contain `body elements`_.
2127
2128 :Analogues:
2129     ``field_body`` has no direct analogues in common DTDs.
2130
2131 :Processing:
2132     See field_list_.
2133
2134
2135 Content Model
2136 -------------
2137
2138 .. parsed-literal::
2139
2140    (`%body.elements;`_)*
2141
2142 :Attributes:
2143     The ``field_body`` element contains only the `common attributes`_:
2144     ids_, names_, dupnames_, source_, and classes_.
2145
2146
2147 Examples
2148 --------
2149
2150 See the examples for the field_list_ and docinfo_ elements.
2151
2152
2153 ``field_list``
2154 ==============
2155
2156 The ``field_list`` element contains two-column table-like structures
2157 resembling database records (label & data pairs).  Field lists are
2158 often meant for further processing.  In reStructuredText_, field lists
2159 are used to represent bibliographic fields (contents of the docinfo_
2160 element) and `directive options`_.
2161
2162 Details
2163 -------
2164
2165 :Category:
2166     `Compound Body Elements`_
2167
2168 :Parents:
2169     All elements employing the `%body.elements;`_ or
2170     `%structure.model;`_ parameter entities in their content models
2171     may contain ``field_list``.
2172
2173 :Children:
2174     ``field_list`` elements contain one or more field_ elements.
2175
2176 :Analogues:
2177     ``field_list`` has no direct analogues in common DTDs.  It can be
2178     emulated with primitives such as tables.
2179
2180 :Processing:
2181     A ``field_list`` is typically rendered as a two-column list, where
2182     the first column contains "labels" (usually with a colon suffix).
2183     However, field lists are often used for extension syntax or
2184     special processing.  Such structures do not survive as field lists
2185     to be rendered.
2186
2187
2188 Content Model
2189 -------------
2190
2191 .. parsed-literal::
2192
2193    (field_ +)
2194
2195 :Attributes:
2196     The ``field_list`` element contains only the `common attributes`_:
2197     ids_, names_, dupnames_, source_, and classes_.
2198
2199 :Parameter Entities:
2200     The `%body.elements;`_ parameter entity directly includes
2201     ``field_list``.  The `%structure.model;`_ parameter entity
2202     indirectly includes ``field_list``.
2203
2204
2205 Examples
2206 --------
2207
2208 reStructuredText_ source::
2209
2210     :Author: Me
2211     :Version: 1
2212     :Date: 2001-08-11
2213     :Parameter i: integer
2214
2215 Pseudo-XML_ fragment from simple parsing::
2216
2217     <field_list>
2218         <field>
2219             <field_name>
2220                 Author
2221             <field_body>
2222                 <paragraph>
2223                     Me
2224         <field>
2225             <field_name>
2226                 Version
2227             <field_body>
2228                 <paragraph>
2229                     1
2230         <field>
2231             <field_name>
2232                 Date
2233             <field_body>
2234                 <paragraph>
2235                     2001-08-11
2236         <field>
2237             <field_name>
2238                 Parameter i
2239             <field_body>
2240                 <paragraph>
2241                     integer
2242
2243 .. _directive options: rst/restructuredtext.html#directive-options
2244
2245
2246 ``field_name``
2247 ==============
2248
2249 The ``field_name`` element contains text; it is analogous to a
2250 database field's name.
2251
2252
2253 Details
2254 -------
2255
2256 :Category:
2257     `Body Subelements`_ (simple)
2258
2259 :Parents:
2260     Only the field_ element contains ``field_name``.
2261
2262 :Children:
2263     ``field_name`` elements may contain text data plus `inline elements`_.
2264
2265 :Analogues:
2266     ``field_name`` has no direct analogues in common DTDs.
2267
2268 :Processing:
2269     See field_list_.
2270
2271
2272 Content Model
2273 -------------
2274
2275 .. parsed-literal::
2276
2277     `%text.model;`_
2278
2279 :Attributes:
2280     The ``field_name`` element contains only the `common attributes`_:
2281     ids_, names_, dupnames_, source_, and classes_.
2282
2283
2284 Examples
2285 --------
2286
2287 See the examples for the field_list_ and docinfo_ elements.
2288
2289
2290 ``figure``
2291 ==========
2292
2293 `To be completed`_.
2294
2295
2296 ``footer``
2297 ==========
2298
2299 The ``footer`` element is a container element whose contents are meant
2300 to appear at the bottom of a web page, or repeated at the bottom of
2301 every printed page.  The ``footer`` element may contain processing
2302 information (datestamp, a link to Docutils_, etc.) as well as custom
2303 content.
2304
2305
2306 Details
2307 -------
2308
2309 :Category:
2310     `Decorative Elements`_
2311
2312 :Parents:
2313     Only the decoration_ element contains ``footer``.
2314
2315 :Children:
2316     ``footer`` elements may contain `body elements`_.
2317
2318 :Analogues:
2319     ``footer`` is analogous to the HTML5 "footer" element
2320     There are no direct analogies to ``footer`` in HTML4 or DocBook.
2321     Equivalents are typically constructed from primitives and/or
2322     generated by the processing system.
2323
2324
2325 Content Model
2326 -------------
2327
2328 .. parsed-literal::
2329
2330     (`%body.elements;`_)+
2331
2332 :Attributes:
2333     The ``footer`` element contains only the `common attributes`_:
2334     ids_, names_, dupnames_, source_, and classes_.
2335
2336
2337 Examples
2338 --------
2339
2340 reStructuredText_ source::
2341
2342     A paragraph.
2343
2344 Complete pseudo-XML_ result after parsing and applying transforms,
2345 assuming that the datestamp command-line option or configuration
2346 setting has been supplied::
2347
2348     <document>
2349         <decoration>
2350             <footer>
2351                 <paragraph>
2352                     Generated on: 2002-08-20.
2353         <paragraph>
2354             A paragraph.
2355
2356
2357 ``footnote``
2358 ============
2359
2360 `To be completed`_.
2361
2362
2363 ``footnote_reference``
2364 ======================
2365
2366 `To be completed`_.
2367
2368
2369 ``generated``
2370 =============
2371
2372 Docutils wraps ``generated`` elements around text that is inserted
2373 (generated) by Docutils; i.e., text that was not in the document, like
2374 section numbers inserted by the "sectnum" directive.
2375
2376 `To be completed`_.
2377
2378
2379 ``header``
2380 ==========
2381
2382 The ``header`` element is a container element whose contents are meant
2383 to appear at the top of a web page, or at the top of every printed
2384 page.
2385
2386
2387 Details
2388 -------
2389
2390 :Category:
2391     `Decorative Elements`_
2392
2393 :Parents:
2394     Only the decoration_ element contains ``header``.
2395
2396 :Children:
2397     ``header`` elements may contain `body elements`_.
2398
2399 :Analogues:
2400     ``header`` is analogous to the HTML5 "header" element
2401     There are no direct analogies to ``header`` in HTML4 or DocBook.
2402     Equivalents are typically constructed from primitives and/or
2403     generated by the processing system.
2404
2405
2406 Content Model
2407 -------------
2408
2409 .. parsed-literal::
2410
2411     (`%body.elements;`_)+
2412
2413 :Attributes:
2414     The ``header`` element contains only the `common attributes`_:
2415     ids_, names_, dupnames_, source_, and classes_.
2416
2417
2418 Examples
2419 --------
2420
2421 reStructuredText source fragment::
2422
2423     .. header:: This space for rent.
2424
2425 Pseudo-XML_ fragment from simple parsing::
2426
2427     <document>
2428         <decoration>
2429             <header>
2430                 <paragraph>
2431                     This space for rent.
2432
2433
2434 ``hint``
2435 ========
2436
2437 The ``hint`` element is an admonition, a distinctive and
2438 self-contained notice.  Also see the other admonition elements
2439 Docutils offers (in alphabetical order): attention_, caution_,
2440 danger_, error_, important_, note_, tip_, warning_, and the generic
2441 admonition_.
2442
2443
2444 Details
2445 -------
2446
2447 :Category:
2448     `Compound Body Elements`_
2449
2450 :Parents:
2451     All elements employing the `%body.elements;`_ or
2452     `%structure.model;`_ parameter entities in their content models
2453     may contain ``hint``.
2454
2455 :Children:
2456     ``hint`` elements contain one or more `body elements`_.
2457
2458 :Analogues:
2459     ``hint`` has no direct analogues in common DTDs.  It can be
2460     emulated with primitives and type effects.
2461
2462 :Processing:
2463     Rendered distinctly (inset and/or in a box, etc.), with the
2464     generated title "Hint" (or similar).
2465
2466
2467 Content Model
2468 -------------
2469
2470 .. parsed-literal::
2471
2472    (`%body.elements;`_)+
2473
2474 :Attributes:
2475     The ``hint`` element contains only the `common attributes`_: ids_,
2476     names_, dupnames_, source_, and classes_.
2477
2478 :Parameter Entities:
2479     The `%body.elements;`_ parameter entity directly includes
2480     ``hint``.  The `%structure.model;`_ parameter entity indirectly
2481     includes ``hint``.
2482
2483
2484 Examples
2485 --------
2486
2487 reStructuredText source::
2488
2489     .. Hint:: It's bigger than a bread box.
2490
2491 Pseudo-XML_ fragment from simple parsing::
2492
2493     <hint>
2494         <paragraph>
2495             It's bigger than a bread box.
2496
2497
2498 ``image``
2499 =========
2500
2501 :Attributes:
2502     The ``image`` element contains the `common attributes`_ (ids_,
2503     names_, dupnames_, source_, and classes_), plus uri, alt, height_,
2504     width_, and scale_.
2505
2506 `To be completed`_.
2507
2508
2509 ``important``
2510 =============
2511
2512 The ``important`` element is an admonition, a distinctive and
2513 self-contained notice.  Also see the other admonition elements
2514 Docutils offers (in alphabetical order): attention_, caution_,
2515 danger_, error_, hint_, note_, tip_, warning_, and the generic
2516 admonition_.
2517
2518
2519 Details
2520 -------
2521
2522 :Category:
2523     `Compound Body Elements`_
2524
2525 :Parents:
2526     All elements employing the `%body.elements;`_ or
2527     `%structure.model;`_ parameter entities in their content models
2528     may contain ``important``.
2529
2530 :Children:
2531     ``important`` elements contain one or more `body elements`_.
2532
2533 :Analogues:
2534     ``important`` is analogous to the DocBook "important" element.
2535
2536 :Processing:
2537     Rendered distinctly (inset and/or in a box, etc.), with the
2538     generated title "Important" (or similar).
2539
2540
2541 Content Model
2542 -------------
2543
2544 .. parsed-literal::
2545
2546    (`%body.elements;`_)+
2547
2548 :Attributes:
2549     The ``important`` element contains only the `common attributes`_:
2550     ids_, names_, dupnames_, source_, and classes_.
2551
2552 :Parameter Entities:
2553     The `%body.elements;`_ parameter entity directly includes
2554     ``important``.  The `%structure.model;`_ parameter entity
2555     indirectly includes ``important``.
2556
2557
2558 Examples
2559 --------
2560
2561 reStructuredText source::
2562
2563     .. Important::
2564
2565        * Wash behind your ears.
2566        * Clean up your room.
2567        * Back up your data.
2568        * Call your mother.
2569
2570 Pseudo-XML_ fragment from simple parsing::
2571
2572     <important>
2573         <bullet_list>
2574             <list_item>
2575                 <paragraph>
2576                     Wash behind your ears.
2577             <list_item>
2578                 <paragraph>
2579                     Clean up your room.
2580             <list_item>
2581                 <paragraph>
2582                     Back up your data.
2583             <list_item>
2584                 <paragraph>
2585                     Call your mother.
2586
2587
2588 ``inline``
2589 ==========
2590
2591 `To be completed`_.
2592
2593
2594 ``label``
2595 =========
2596
2597 `To be completed`_.
2598
2599
2600 ``legend``
2601 ==========
2602
2603 `To be completed`_.
2604
2605
2606 ``line``
2607 ========
2608
2609 The ``line`` element contains a single line of text, part of a
2610 `line_block`_.
2611
2612
2613 Details
2614 -------
2615
2616 :Category:
2617     `Body Subelements`_ (simple)
2618
2619 :Parents:
2620     Only the `line_block`_ element contains ``line``.
2621
2622 :Children:
2623     ``line`` elements may contain text data plus `inline elements`_.
2624
2625 :Analogues:
2626     ``line`` has no direct analogues in common DTDs.  It can be
2627     emulated with primitives or type effects.
2628
2629 :Processing:
2630     See `line_block`_.
2631
2632
2633 Content Model
2634 -------------
2635
2636 .. parsed-literal::
2637
2638    `%text.model;`_
2639
2640 :Attributes:
2641     The ``line`` element contains the `common attributes`_ (ids_,
2642     names_, dupnames_, source_, and classes_), plus `xml:space`_.
2643
2644
2645 Examples
2646 --------
2647
2648 See `line_block`_.
2649
2650
2651 ``line_block``
2652 ==============
2653
2654 The ``line_block`` element contains a sequence of lines and nested
2655 line blocks.  Line breaks (implied between elements) and leading
2656 whitespace (indicated by nesting) is significant and must be
2657 preserved.  ``line_block`` elements are commonly used for verse and
2658 addresses.  See `literal_block`_ for an alternative useful for program
2659 listings and interactive computer sessions.
2660
2661
2662 Details
2663 -------
2664
2665 :Category:
2666     `Compound Body Elements`_
2667
2668 :Parents:
2669     All elements employing the `%body.elements;`_ or
2670     `%structure.model;`_ parameter entities in their content models
2671     may contain ``line_block``.
2672
2673 :Children:
2674     ``line_block`` elements may contain line_ elements and nested
2675     ``line_block`` elements.
2676
2677 :Analogues:
2678     ``line_block`` is analogous to the DocBook "literallayout" element
2679     and to the HTML "pre" element (with modifications to typeface
2680     styles).
2681
2682 :Processing:
2683     Unlike ``literal_block``, ``line_block`` elements are typically
2684     rendered in an ordinary text typeface.  It is crucial that leading
2685     whitespace and line breaks are preserved in the rendered form.
2686
2687
2688 Content Model
2689 -------------
2690
2691 .. parsed-literal::
2692
2693    (line_ | line_block_)+
2694
2695 :Attributes:
2696     The ``line_block`` element contains the `common attributes`_ (ids_,
2697     names_, dupnames_, source_, and classes_), plus `xml:space`_.
2698
2699 :Parameter Entities:
2700     The `%body.elements;`_ parameter entity directly includes
2701     ``line_block``.  The `%structure.model;`_ parameter entity
2702     indirectly includes ``line_block``.
2703
2704
2705 Examples
2706 --------
2707
2708 reStructuredText uses a directive to indicate a ``line_block``.
2709 Example source::
2710
2711     Take it away, Eric the Orchestra Leader!
2712
2713     | A one, two, a one two three four
2714     |
2715     | Half a bee, philosophically,
2716     |     must, *ipso facto*, half not be.
2717     | But half the bee has got to be,
2718     |     *vis a vis* its entity.  D'you see?
2719     |
2720     | But can a bee be said to be
2721     |     or not to be an entire bee,
2722     |         when half the bee is not a bee,
2723     |             due to some ancient injury?
2724     |
2725     | Singing...
2726
2727 Pseudo-XML_ fragment from simple parsing::
2728
2729     <paragraph>
2730         Take it away, Eric the Orchestra Leader!
2731     <line_block>
2732         <line>
2733             A one, two, a one two three four
2734         <line>
2735         <line>
2736             Half a bee, philosophically,
2737         <line_block>
2738             <line>
2739                 must,
2740                 <emphasis>
2741                     ipso facto
2742                 , half not be.
2743         <line>
2744             But half the bee has got to be,
2745         <line_block>
2746             <line>
2747                 <emphasis>
2748                     vis a vis
2749                  its entity.  D'you see?
2750             <line>
2751         <line>
2752             But can a bee be said to be
2753         <line_block>
2754             <line>
2755                 or not to be an entire bee,
2756             <line_block>
2757                 <line>
2758                     when half the bee is not a bee,
2759                 <line_block>
2760                     <line>
2761                         due to some ancient injury?
2762                     <line>
2763         <line>
2764             Singing...
2765
2766
2767 ``list_item``
2768 =============
2769
2770 The ``list_item`` element is a container for the elements of a list
2771 item.
2772
2773
2774 Details
2775 -------
2776
2777 :Category:
2778     `Body Subelements`_ (compound)
2779
2780 :Parents:
2781     The bullet_list_ and enumerated_list_ elements contain
2782     ``list_item``.
2783
2784 :Children:
2785     ``list_item`` elements may contain `body elements`_.
2786
2787 :Analogues:
2788     ``list_item`` is analogous to the HTML "li" element and to the
2789     DocBook "listitem" element.
2790
2791 :Processing:
2792     See bullet_list_ or enumerated_list_.
2793
2794
2795 Content Model
2796 -------------
2797
2798 .. parsed-literal::
2799
2800     (`%body.elements;`_)*
2801
2802 :Attributes:
2803     The ``list_item`` element contains only the `common attributes`_:
2804     ids_, names_, dupnames_, source_, and classes_.
2805
2806
2807 Examples
2808 --------
2809
2810 reStructuredText_ source::
2811
2812     1. Outer list, item 1.
2813
2814        * Inner list, item 1.
2815        * Inner list, item 2.
2816
2817     2. Outer list, item 2.
2818
2819 Pseudo-XML_ fragment from simple parsing::
2820
2821     <enumerated_list enumtype="arabic" prefix="" suffix=".">
2822         <list_item>
2823             <paragraph>
2824                 Outer list, item 1.
2825             <bullet_list bullet="*">
2826                 <list_item>
2827                     <paragraph>
2828                         Inner list, item 1.
2829                 <list_item>
2830                     <paragraph>
2831                         Inner list, item 2.
2832         <list_item>
2833             <paragraph>
2834                 Outer list, item 2.
2835
2836 See bullet_list_ or enumerated_list_ for further examples.
2837
2838
2839 ``literal``
2840 ===========
2841
2842 `To be completed`_.
2843
2844
2845 ``literal_block``
2846 =================
2847
2848 The ``literal_block`` element contains a block of text where line
2849 breaks and whitespace are significant and must be preserved.
2850 ``literal_block`` elements are commonly used for program listings and
2851 interactive computer sessions.  See `line_block`_ for an alternative
2852 useful for verse and addresses.
2853
2854
2855 Details
2856 -------
2857
2858 :Category:
2859     `Simple Body Elements`_
2860
2861 :Parents:
2862     All elements employing the `%body.elements;`_ or
2863     `%structure.model;`_ parameter entities in their content models
2864     may contain ``literal_block``.
2865
2866 :Children:
2867     ``literal_block`` elements may contain text data plus `inline
2868     elements`_.
2869
2870 :Analogues:
2871     ``literal_block`` is analogous to the HTML "pre" element and to
2872     the DocBook "programlisting" and "screen" elements.
2873
2874 :Processing:
2875     ``literal_block`` elements are typically rendered in a monospaced
2876     typeface.  It is crucial that all whitespace and line breaks are
2877     preserved in the rendered form.
2878
2879
2880 Content Model
2881 -------------
2882
2883 .. parsed-literal::
2884
2885    `%text.model;`_
2886
2887 :Attributes:
2888     The ``literal_block`` element contains the `common attributes`_
2889     (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_.
2890
2891 :Parameter Entities:
2892     The `%body.elements;`_ parameter entity directly includes
2893     ``literal_block``.  The `%structure.model;`_ parameter entity
2894     indirectly includes ``literal_block``.
2895
2896
2897 Examples
2898 --------
2899
2900 reStructuredText source::
2901
2902     Here is a literal block::
2903
2904         if literal_block:
2905             text = 'is left as-is'
2906             spaces_and_linebreaks = 'are preserved'
2907             markup_processing = None
2908
2909 Pseudo-XML_ fragment from simple parsing::
2910
2911     <paragraph>
2912         Here is a literal block:
2913     <literal_block xml:space="preserve">
2914         if literal_block:
2915             text = 'is left as-is'
2916             spaces_and_linebreaks = 'are preserved'
2917             markup_processing = None
2918
2919 ``math``
2920 ========
2921
2922 The ``math`` element contains text in `LaTeX math format` [#latex-math]_
2923 that is typeset as mathematical notation (inline formula).
2924
2925 If the output format does not support math typesetting, the content is
2926 inserted verbatim.
2927
2928 Details
2929 -------
2930
2931 :Category:
2932     `Inline Elements`_
2933
2934 :Parents:
2935     All elements employing the `%inline.elements;`_ parameter entities in
2936     their content models may contain ``math``.
2937
2938 :Children:
2939     ``math`` elements may contain text data.
2940
2941 :Analogues:
2942     ``math`` is analogous to a MathML "math" element or
2943     the LaTeX (``$ math $``) mode.
2944
2945 :Processing:
2946     Rendered as mathematical notation.
2947
2948 Content Model
2949 -------------
2950
2951 .. parsed-literal::
2952
2953     `%text.model;`_
2954
2955 :Attributes:
2956     The ``math`` element contains the `common attributes`_
2957     (ids_, names_, dupnames_, source_, and classes_).
2958
2959 .. [#latex-math] For details of the supported mathematical language, see
2960    the `"math" directive`_
2961
2962 .. _"math" directive: rst/directives.html#math
2963
2964
2965 ``math_block``
2966 ==============
2967
2968 The ``math_block`` element contains a block of text in `LaTeX math
2969 format` [#latex-math]_ that is typeset as mathematical notation
2970 (display formula). The ``math_block`` element is generated during
2971 the initial parse from a `"math" directive`_.
2972
2973 If the output format does not support math typesetting, the content is
2974 inserted verbatim.
2975
2976 Details
2977 -------
2978
2979 :Category:
2980     `Simple Body Elements`_
2981
2982 :Parents:
2983     All elements employing the `%body.elements;`_ or
2984     `%structure.model;`_ parameter entities in their content models
2985     may contain ``math_block``.
2986
2987 :Children:
2988     ``math_block`` elements may contain text data.
2989
2990 :Analogues:
2991     ``math_block`` is analogous to a LaTeX "equation*" environment or
2992     a MathML "math" element displayed as block-level element.
2993
2994 :Processing:
2995     Rendered in a block as mathematical notation, typically centered or with
2996     indentation
2997
2998 Content Model
2999 -------------
3000
3001 .. parsed-literal::
3002
3003     (#PCDATA)
3004
3005 :Attributes:
3006     The ``math`` element contains the `common attributes`_
3007     (ids_, names_, dupnames_, source_, and classes_).
3008
3009
3010 ``note``
3011 ========
3012
3013 The ``note`` element is an admonition, a distinctive and
3014 self-contained notice.  Also see the other admonition elements
3015 Docutils offers (in alphabetical order): attention_, caution_,
3016 danger_, error_, hint_, important_, tip_, warning_, and the generic
3017 admonition_.
3018
3019
3020 Details
3021 -------
3022
3023 :Category:
3024     `Compound Body Elements`_
3025
3026 :Parents:
3027     All elements employing the `%body.elements;`_ or
3028     `%structure.model;`_ parameter entities in their content models
3029     may contain ``note``.
3030
3031 :Children:
3032     ``note`` elements contain one or more `body elements`_.
3033
3034 :Analogues:
3035     ``note`` is analogous to the DocBook "note" element.
3036
3037 :Processing:
3038     Rendered distinctly (inset and/or in a box, etc.), with the
3039     generated title "Note" (or similar).
3040
3041
3042 Content Model
3043 -------------
3044
3045 .. parsed-literal::
3046
3047    (`%body.elements;`_)+
3048
3049 :Attributes:
3050     The ``note`` element contains only the `common attributes`_: ids_,
3051     names_, dupnames_, source_, and classes_.
3052
3053 :Parameter Entities:
3054     The `%body.elements;`_ parameter entity directly includes
3055     ``note``.  The `%structure.model;`_ parameter entity indirectly
3056     includes ``note``.
3057
3058
3059 Examples
3060 --------
3061
3062 reStructuredText source::
3063
3064     .. Note:: Admonitions can be handy to break up a
3065        long boring technical document.
3066
3067 Pseudo-XML_ fragment from simple parsing::
3068
3069     <note>
3070         <paragraph>
3071             Admonitions can be handy to break up a
3072             long boring technical document.
3073
3074 ``option``
3075 ==========
3076
3077 The ``option`` element groups an option string together with zero or
3078 more option argument placeholders.  Note that reStructuredText_
3079 currently supports only one argument per option.
3080
3081
3082 Details
3083 -------
3084
3085 :Category:
3086     `Body Subelements`_
3087
3088 :Parents:
3089     Only the option_group_ element contains ``option``.
3090
3091 :Children:
3092     Each ``option`` element contains one option_string_ and zero or
3093     more option_argument_ elements.
3094
3095 :Analogues:
3096     ``option`` has no direct analogues in common DTDs.
3097
3098 :Processing:
3099     See option_list_.
3100
3101
3102 Content Model
3103 -------------
3104
3105 .. parsed-literal::
3106
3107    (option_string_, option_argument_ \*)
3108
3109 :Attributes:
3110     The ``option`` element contains only the `common attributes`_:
3111     ids_, names_, dupnames_, source_, and classes_.
3112
3113
3114 Examples
3115 --------
3116
3117 See the examples for the option_list_ element.
3118
3119
3120 ``option_argument``
3121 ===================
3122
3123 The ``option_argument`` element contains placeholder text for option
3124 arguments.
3125
3126
3127 Details
3128 -------
3129
3130 :Category:
3131     `Body Subelements`_
3132
3133 :Parents:
3134     Only the option_ element contains ``option_argument``.
3135
3136 :Children:
3137     ``option_argument`` elements contain text data only.
3138
3139 :Analogues:
3140     ``option_argument`` has no direct analogues in common DTDs.
3141
3142 :Processing:
3143     The value of the "delimiter" attribute is prefixed to the
3144     ``option_argument``, separating it from its option_string_ or a
3145     preceding ``option_argument``.  The ``option_argument`` text is
3146     typically rendered in a monospaced typeface, possibly italicized
3147     or otherwise altered to indicate its placeholder nature.
3148
3149
3150 Content Model
3151 -------------
3152
3153 .. parsed-literal::
3154
3155    (#PCDATA)
3156
3157 :Attributes:
3158     The ``option_argument`` element contains the `common attributes`_ (ids_,
3159     names_, dupnames_, source_, and classes_), plus delimiter_.
3160
3161     ``delimiter`` contains the text preceding the ``option_argument``:
3162     either the text separating it from the option_string_ (typically
3163     either "=" or " ") or the text between option arguments (typically
3164     either "," or " ").
3165
3166
3167 Examples
3168 --------
3169
3170 See the examples for the option_list_ element.
3171
3172
3173 ``option_group``
3174 ================
3175
3176 The ``option_group`` element groups together one or more option_
3177 elements, all synonyms.
3178
3179
3180 Details
3181 -------
3182
3183 :Category:
3184     `Body Subelements`_
3185
3186 :Parents:
3187     Only the option_list_item_ element contains ``option_group``.
3188
3189 :Children:
3190     ``option_group`` elements contain one or more option_ elements.
3191
3192     ``option_group`` is an empty element and has no children.
3193
3194     Each ``option_group`` element contains one _ and
3195     one _ element.
3196
3197 :Analogues:
3198     ``option_group`` has no direct analogues in common DTDs.
3199
3200 :Processing:
3201     Typically option_ elements within an ``option_group`` are joined
3202     together in a comma-separated list.
3203
3204
3205 Content Model
3206 -------------
3207
3208 .. parsed-literal::
3209
3210    (option_group_, description_)
3211
3212 :Attributes:
3213     The ``option_group`` element contains only the `common attributes`_:
3214     ids_, names_, dupnames_, source_, and classes_.
3215
3216
3217 Examples
3218 --------
3219
3220 See the examples for the option_list_ element.
3221
3222
3223 ``option_list``
3224 ===============
3225
3226 Each ``option_list`` element contains a two-column list of
3227 command-line options and descriptions, documenting a program's
3228 options.
3229
3230
3231 Details
3232 -------
3233
3234 :Category:
3235     `Compound Body Elements`_
3236
3237 :Parents:
3238     All elements employing the `%body.elements;`_ or
3239     `%structure.model;`_ parameter entities in their content models
3240     may contain ``option_list``.
3241
3242 :Children:
3243     ``option_list`` elements contain one or more option_list_item_
3244     elements.
3245
3246 :Analogues:
3247     ``option_list`` has no direct analogues in common DTDs.  It can be
3248     emulated with primitives such as tables.
3249
3250 :Processing:
3251     An ``option_list`` is typically rendered as a two-column list,
3252     where the first column contains option strings and arguments, and
3253     the second column contains descriptions.
3254
3255
3256 Content Model
3257 -------------
3258
3259 .. parsed-literal::
3260
3261    (option_list_item_ +)
3262
3263 :Attributes:
3264     The ``option_list`` element contains only the `common attributes`_:
3265     ids_, names_, dupnames_, source_, and classes_.
3266
3267 :Parameter Entities:
3268     The `%body.elements;`_ parameter entity directly includes
3269     ``option_list``.  The `%structure.model;`_ parameter entity
3270     indirectly includes ``option_list``.
3271
3272
3273 Examples
3274 --------
3275
3276 reStructuredText_ source::
3277
3278     -a            command-line option "a"
3279     -1 file, --one=file, --two file
3280                   Multiple options with arguments.
3281
3282 Pseudo-XML_ fragment from simple parsing::
3283
3284     <option_list>
3285         <option_list_item>
3286             <option_group>
3287                 <option>
3288                     <option_string>
3289                         -a
3290             <description>
3291                 <paragraph>
3292                     command-line option "a"
3293         <option_list_item>
3294             <option_group>
3295                 <option>
3296                     <option_string>
3297                         -1
3298                     <option_argument delimiter=" ">
3299                         file
3300                 <option>
3301                     <option_string>
3302                         --one
3303                     <option_argument delimiter="=">
3304                         file
3305                 <option>
3306                     <option_string>
3307                         --two
3308                     <option_argument delimiter=" ">
3309                         file
3310             <description>
3311                 <paragraph>
3312                     Multiple options with arguments.
3313
3314
3315 ``option_list_item``
3316 ====================
3317
3318 The ``option_list_item`` element is a container for a pair of
3319 option_group_ and description_ elements.
3320
3321
3322 Details
3323 -------
3324
3325 :Category:
3326     `Body Subelements`_
3327
3328 :Parents:
3329     Only the option_list_ element contains ``option_list_item``.
3330
3331 :Children:
3332     Each ``option_list_item`` element contains one option_group_ and
3333     one description_ element.
3334
3335 :Analogues:
3336     ``option_list_item`` has no direct analogues in common DTDs.
3337
3338 :Processing:
3339     See option_list_.
3340
3341
3342 Content Model
3343 -------------
3344
3345 .. parsed-literal::
3346
3347    (option_group_, description_)
3348
3349 :Attributes:
3350     The ``option_list_item`` element contains only the `common attributes`_:
3351     ids_, names_, dupnames_, source_, and classes_.
3352
3353
3354 Examples
3355 --------
3356
3357 See the examples for the option_list_ element.
3358
3359
3360 ``option_string``
3361 =================
3362
3363 The ``option_string`` element contains the text of a command-line
3364 option.
3365
3366
3367 Details
3368 -------
3369
3370 :Category:
3371     `Body Subelements`_
3372
3373 :Parents:
3374     Only the option_ element contains ``option_string``.
3375
3376 :Children:
3377     ``option_string`` elements contain text data only.
3378
3379 :Analogues:
3380     ``option_string`` has no direct analogues in common DTDs.
3381
3382 :Processing:
3383     The ``option_string`` text is typically rendered in a monospaced
3384     typeface.
3385
3386
3387 Content Model
3388 -------------
3389
3390 .. parsed-literal::
3391
3392    (#PCDATA)
3393
3394 :Attributes:
3395     The ``option_string`` element contains only the `common attributes`_:
3396     ids_, names_, dupnames_, source_, and classes_.
3397
3398
3399 Examples
3400 --------
3401
3402 See the examples for the option_list_ element.
3403
3404
3405 ``organization``
3406 ================
3407
3408 The ``organization`` element contains the name of document author's
3409 organization, or the organization responsible for the document.
3410
3411
3412 Details
3413 -------
3414
3415 :Category:
3416     `Bibliographic Elements`_
3417
3418 :Parents:
3419     Only the docinfo_ element contains ``organization``.
3420
3421 :Children:
3422     ``organization`` elements may contain text data plus `inline
3423     elements`_.
3424
3425 :Analogues:
3426     ``organization`` is analogous to the DocBook "orgname",
3427     "corpname", or "publishername" elements.
3428
3429 :Processing:
3430     See docinfo_.
3431
3432
3433 Content Model
3434 -------------
3435
3436 .. parsed-literal::
3437
3438     `%text.model;`_
3439
3440 :Attributes:
3441     The ``organization`` element contains only the `common attributes`_:
3442     ids_, names_, dupnames_, source_, and classes_.
3443
3444 :Parameter Entities:
3445     The `%bibliographic.elements;`_ parameter entity directly includes
3446     ``organization``.
3447
3448
3449 Examples
3450 --------
3451
3452 reStructuredText_ source::
3453
3454     Document Title
3455     ==============
3456
3457     :Organization: Humankind
3458
3459 Complete pseudo-XML_ result after parsing and applying transforms::
3460
3461     <document ids="document-title" names="document title">
3462         <title>
3463             Document Title
3464         <docinfo>
3465             <organization>
3466                 Humankind
3467
3468 See docinfo_ for a more complete example, including processing
3469 context.
3470
3471
3472 ``paragraph``
3473 =============
3474
3475 The ``paragraph`` element contains the text and inline elements of a
3476 single paragraph, a fundamental building block of documents.
3477
3478
3479 Details
3480 -------
3481
3482 :Category:
3483     `Simple Body Elements`_
3484
3485 :Parents:
3486     All elements employing the `%body.elements;`_ or
3487     `%structure.model;`_ parameter entities in their content models
3488     may contain ``paragraph``.
3489
3490 :Children:
3491     ``paragraph`` elements may contain text data plus `inline
3492     elements`_.
3493
3494 :Analogues:
3495     ``paragraph`` is analogous to the HTML "p" element and to the
3496     DocBook "para" elements.
3497
3498
3499 Content Model
3500 -------------
3501
3502 .. parsed-literal::
3503
3504     `%text.model;`_
3505
3506 :Attributes:
3507     The ``paragraph`` element contains only the `common attributes`_:
3508     ids_, names_, dupnames_, source_, and classes_.
3509
3510 :Parameter Entities:
3511     The `%body.elements;`_ parameter entity directly includes
3512     ``paragraph``.  The `%structure.model;`_ parameter entity
3513     indirectly includes ``paragraph``.
3514
3515
3516 Examples
3517 --------
3518
3519 reStructuredText_ source::
3520
3521     A paragraph.
3522
3523 Pseudo-XML_ fragment from simple parsing::
3524
3525     <paragraph>
3526         A paragraph.
3527
3528
3529 ``pending``
3530 ===========
3531
3532 `To be completed`_.
3533
3534
3535 ``problematic``
3536 ===============
3537
3538 `To be completed`_.
3539
3540
3541 ``raw``
3542 =======
3543
3544 `To be completed`_.
3545
3546
3547 ``reference``
3548 =============
3549
3550 `To be completed`_.
3551
3552
3553 ``revision``
3554 ============
3555
3556 The ``revision`` element contains the revision number of the document.
3557 It can be used alone or in conjunction with version_.
3558
3559
3560 Details
3561 -------
3562
3563 :Category:
3564     `Bibliographic Elements`_
3565
3566 :Parents:
3567     Only the docinfo_ element contains ``revision``.
3568
3569 :Children:
3570     ``revision`` elements may contain text data plus `inline
3571     elements`_.
3572
3573 :Analogues:
3574     ``revision`` is analogous to but simpler than the DocBook
3575     "revision" element.  It closely matches the DocBook "revnumber"
3576     element, but in a simpler context.
3577
3578 :Processing:
3579     Often used with the RCS/CVS keyword "Revision".  See docinfo_.
3580
3581
3582 Content Model
3583 -------------
3584
3585 .. parsed-literal::
3586
3587     `%text.model;`_
3588
3589 :Attributes:
3590     The ``revision`` element contains only the `common attributes`_:
3591     ids_, names_, dupnames_, source_, and classes_.
3592
3593 :Parameter Entities:
3594     The `%bibliographic.elements;`_ parameter entity directly includes
3595     ``revision``.
3596
3597
3598 Examples
3599 --------
3600
3601 reStructuredText_ source::
3602
3603     Document Title
3604     ==============
3605
3606     :Version: 1
3607     :Revision: b
3608
3609 Complete pseudo-XML_ result after parsing and applying transforms::
3610
3611     <document ids="document-title" names="document title">
3612         <title>
3613             Document Title
3614         <docinfo>
3615             <version>
3616                 1
3617             <revision>
3618                 b
3619
3620 See docinfo_ for a more complete example, including processing
3621 context.
3622
3623
3624 ``row``
3625 =======
3626
3627 `To be completed`_.
3628
3629
3630 ``rubric``
3631 ==========
3632
3633      rubric n. 1. a title, heading, or the like, in a manuscript,
3634      book, statute, etc., written or printed in red or otherwise
3635      distinguished from the rest of the text. ...
3636
3637      -- Random House Webster's College Dictionary, 1991
3638
3639 A rubric is like an informal heading that doesn't correspond to the
3640 document's structure.
3641
3642 `To be completed`_.
3643
3644
3645 ``section``
3646 ===========
3647
3648 The ``section`` element is the main unit of hierarchy for Docutils
3649 documents.  Docutils ``section`` elements are a recursive structure; a
3650 ``section`` may contain other ``section`` elements, without limit.
3651 Paragraphs and other body elements may occur before a ``section``, but
3652 not after it.
3653
3654
3655 Details
3656 -------
3657
3658 :Category:
3659     `Structural Elements`_
3660
3661 :Parents:
3662     The following elements may contain ``section``: document_,
3663     section_
3664
3665 :Children:
3666     ``section`` elements begin with a title_, and may contain `body
3667     elements`_ as well as transition_, topic_, and sidebar_ elements.
3668
3669 :Analogues:
3670     ``section`` is analogous to the recursive "section" elements in
3671     DocBook and HTML5.
3672
3673
3674 Content Model
3675 -------------
3676
3677 .. parsed-literal::
3678
3679     (title_,
3680      `%structure.model;`_)
3681
3682 See the `%structure.model;`_ parameter entity for details of the body
3683 of a ``section``.
3684
3685 :Attributes:
3686     The ``section`` element contains only the `common attributes`_:
3687     ids_, names_, dupnames_, source_, and classes_.
3688
3689 :Parameter Entities:
3690     The `%section.elements;`_ parameter entity directly includes
3691     ``section``.  The `%structure.model;`_ parameter entity indirectly
3692     includes ``section``.
3693
3694
3695 Examples
3696 --------
3697
3698 reStructuredText_ source::
3699
3700     Title 1
3701     =======
3702     Paragraph 1.
3703
3704     Title 2
3705     -------
3706     Paragraph 2.
3707
3708     Title 3
3709     =======
3710     Paragraph 3.
3711
3712     Title 4
3713     -------
3714     Paragraph 4.
3715
3716 Complete pseudo-XML_ result after parsing::
3717
3718     <document>
3719         <section ids="title-1" names="title 1">
3720             <title>
3721                 Title 1
3722             <paragraph>
3723                 Paragraph 1.
3724             <section ids="title-2" names="title 2">
3725                 <title>
3726                     Title 2
3727                 <paragraph>
3728                     Paragraph 2.
3729         <section ids="title-3" names="title 3">
3730             <title>
3731                 Title 3
3732             <paragraph>
3733                 Paragraph 3.
3734             <section ids="title-4" names="title 4">
3735                 <title>
3736                     Title 4
3737                 <paragraph>
3738                     Paragraph 4.
3739
3740
3741 ``sidebar``
3742 ===========
3743
3744 Sidebars are like miniature, parallel documents that occur inside
3745 other documents, providing related or reference material.  A
3746 ``sidebar`` is typically offset by a border and "floats" to the side
3747 of the page; the document's main text may flow around it.  Sidebars
3748 can also be likened to super-footnotes; their content is outside of
3749 the flow of the document's main text.
3750
3751 The ``sidebar`` element is a nonrecursive section_-like construct
3752 which may occur at the top level of a section_ wherever a body element
3753 (list, table, etc.) is allowed.  In other words, ``sidebar`` elements
3754 cannot nest inside body elements, so you can't have a ``sidebar``
3755 inside a ``table`` or a ``list``, or inside another ``sidebar`` (or
3756 topic_).
3757
3758
3759 Details
3760 -------
3761
3762 :Category:
3763     `Structural Elements`_
3764
3765 :Parents:
3766     The following elements may contain ``sidebar``: document_,
3767     section_
3768
3769 :Children:
3770     ``sidebar`` elements begin with optional title_ and subtitle_
3771     and contain `body elements`_ and topic_ elements.
3772
3773 :Analogues:
3774     ``sidebar`` is analogous to the DocBook "sidebar" element.
3775
3776 :Processing:
3777     A ``sidebar`` element should be set off from the rest of the
3778     document somehow, typically with a border.  Sidebars typically
3779     "float" to the side of the page and the document's main text flows
3780     around them.
3781
3782
3783 Content Model
3784 -------------
3785
3786 .. parsed-literal::
3787
3788     (title_, subtitle_?,
3789      (`%body.elements;`_ | topic_)+)
3790
3791 :Attributes:
3792     The ``sidebar`` element contains only the `common attributes`_:
3793     ids_, names_, dupnames_, source_, and classes_.
3794
3795 :Parameter Entities:
3796     The `%structure.model;`_ parameter entity directly includes
3797     ``sidebar``.
3798
3799
3800 Examples
3801 --------
3802
3803 The `"sidebar" directive`_ is used to create a ``sidebar`` element.
3804 reStructuredText_ source::
3805
3806     .. sidebar:: Optional Title
3807        :subtitle: If Desired
3808
3809        Body.
3810
3811 Pseudo-XML_ fragment from simple parsing::
3812
3813     <sidebar>
3814         <title>
3815             Optional Title
3816         <subtitle>
3817             If Desired
3818         <paragraph>
3819             Body.
3820
3821 .. _"sidebar" directive: rst/directives.html#sidebar
3822
3823
3824 ``status``
3825 ==========
3826
3827 The ``status`` element contains a status statement for the document,
3828 such as "Draft", "Final", "Work In Progress", etc.
3829
3830
3831 Details
3832 -------
3833
3834 :Category:
3835     `Bibliographic Elements`_
3836
3837 :Parents:
3838     Only the docinfo_ element contains ``status``.
3839
3840 :Children:
3841     ``status`` elements may contain text data plus `inline elements`_.
3842
3843 :Analogues:
3844     ``status`` is analogous to the DocBook "status" element.
3845
3846 :Processing:
3847     See docinfo_.
3848
3849
3850 Content Model
3851 -------------
3852
3853 .. parsed-literal::
3854
3855     `%text.model;`_
3856
3857 :Attributes:
3858     The ``status`` element contains only the `common attributes`_:
3859     ids_, names_, dupnames_, source_, and classes_.
3860
3861 :Parameter Entities:
3862     The `%bibliographic.elements;`_ parameter entity directly includes
3863     ``status``.
3864
3865
3866 Examples
3867 --------
3868
3869 reStructuredText_ source::
3870
3871     Document Title
3872     ==============
3873
3874     :Status: Work In Progress
3875
3876 Complete pseudo-XML_ result after parsing and applying transforms::
3877
3878     <document ids="document-title" names="document title">
3879         <title>
3880             Document Title
3881         <docinfo>
3882             <status>
3883                 Work In Progress
3884
3885 See docinfo_ for a more complete example, including processing
3886 context.
3887
3888
3889 ``strong``
3890 ==========
3891
3892 `To be completed`_.
3893
3894
3895 ``subscript``
3896 =============
3897
3898 `To be completed`_.
3899
3900
3901 ``substitution_definition``
3902 ===========================
3903
3904 `To be completed`_.
3905
3906
3907 ``substitution_reference``
3908 ==========================
3909
3910 `To be completed`_.
3911
3912
3913 ``subtitle``
3914 ============
3915
3916 The ``subtitle`` element stores the subtitle of a document_.
3917
3918
3919 Details
3920 -------
3921
3922 :Category:
3923     `Structural Subelements`_
3924
3925 :Parents:
3926     The document_ and sidebar_ elements may contain ``subtitle``.
3927
3928 :Children:
3929     ``subtitle`` elements may contain text data plus `inline
3930     elements`_.
3931
3932 :Analogues:
3933     ``subtitle`` is analogous to HTML header elements ("h2" etc.) and
3934     to the DocBook "subtitle" element.
3935
3936 :Processing:
3937     A document's subtitle is usually rendered smaller than its title_.
3938
3939
3940 Content Model
3941 -------------
3942
3943 .. parsed-literal::
3944
3945     `%text.model;`_
3946
3947 :Attributes:
3948     The ``subtitle`` element contains only the `common attributes`_:
3949     ids_, names_, dupnames_, source_, and classes_.
3950
3951
3952 Examples
3953 --------
3954
3955 reStructuredText_ source::
3956
3957     =======
3958      Title
3959     =======
3960     ----------
3961      Subtitle
3962     ----------
3963
3964     A paragraph.
3965
3966 Complete pseudo-XML_ result after parsing and applying transforms::
3967
3968     <document ids="title" names="title">
3969         <title>
3970             Title
3971         <subtitle ids="subtitle" names="subtitle">
3972             Subtitle
3973         <paragraph>
3974             A paragraph.
3975
3976 Note how two section levels have collapsed, promoting their titles to
3977 become the document's title and subtitle.  Since there is only one
3978 structural element (document), the subsection's ``ids`` and ``names``
3979 attributes are stored in the ``subtitle`` element.
3980
3981
3982 ``superscript``
3983 ===============
3984
3985 `To be completed`_.
3986
3987
3988 ``system_message``
3989 ==================
3990
3991 `To be completed`_.
3992
3993
3994 ``table``
3995 =========
3996
3997 Docutils tables are based on the Exchange subset of the CALS-table model
3998 (OASIS Technical Memorandum 9901:1999 "XML Exchange Table Model DTD",
3999 http://www.oasis-open.org/html/tm9901.htm).
4000
4001 `To be completed`_.
4002
4003
4004 ``target``
4005 ==========
4006
4007 `To be completed`_.
4008
4009
4010 ``tbody``
4011 =========
4012
4013 `To be completed`_.
4014
4015
4016 ``term``
4017 ========
4018
4019 The ``term`` element contains a word or phrase being defined in a
4020 definition_list_.
4021
4022
4023 Details
4024 -------
4025
4026 :Category:
4027     `Body Subelements`_ (simple)
4028
4029 :Parents:
4030     Only the definition_list_item_ element contains ``term``.
4031
4032 :Children:
4033     ``term`` elements may contain text data plus `inline elements`_.
4034
4035 :Analogues:
4036     ``term`` is analogous to the HTML "dt" element and to the DocBook
4037     "term" element.
4038
4039 :Processing:
4040     See definition_list_item_.
4041
4042
4043 Content Model
4044 -------------
4045
4046 .. parsed-literal::
4047
4048     `%text.model;`_
4049
4050 :Attributes:
4051     The ``term`` element contains only the `common attributes`_:
4052     ids_, names_, dupnames_, source_, and classes_.
4053
4054
4055 Examples
4056 --------
4057
4058 See the examples for the definition_list_, definition_list_item_, and
4059 classifier_ elements.
4060
4061
4062 ``tgroup``
4063 ==========
4064
4065 `To be completed`_.
4066
4067
4068 ``thead``
4069 =========
4070
4071 `To be completed`_.
4072
4073
4074 ``tip``
4075 =======
4076
4077 The ``tip`` element is an admonition, a distinctive and self-contained
4078 notice.  Also see the other admonition elements Docutils offers (in
4079 alphabetical order): attention_, caution_, danger_, error_, hint_,
4080 important_, note_, warning_, and the generic admonition_.
4081
4082
4083 Details
4084 -------
4085
4086 :Category:
4087     `Compound Body Elements`_
4088
4089 :Parents:
4090     All elements employing the `%body.elements;`_ or
4091     `%structure.model;`_ parameter entities in their content models
4092     may contain ``tip``.
4093
4094 :Children:
4095     ``tip`` elements contain one or more `body elements`_.
4096
4097 :Analogues:
4098     ``tip`` is analogous to the DocBook "tip" element.
4099
4100 :Processing:
4101     Rendered distinctly (inset and/or in a box, etc.), with the
4102     generated title "Tip" (or similar).
4103
4104
4105 Content Model
4106 -------------
4107
4108 .. parsed-literal::
4109
4110    (`%body.elements;`_)+
4111
4112 :Attributes:
4113     The ``tip`` element contains only the `common attributes`_: ids_,
4114     names_, dupnames_, source_, and classes_.
4115
4116 :Parameter Entities:
4117     The `%body.elements;`_ parameter entity directly includes ``tip``.
4118     The `%structure.model;`_ parameter entity indirectly includes
4119     ``tip``.
4120
4121
4122 Examples
4123 --------
4124
4125 reStructuredText source::
4126
4127     .. Tip:: 15% if the service is good.
4128
4129 Pseudo-XML_ fragment from simple parsing::
4130
4131     <tip>
4132         <paragraph>
4133             15% if the service is good.
4134
4135
4136 .. _title:
4137
4138 ``title``
4139 =========
4140
4141 The ``title`` element stores the title of a document_, section_,
4142 topic_, sidebar_, or generic admonition_.
4143
4144
4145 Details
4146 -------
4147
4148 :Category:
4149     `Structural Subelements`_
4150
4151 :Parents:
4152     The following elements may contain ``title``: document_, section_,
4153     topic_, sidebar_, admonition_
4154
4155 :Children:
4156     ``title`` elements may contain text data plus `inline elements`_.
4157
4158 :Analogues:
4159     ``title`` is analogous to HTML "title" and header ("h1" etc.)
4160     elements, and to the DocBook "title" element.
4161
4162
4163 Content Model
4164 -------------
4165
4166 .. parsed-literal::
4167
4168     `%text.model;`_
4169
4170 :Attributes:
4171     The ``title`` element contains the `common attributes`_ (ids_,
4172     names_, dupnames_, source_, and classes_), plus refid_ and auto_.
4173
4174     ``refid`` is used as a backlink to a table of contents entry.
4175
4176     ``auto`` is used to indicate (with value "1") that the ``title``
4177     has been numbered automatically.
4178
4179
4180 Examples
4181 --------
4182
4183 reStructuredText_ source::
4184
4185     A Title
4186     =======
4187
4188     A paragraph.
4189
4190 Pseudo-XML_ fragment from simple parsing::
4191
4192     <section ids="a-title" names="a title">
4193         <title>
4194             A Title
4195         <paragraph>
4196             A paragraph.
4197
4198
4199 ``title_reference``
4200 ===================
4201
4202 `To be completed`_.
4203
4204
4205 ``topic``
4206 =========
4207
4208 The ``topic`` element is a nonrecursive section_-like construct which
4209 may occur at the top level of a section_ wherever a body element
4210 (list, table, etc.) is allowed.  In other words, ``topic`` elements
4211 cannot nest inside body elements, so you can't have a ``topic`` inside
4212 a ``table`` or a ``list``, or inside another ``topic``.
4213
4214
4215 Details
4216 -------
4217
4218 :Category:
4219     `Structural Elements`_
4220
4221 :Parents:
4222     The following elements may contain ``topic``: document_, section_,
4223     sidebar_
4224
4225 :Children:
4226     ``topic`` elements begin with a title_ and may contain `body
4227     elements`_.
4228
4229 :Analogues:
4230     ``topic`` is analogous to the DocBook "simplesect" element.
4231
4232 :Processing:
4233     A ``topic`` element should be set off from the rest of the
4234     document somehow, such as with indentation or a border.
4235
4236
4237 Content Model
4238 -------------
4239
4240 .. parsed-literal::
4241
4242     (title_?,
4243      (`%body.elements;`_)+)
4244
4245 :Attributes:
4246     The ``topic`` element contains only the `common attributes`_:
4247     ids_, names_, dupnames_, source_, and classes_.
4248
4249 :Parameter Entities:
4250     The `%structure.model;`_ parameter entity directly includes
4251     ``topic``.
4252
4253
4254 Examples
4255 --------
4256
4257 The `"topic" directive`_ is used to create a ``topic`` element.
4258 reStructuredText_ source::
4259
4260     .. topic:: Title
4261
4262        Body.
4263
4264 Pseudo-XML_ fragment from simple parsing::
4265
4266     <topic>
4267         <title>
4268             Title
4269         <paragraph>
4270             Body.
4271
4272 .. _"topic" directive: rst/directives.html#topic
4273
4274
4275 ``transition``
4276 ==============
4277
4278 The ``transition`` element is commonly seen in novels and short
4279 fiction, as a gap spanning one or more lines, with or without a type
4280 ornament such as a row of asterisks.  Transitions separate body
4281 elements and sections, dividing a section into untitled divisions.  A
4282 transition may not begin or end a section [#]_ or document, nor may
4283 two transitions be immediately adjacent.
4284
4285 See `Doctree Representation of Transitions`__ in `A Record of
4286 reStructuredText Syntax Alternatives`__.
4287
4288 .. [#] In reStructuredText markup, a transition may appear to fall at
4289    the end of a section immediately before another section.  A
4290    transform recognizes this case and moves the transition so it
4291    separates the sections.
4292
4293 __ ../dev/rst/alternatives.html#doctree-representation-of-transitions
4294 __ ../dev/rst/alternatives.html
4295
4296
4297 Details
4298 -------
4299
4300 :Category:
4301     `Structural Subelements`_
4302
4303 :Parents:
4304     The following elements may contain ``transition``: document_,
4305     section_
4306
4307 :Children:
4308     ``transition`` is an empty element and has no children.
4309
4310 :Analogues:
4311     ``transition`` is analogous to the HTML "hr" element.
4312
4313 :Processing:
4314     The ``transition`` element is typically rendered as vertical
4315     whitespace (more than that separating paragraphs), with or without
4316     a horizontal line or row of asterisks.  In novels, transitions are
4317     often represented as a row of three well-spaced asterisks with
4318     vertical space above and below.
4319
4320
4321 Content Model
4322 -------------
4323
4324 ::
4325
4326     EMPTY
4327
4328 The ``transition`` element has no content; it is a "point element".
4329
4330 :Attributes:
4331     The ``transition`` element contains only the `common attributes`_:
4332     ids_, names_, dupnames_, source_, and classes_.
4333
4334 :Parameter Entities:
4335     The `%structure.model;`_ parameter entity directly includes
4336     ``transition``.
4337
4338
4339 Examples
4340 --------
4341
4342 reStructuredText_ source::
4343
4344     Paragraph 1.
4345
4346     --------
4347
4348     Paragraph 2.
4349
4350 Complete pseudo-XML_ result after parsing::
4351
4352     <document>
4353         <paragraph>
4354             Paragraph 1.
4355         <transition>
4356         <paragraph>
4357             Paragraph 2.
4358
4359
4360 ``version``
4361 ===========
4362
4363 The ``version`` element contains the version number of the document.
4364 It can be used alone or in conjunction with revision_.
4365
4366
4367 Details
4368 -------
4369
4370 :Category:
4371     `Bibliographic Elements`_
4372
4373 :Parents:
4374     Only the docinfo_ element contains ``version``.
4375
4376 :Children:
4377     ``version`` elements may contain text data plus `inline
4378     elements`_.
4379
4380 :Analogues:
4381     ``version`` may be considered analogous to the DocBook "revision",
4382     "revnumber", or "biblioid" elements.
4383
4384 :Processing:
4385     Sometimes used with the RCS/CVS keyword "Revision".  See docinfo_
4386     and revision_.
4387
4388
4389 Content Model
4390 -------------
4391
4392 .. parsed-literal::
4393
4394     `%text.model;`_
4395
4396 :Attributes:
4397     The ``version`` element contains only the `common attributes`_:
4398     ids_, names_, dupnames_, source_, and classes_.
4399
4400 :Parameter Entities:
4401     The `%bibliographic.elements;`_ parameter entity directly includes
4402     ``version``.
4403
4404
4405 Examples
4406 --------
4407
4408 reStructuredText_ source::
4409
4410     Document Title
4411     ==============
4412
4413     :Version: 1.1
4414
4415 Complete pseudo-XML_ result after parsing and applying transforms::
4416
4417     <document ids="document-title" names="document title">
4418         <title>
4419             Document Title
4420         <docinfo>
4421             <version>
4422                 1.1
4423
4424 See docinfo_ for a more complete example, including processing
4425 context.
4426
4427
4428 ``warning``
4429 ===========
4430
4431 The ``warning`` element is an admonition, a distinctive and
4432 self-contained notice.  Also see the other admonition elements
4433 Docutils offers (in alphabetical order): attention_, caution_,
4434 danger_, error_, hint_, important_, note_, tip_.
4435
4436
4437 Details
4438 -------
4439
4440 :Category:
4441     `Compound Body Elements`_
4442
4443 :Parents:
4444     All elements employing the `%body.elements;`_ or
4445     `%structure.model;`_ parameter entities in their content models
4446     may contain ``warning``.
4447
4448 :Children:
4449     ``warning`` elements contain one or more `body elements`_.
4450
4451 :Analogues:
4452     ``warning`` is analogous to the DocBook "warning" element.
4453
4454 :Processing:
4455     Rendered distinctly (inset and/or in a box, etc.), with the
4456     generated title "Warning" (or similar).
4457
4458
4459 Content Model
4460 -------------
4461
4462 .. parsed-literal::
4463
4464    (`%body.elements;`_)+
4465
4466 :Attributes:
4467     The ``warning`` element contains only the `common attributes`_:
4468     ids_, names_, dupnames_, source_, and classes_.
4469
4470 :Parameter Entities:
4471     The `%body.elements;`_ parameter entity directly includes
4472     ``warning``.  The `%structure.model;`_ parameter entity indirectly
4473     includes ``warning``.
4474
4475
4476 Examples
4477 --------
4478
4479 reStructuredText source::
4480
4481     .. WARNING:: Reader discretion is strongly advised.
4482
4483 Pseudo-XML_ fragment from simple parsing::
4484
4485     <warning>
4486         <paragraph>
4487             Reader discretion is strongly advised.
4488
4489
4490 .. _attribute type:
4491
4492 ---------------
4493 Attribute types
4494 ---------------
4495
4496 .. contents:: :local:
4497               :depth: 1
4498
4499 Standard attribute types
4500 ========================
4501
4502 Attribute types defined in the `attribute types`__ section of the
4503 `XML 1.0 specification`_:
4504
4505 _`CDATA`
4506     Character data.  CDATA attributes may contain arbitrary text.
4507
4508 _`NMTOKEN`
4509     A "name token".  One or more of letters, digits, ".", "-", and
4510     "_".
4511
4512 _`NMTOKENS`
4513     One or more space-separated NMTOKEN values.
4514
4515 _`EnumeratedType`
4516     The attribute value may be one of a specified list of values.
4517
4518 Docutils uses `custom attribute types`_ instead of the ID, IDREF, and IDREFS
4519 standard types, because it does not adhere to the `One ID per Element Type`_
4520 validity constraint.
4521
4522 __ `XML attribute types`_
4523
4524
4525 Custom attribute types
4526 ======================
4527
4528 The Docutils DTD defines `parameter entities`_ that resolve to standard
4529 attribute types to highlight specific attribute value constraints.
4530
4531 _`yesorno`
4532     Boolean: no if zero ("0"), yes if any other value.
4533     Resolves to ``NMTOKEN``.
4534
4535     Used in the `anonymous`_ and `stub`_ attributes.
4536
4537 _`number`
4538     The attribute value must be a number. Resolves to ``NMTOKEN``.
4539
4540     Used in the `start`_ and `scale`_ attributes.
4541
4542     .. also ltrim, rtrim
4543
4544 _`measure`
4545     A number which may be immediately followed by a unit or percent sign.
4546     Resolves to CDATA.
4547
4548     Used in the `height`_ and `width`_ attributes.
4549
4550 _`classnames.type`
4551     A space-separated list of `class names` [#classname]_. Resolves to NMTOKEN.
4552
4553     Used in the `classes`_ attribute.
4554
4555 _`refname.type`
4556     A normalized_ `reference name`_. Resolves to CDATA (in contrast to
4557     NMTOKENS, `reference names`_ may consist of any text).
4558
4559     Used in the `refname`_ attribute.
4560
4561 _`refnames.type`
4562     A space-separated list of `reference names`_. Resolves to CDATA.
4563
4564     `Backslash escaping`_ is used for space characters inside a `reference
4565     name`.
4566
4567     Used in the `names`_ and `dupnames`_ attributes.
4568
4569 _`ids.type`
4570     A space-separated list of unique `identifier keys` [#identifier]_.
4571     Resolves to NMTOKENS (the XML `standard attribute types`_ do not provide
4572     for a list of IDs).
4573
4574     Used in the `ids`_ attribute.
4575
4576 _`idref.type`
4577     A reference to an `identifier key`_.
4578     Resolves to NMTOKEN (Docutils identifier keys do not use the ID standard
4579     type as required by the `IDREF Validity constraint`_).
4580
4581     Used in the `refid`_ attribute.
4582
4583 _`idrefs.type`
4584     A list of references to element identifiers.
4585     Resolves to NMTOKENS.
4586
4587     Used in the `backrefs`_ attribute.
4588
4589 .. _`class names`:
4590
4591 .. [#classname] `Class names` define sub-classes of existing elements.
4592
4593    In reStructuredText, custom `class names` can be specified using
4594    the `"class" directive`_, a directive's `:class: option`_, or
4595    `custom interpreted text roles`_.
4596    Docutils normalizes them to conform to both, HTML4.1 and CSS1.0 `name`
4597    requirements (the regular expression ``[a-z](-?[a-z0-9]+)*``) via the
4598    `identifier normalization`_.
4599
4600 .. _identifiers:
4601 .. _identifier key:
4602 .. _identifier keys:
4603
4604 .. [#identifier] `Identifier keys` are used for cross references in
4605    generated documents. Therefore, they must comply with restrictions in the
4606    respective output formats (HTML4.1__, HTML5__, `polyglot HTML`__,
4607    LaTeX__, ODT__, troff (manpage), XML__).
4608
4609    Identifier keys cannot be specified directly in reStructuredText.
4610    Docutils generates them by applying the `identifier normalization`_ to
4611    `reference names`_ or from the auto_id_prefix_, prepending the id_prefix_
4612    and potentially appending numbers for disambiguation.
4613
4614    __ http://www.w3.org/TR/html401/types.html#type-name
4615    __ https://www.w3.org/TR/html50/dom.html#the-id-attribute
4616    __ https://www.w3.org/TR/html-polyglot/#id-attribute
4617    __ https://tex.stackexchange.com/questions/18311/what-are-the-valid-names-as-labels
4618    __ https://help.libreoffice.org/6.3/en-US/text/swriter/01/04040000.html?DbPAR=WRITER#bm_id4974211
4619    __ https://www.w3.org/TR/REC-xml/#id
4620
4621
4622 .. _XML 1.0 specification: https://www.w3.org/TR/REC-xml
4623 .. _XML attribute types: https://www.w3.org/TR/REC-xml/#sec-attribute-types
4624 .. _One ID per Element Type: https://www.w3.org/TR/REC-xml/#one-id-per-el
4625 .. .. _ID attribute type: https://www.w3.org/TR/REC-xml/#id
4626 .. _parameter entities: https://www.w3.org/TR/REC-xml/#dt-PE
4627 .. _IDREF Validity constraint: https://www.w3.org/TR/REC-xml/#idref
4628
4629 .. _reference names:
4630 .. _reference name: rst/restructuredtext.html#reference-names
4631 .. _backslash escaping: rst/restructuredtext.html#escaping-mechanism
4632 .. _id_prefix: ../user/config.html#id-prefix
4633 .. _auto_id_prefix: ../user/config.html#auto-id-prefix
4634 .. _identifier normalization:
4635     rst/directives.html#identifier-normalization
4636 .. _`:class: option`: rst/directives.html#class-option
4637 .. _custom interpreted text roles:
4638     rst/directives.html#custom-interpreted-text-roles
4639
4640
4641 ---------------------
4642  Attribute Reference
4643 ---------------------
4644
4645 .. contents:: :local:
4646               :depth: 1
4647
4648 _`Common Attributes`: Through the `%basic.atts;`_ parameter entity,
4649 all elements contain the following attributes: ids_, names_ or dupnames_,
4650 source_, and classes_.
4651
4652
4653 ``anonymous``
4654 =============
4655
4656 Attribute type: `yesorno`_.  Default value: none (implies no).
4657
4658 The ``anonymous`` attribute is used for unnamed hyperlinks in the
4659 target_ and reference_ elements (via the `%anonymous.att;`_ parameter
4660 entity).
4661
4662
4663 ``auto``
4664 ========
4665
4666 Attribute type: `CDATA`_.  Default value: none.
4667
4668 The ``auto`` attribute is used to indicate automatically-numbered
4669 footnote_, footnote_reference_ and title_ elements (via the
4670 `%auto.att;`_ parameter entity).
4671
4672
4673 ``backrefs``
4674 ============
4675
4676 Attribute type: `idrefs.type`_.  Default value: none.
4677
4678 The ``backrefs`` attribute contains a space-separated list of identifier_
4679 references, used for backlinks from footnote_, citation_, and
4680 system_message_ elements (via the `%backrefs.att;`_ parameter entity).
4681
4682
4683 ``bullet``
4684 ==========
4685
4686 Attribute type: `CDATA`_.  Default value: none.
4687
4688 The ``bullet`` attribute is used in the bullet_list_ element.
4689
4690
4691 ``classes``
4692 ===========
4693
4694 Attribute type: `classnames.type`_.  Default value: none.
4695
4696 The ``classes`` attribute is a space separated list containing zero or more
4697 `class names`_.
4698
4699 The purpose of the attribute is to indicate an "is-a" variant relationship,
4700 to allow an extensible way of defining sub-classes of existing elements.  It
4701 can be used to carry context forward between a Docutils Reader and Writer,
4702 when a custom structure is reduced to a standardized document tree.  One
4703 common use is in conjunction with stylesheets, to add selection criteria.
4704 It should not be used to carry formatting instructions or arbitrary content.
4705
4706 The ``classes`` attribute's contents should be ignorable.  Writers that
4707 are not familiar with the variant expressed should be able to ignore
4708 the attribute.
4709
4710 ``classes`` is one of the `common attributes`_, shared by all Docutils
4711 elements.
4712
4713 .. _"class" directive: rst/directives.html#class
4714
4715
4716 ``delimiter``
4717 =============
4718
4719 Attribute type: `CDATA`_.  Default value: none.
4720
4721 The ``delimiter`` attribute is used in the option_argument_ element.
4722
4723
4724 ``dupnames``
4725 ============
4726
4727 Attribute type: `refnames.type`_.  Default value: none.
4728
4729 The ``dupnames`` attribute replaces the `names`_ attribute
4730 when there has been a naming conflict.
4731 ``dupnames`` is one of the `common attributes`_, shared by all
4732 Docutils elements.
4733
4734
4735 ``enumtype``
4736 ============
4737
4738 Attribute type: EnumeratedType_, one of "arabic", "loweralpha",
4739 "upperalpha", "lowerroman", or "upperroman".  Default value: none.
4740
4741 The ``enumtype`` attribute is used in the enumerated_list_ element.
4742
4743
4744 ``height``
4745 ==========
4746
4747 Attribute type: measure_.  Default value: none.
4748
4749 The ``height`` attribute is used in the image_ element.
4750
4751
4752 ``ids``
4753 =======
4754
4755 Attribute type: `ids.type`_.  Default value: none.
4756
4757 The ``ids`` attribute is a space separated list containing one or more
4758 unique `identifier keys`_, typically assigned by the system.
4759
4760 ``ids`` is one of the `common attributes`_, shared by all Docutils
4761 elements.
4762
4763 .. TODO:
4764    * Use 'id' for primary identifier key?
4765    * Keep additional keys in `ids`
4766      or in the preceding target elements?
4767
4768
4769 ``names``
4770 =========
4771
4772 Attribute type: `refnames.type`_.  Default value: none.
4773
4774 The ``names`` attribute is a space-separated list containing
4775 `normalized`_ `reference names`_ of an element. Whitespace inside a
4776 name is backslash escaped.
4777 Each name in the list must be unique; if there are name conflicts
4778 (two or more elements want to the same name), the contents will be
4779 transferred to the `dupnames`_ attribute on the duplicate elements.
4780 An element may have at most one of the ``names`` or ``dupnames``
4781 attributes, but not both.
4782
4783 `Reference names`_ are identifiers assigned in the markup. They
4784 originate from `internal hyperlink targets`_, a directive's `name
4785 option`_, or the element's title or content and are used for
4786 internal cross-references (cf. refname_).
4787
4788 ``names`` is one of the `common attributes`_, shared by all
4789 Docutils elements.
4790
4791 .. _normalized:
4792    rst/restructuredtext.html#normalized-reference-names
4793 .. _internal hyperlink targets:
4794    rst/restructuredtext.html#internal-hyperlink-targets
4795 .. _name option: rst/directives.html#name
4796
4797
4798 ``prefix``
4799 ==========
4800
4801 Attribute type: `CDATA`_.  Default value: none.
4802
4803 The ``prefix`` attribute is used in the enumerated_list_ element.
4804
4805
4806 ``refid``
4807 =========
4808
4809 Attribute type: `idref.type`_.  Default value: none.
4810
4811 The ``refid`` attribute contains a reference to an `identifier key`_
4812
4813 ``refid`` is used by the target_, reference_, footnote_reference_,
4814 citation_reference_, title_ and problematic_ elements (via the
4815 `%refid.att;`_ and `%reference.atts;`_ parameter entities).
4816
4817
4818 ``refname``
4819 ===========
4820
4821 Attribute type: `refname.type`_.  Default value: none.
4822
4823 The ``refname`` attribute contains a reference to one of the
4824 `reference names`_ in the `names`_ attribute of another element.  On
4825 a `target`_ element, ``refname`` indicates an `indirect target`_ which
4826 may resolve to either an internal or external reference.  Docutils
4827 "transforms_" replace the ``refname`` attribute with a refid_ pointing
4828 to the same element.
4829
4830 ``refname`` is used by the target_, reference_, footnote_reference_,
4831 citation_reference_, and substitution_reference_ elements (via the
4832 `%refname.att;`_ and `%reference.atts;`_ parameter entities).
4833
4834 .. _indirect target: rst/restructuredtext.html#indirect-hyperlink-targets
4835 .. _transforms: transforms.html
4836
4837
4838 ``refuri``
4839 ==========
4840
4841 Attribute type: `CDATA`_.  Default value: none.
4842
4843 The ``refuri`` attribute contains an external reference to a URI/URL.
4844 It is used by the target_, reference_, footnote_reference_, and
4845 citation_reference_ elements (via the `%reference.atts;`_ parameter
4846 entity).
4847
4848
4849 ``scale``
4850 ==========
4851
4852 Attribute type: number_.  Default value: none.
4853
4854 The ``scale`` attribute is used in the image_ element.
4855
4856
4857 ``source``
4858 ==========
4859
4860 Attribute type: `CDATA`_.  Default value: none.
4861
4862 The ``source`` attribute is used to store the path or URL to the
4863 source text that was used to produce the document tree.  It is one of
4864 the `common attributes`_, shared by all Docutils elements.
4865
4866
4867 ``start``
4868 =========
4869
4870 Attribute type: `number`_.  Default value: none.
4871
4872 The ``start`` attribute is used in the enumerated_list_ element.
4873
4874
4875 ``stub``
4876 =========
4877
4878 Attribute type: `yesorno`_.  Default value: none.
4879
4880 The ``stub`` attribute is used in the colspec_ element.
4881
4882
4883 ``suffix``
4884 ==========
4885
4886 Attribute type: `CDATA`_.  Default value: none.
4887
4888 The ``suffix`` attribute is used in the enumerated_list_ element.
4889
4890
4891 ``width``
4892 ==========
4893
4894 Attribute type: measure_.  Default value: none.
4895
4896 The ``width`` attribute is used in the image_ element.
4897
4898
4899 ``xml:space``
4900 =============
4901
4902 `Attribute type`: `EnumeratedType`_, one of "default" or "preserve".
4903 Default value: "preserve" (fixed).
4904
4905 The ``xml:space`` attribute is a standard XML attribute for
4906 whitespace-preserving elements.  It is used by the literal_block_,
4907 line_block_, doctest_block_, comment_, and raw_ elements (via the
4908 `%fixedspace.att;`_ parameter entity).  It is a fixed attribute, meant
4909 to communicate to an XML parser that the element contains significant
4910 whitespace.  The attribute value should not be set in a document
4911 instance.
4912
4913
4914 .. _title (attribute):
4915
4916 ``title``
4917 =========
4918
4919 Attribute type: `CDATA`_.  Default value: none.
4920
4921 The ``title`` attribute stores the title metadata of a document.  This
4922 title is typically not part of the rendered document.  It may for
4923 example be used in HTML's ``title`` element.
4924
4925
4926 ----------------------------
4927  Parameter Entity Reference
4928 ----------------------------
4929
4930 .. contents:: :local:
4931               :depth: 1
4932
4933 Parameter entities are used to simplify the DTD (to share definitions
4934 and reduce duplication) and to allow the DTD to be customized by
4935 wrapper DTDs (external client DTDs that use or import the Docutils
4936 DTD).  Parameter entities may be overridden by wrapper DTDs, replacing
4937 the definitions below with custom definitions.  Parameter entities
4938 whose names begin with "additional" are meant to allow easy extension
4939 by wrapper DTDs.
4940
4941
4942 ``%anonymous.att;``
4943 ===================
4944
4945 The ``%anonymous.att;`` parameter entity contains the anonymous_
4946 attribute, used for unnamed hyperlinks.
4947
4948 Entity definition:
4949
4950 .. parsed-literal::
4951
4952     anonymous_ %yesorno; #IMPLIED
4953
4954 The reference_ and target_ elements directly employ the
4955 ``%anonymous.att;`` parameter entity in their attribute lists.
4956
4957
4958 ``%auto.att;``
4959 ==============
4960
4961 The ``%auto.att;`` parameter entity contains the auto_ attribute, used
4962 to indicate an automatically-numbered footnote or title.
4963
4964 Entity definition:
4965
4966 .. parsed-literal::
4967
4968     auto_     CDATA     #IMPLIED
4969
4970 The footnote_, footnote_reference_, and title_ elements directly
4971 employ the ``%auto.att;`` parameter entity in their attribute lists.
4972
4973
4974 ``%backrefs.att;``
4975 ==================
4976
4977 The ``%backrefs.att;`` parameter entity contains the backrefs_
4978 attribute, a space-separated list of id references, for backlinks.
4979
4980 Entity definition:
4981
4982 .. parsed-literal::
4983
4984     backrefs_  %idrefs.type;    #IMPLIED
4985
4986 The citation_, footnote_, and system_message_ elements directly employ
4987 the ``%backrefs.att;`` parameter entity in their attribute lists.
4988
4989
4990 ``%basic.atts;``
4991 ================
4992
4993 The ``%basic.atts;`` parameter entity lists attributes common to all
4994 Docutils elements.  See `Common Attributes`_.
4995
4996 Entity definition:
4997
4998 .. parsed-literal::
4999
5000     ids_      NMTOKENS  #IMPLIED
5001     names_    CDATA     #IMPLIED
5002     dupnames_ CDATA     #IMPLIED
5003     source_   CDATA     #IMPLIED
5004     classes_  NMTOKENS  #IMPLIED
5005     %additional.basic.atts;
5006
5007 The ``%additional.basic.atts;`` parameter entity can be used by
5008 wrapper DTDs to extend ``%basic.atts;``.
5009
5010
5011 ``%bibliographic.elements;``
5012 ============================
5013
5014 The ``%bibliographic.elements;`` parameter entity contains an OR-list of all
5015 `bibliographic elements`_.
5016
5017 Entity definition:
5018
5019 .. parsed-literal::
5020
5021     author_ | authors_ | organization_ | contact_ | address_
5022     | version_ | revision_ | status_ | date_ | copyright_
5023     | field_
5024     %additional.bibliographic.elements;
5025
5026 The ``%additional.bibliographic.elements;`` parameter entity can be used by
5027 wrapper DTDs to extend ``%bibliographic.elements;``.
5028
5029 Only the docinfo_ element directly employs the
5030 ``%bibliographic.elements;`` parameter entity in its content model.
5031
5032
5033 ``%body.elements;``
5034 ===================
5035
5036 The ``%body.elements;`` parameter entity contains an OR-list of all
5037 `body elements`_.  ``%body.elements;`` is itself contained within the
5038 `%structure.model;`_ parameter entity.
5039
5040 Entity definition:
5041
5042 .. parsed-literal::
5043
5044     admonition_ | attention_ | block_quote_ | bullet_list_ | caution_
5045     | citation_ | compound_ | comment_ | container_ | danger_ |
5046       definition_list_ | doctest_block_ | enumerated_list_ | error_ |
5047       field_list_ | figure_ | footnote_ | hint_ | image_ | important_
5048       | line_block_ | literal_block_ | note_ | option_list_ |
5049       paragraph_ | pending_ | raw_ reference_ | rubric_ |
5050       substitution_definition_ | system_message_ | table_ | target_ |
5051       tip_ | warning_ %additional.body.elements;
5052
5053 The ``%additional.body.elements;`` parameter entity can be used by
5054 wrapper DTDs to extend ``%body.elements;``.
5055
5056 The ``%body.elements;`` parameter entity is directly employed in the
5057 content models of the following elements: admonition_, attention_,
5058 block_quote_, caution_, citation_, compound_, danger_, definition_,
5059 description_, entry_, error_, field_body_, footer_, footnote_,
5060 header_, hint_, important_, legend_, list_item_, note_, sidebar_,
5061 system_message_, tip_, topic_, warning_
5062
5063 Via `%structure.model;`_, the ``%body.elements;`` parameter entity is
5064 indirectly employed in the content models of the document_ and
5065 section_ elements.
5066
5067
5068 ``%fixedspace.att;``
5069 ====================
5070
5071 The ``%fixedspace.att;`` parameter entity contains the `xml:space`_
5072 attribute, a standard XML attribute for whitespace-preserving
5073 elements.
5074
5075 Entity definition:
5076
5077 .. parsed-literal::
5078
5079     `xml:space`_ (default | preserve) #FIXED 'preserve'
5080
5081 The ``%fixedspace.att;`` parameter entity is directly employed in the
5082 attribute lists of the following elements: address_, comment_,
5083 doctest_block_, line_block_, literal_block_, raw_
5084
5085
5086 ``%inline.elements;``
5087 =====================
5088
5089 The ``%inline.elements;`` parameter entity contains an OR-list of all
5090 `inline elements`_.
5091
5092 Entity definition:
5093
5094 .. parsed-literal::
5095
5096     abbreviation_ | acronym_ | citation_reference_ | emphasis_ |
5097     footnote_reference_ | generated_ | image_ | inline_ | literal_ |
5098     problematic_ | raw_ | reference_ | strong_ | substitution_reference_ |
5099     subscript_ | superscript_ | target_ | title_reference_
5100     %additional.inline.elements;
5101
5102 The ``%additional.inline.elements;`` parameter entity can be used by
5103 wrapper DTDs to extend ``%inline.elements;``.
5104
5105 Via `%text.model;`_, the ``%inline.elements;`` parameter entity is
5106 indirectly employed in the content models of the following elements:
5107 abbreviation_, acronym_, address_, attribution_, author_, caption_,
5108 classifier_, contact_, copyright_, date_, doctest_block_, emphasis_,
5109 generated_, inline_, line_block_, literal_block_, math_, math_block_,
5110 organization_,
5111 paragraph_, problematic_, raw_, reference_, revision_, rubric_,
5112 status_, strong_, subscript_, substitution_definition_,
5113 substitution_reference_, subtitle_, superscript_, target_, term_,
5114 title_, title_reference_, version_
5115
5116
5117 ``%reference.atts;``
5118 ====================
5119
5120 The ``%reference.atts;`` parameter entity groups together the refuri_,
5121 refid_, and refname_ attributes.
5122
5123 Entity definition:
5124
5125 .. parsed-literal::
5126
5127     `%refuri.att;`_
5128     `%refid.att;`_
5129     `%refname.att;`_
5130     %additional.reference.atts;
5131
5132 The ``%additional.reference.atts;`` parameter entity can be used by
5133 wrapper DTDs to extend ``%additional.reference.atts;``.
5134
5135 The citation_reference_, footnote_reference_, reference_, and target_
5136 elements directly employ the ``%reference.att;`` parameter entity in
5137 their attribute lists.
5138
5139
5140 ``%refid.att;``
5141 ================
5142
5143 The ``%refid.att;`` parameter entity contains the refid_ attribute, an
5144 internal reference to the `ids`_ attribute of another element.
5145
5146 Entity definition:
5147
5148 .. parsed-literal::
5149
5150     refid_   %idref.type;    #IMPLIED
5151
5152 The title_ and problematic_ elements directly employ the
5153 ``%refid.att;`` parameter entity in their attribute lists.
5154
5155 Via `%reference.atts;`_, the ``%refid.att;`` parameter entity is
5156 indirectly employed in the attribute lists of the citation_reference_,
5157 footnote_reference_, reference_, and target_ elements.
5158
5159
5160 ``%refname.att;``
5161 =================
5162
5163 The ``%refname.att;`` parameter entity contains the refname_
5164 attribute, an internal reference to the `names`_ attribute of another
5165 element.  On a `target`_ element, ``refname`` indicates an indirect
5166 target which may resolve to either an internal or external
5167 reference.
5168
5169 Entity definition:
5170
5171 .. parsed-literal::
5172
5173     refname_  %refname.type;  #IMPLIED
5174
5175 The substitution_reference_ element directly employs the
5176 ``%refname.att;`` parameter entity in its attribute list.
5177
5178 Via `%reference.atts;`_, the ``%refname.att;`` parameter entity is
5179 indirectly employed in the attribute lists of the citation_reference_,
5180 footnote_reference_, reference_, and target_ elements.
5181
5182
5183 ``%refuri.att;``
5184 ================
5185
5186 The ``%refuri.att;`` parameter entity contains the refuri_ attribute,
5187 an external reference to a URI/URL.
5188
5189 Entity definition:
5190
5191 .. parsed-literal::
5192
5193     refuri_   CDATA     #IMPLIED
5194
5195 Via `%reference.atts;`_, the ``%refuri.att;`` parameter entity is
5196 indirectly employed in the attribute lists of the citation_reference_,
5197 footnote_reference_, reference_, and target_ elements.
5198
5199
5200 ``%section.elements;``
5201 ======================
5202
5203 The ``%section.elements;`` parameter entity contains an OR-list of all
5204 section_-equivalent elements.  ``%section.elements;`` is itself
5205 contained within the `%structure.model;`_ parameter entity.
5206
5207 Entity definition:
5208
5209 .. parsed-literal::
5210
5211     section_
5212     %additional.section.elements;
5213
5214 The ``%additional.section.elements;`` parameter entity can be used
5215 by wrapper DTDs to extend ``%section.elements;``.
5216
5217 Via `%structure.model;`_, the ``%section.elements;`` parameter entity
5218 is indirectly employed in the content models of the document_ and
5219 section_ elements.
5220
5221
5222 ``%structure.model;``
5223 =====================
5224
5225 The ``%structure.model;`` parameter entity encapsulates the
5226 hierarchical structure of a document and of its constituent parts.
5227 See the discussion of the `element hierarchy`_ above.
5228
5229 Entity definition:
5230
5231 .. parsed-literal::
5232
5233    ( ( (`%body.elements;`_ | topic_ | sidebar_)+, transition_? )*,
5234      ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? )
5235
5236 Each document_ or section_ contains zero or more body elements,
5237 topics, and/or sidebars, optionally interspersed with single
5238 transitions, followed by zero or more sections (whose contents are
5239 recursively the same as this model) optionally interspersed with
5240 transitions.
5241
5242 The following restrictions are imposed by this model:
5243
5244 * Transitions must be separated by other elements (body elements,
5245   sections, etc.).  In other words, a transition may not be
5246   immediately adjacent to another transition.
5247
5248 * A transition may not occur at the beginning of a document or
5249   section.
5250
5251 .. The following is not the case with Docutils (since at least 2004)
5252    (cf. test/functional/input/data/standard.txt)
5253
5254    An additional restriction, which cannot be expressed in the language
5255    of DTDs, is imposed by software:
5256
5257    * A transition may not occur at the end of a document or section.
5258
5259 The `%structure.model;`_ parameter entity is directly employed in the
5260 content models of the document_ and section_ elements.
5261
5262
5263 ``%text.model;``
5264 ================
5265
5266 The ``%text.model;`` parameter entity is used by many elements to
5267 represent text data mixed with `inline elements`_.
5268
5269 Entity definition:
5270
5271 .. parsed-literal::
5272
5273     (#PCDATA | `%inline.elements;`_)*
5274
5275 The ``%text.model;`` parameter entity is directly employed in the
5276 content models of the following elements: abbreviation_, acronym_,
5277 address_, author_, caption_, classifier_, contact_, copyright_, date_,
5278 doctest_block_, emphasis_, field_name_, generated_, line_block_,
5279 literal_block_, organization_, paragraph_, problematic_, raw_,
5280 reference_, revision_, status_, strong_, substitution_definition_,
5281 substitution_reference_, subtitle_, target_, term_, title_, version_
5282
5283
5284 \f
5285 ..
5286    Local Variables:
5287    mode: indented-text
5288    indent-tabs-mode: nil
5289    sentence-end-double-space: t
5290    fill-column: 70
5291    End: