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: goodger@users.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
  40 .. _Docutils: http://docutils.sourceforge.net/
  41 .. _Docutils Generic DTD:
  42 .. _Docutils DTD:
  43 .. _docutils.dtd: docutils.dtd
  44 .. _Introducing the Extensible Markup Language (XML):
  45    http://xml.coverpages.org/xmlIntro.html
  46 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
  47 .. _A ReStructuredText Primer: ../docs/rst/quickstart.html
  48 .. _reStructuredText Markup Specification: rst/reStructuredText.html
  49
  50
  51 -------------------
  52  Element Hierarchy
  53 -------------------
  54
  55 .. contents:: :local:
  56
  57 Below is a simplified diagram of the hierarchy of elements in the
  58 Docutils document tree structure.  An element may contain any other
  59 elements immediately below it in the diagram.  Notes are written in
  60 square brackets.  Element types in parentheses indicate recursive or
  61 one-to-many relationships; sections may contain (sub)sections, tables
  62 contain further body elements, etc. ::
  63
  64   +--------------------------------------------------------------------+
  65   | document  [may begin with a title, subtitle, docinfo, decoration]  |
  66   |                             +--------------------------------------+
  67   |                             | sections  [each begins with a title] |
  68   +-----------------------------+-------------------------+------------+
  69   | [body elements:]                                      | (sections) |
  70   |         | - literal | - lists  |       | - hyperlink  +------------+
  71   |         |   blocks  | - tables |       |   targets    |
  72   | para-   | - doctest | - block  | foot- | - sub. defs  |
  73   | graphs  |   blocks  |   quotes | notes | - comments   |
  74   +---------+-----------+----------+-------+--------------+
  75   | [text]+ | [text]    | (body elements)  | [text]       |
  76   | (inline +-----------+------------------+--------------+
  77   | markup) |
  78   +---------+
  79
  80 The Docutils document model uses a simple, recursive model for section
  81 structure.  A document_ node may contain body elements and section_
  82 elements.  Sections in turn may contain body elements and sections.
  83 The level (depth) of a section element is determined from its physical
  84 nesting level; unlike other document models (``<h1>`` in HTML_,
  85 ``<sect1>`` in DocBook_, ``<div1>`` in XMLSpec_) the level is not
  86 incorporated into the element name.
  87
  88 The Docutils document model uses strict element content models.  Every
  89 element has a unique structure and semantics, but elements may be
  90 classified into general categories (below).  Only elements which are
  91 meant to directly contain text data have a mixed content model, where
  92 text data and inline elements may be intermixed.  This is unlike the
  93 much looser HTML_ document model, where paragraphs and text data may
  94 occur at the same level.
  95
  96
  97 Structural Elements
  98 ===================
  99
 100 Structural elements may only contain child elements; they do not
 101 directly contain text data.  Structural elements may contain body
 102 elements or further structural elements.  Structural elements can only
 103 be child elements of other structural elements.
 104
 105 Category members: document_, section_, topic_
 106
 107
 108 Structural Subelements
 109 ----------------------
 110
 111 Structural subelements are child elements of structural elements.
 112
 113 Category members: title_, subtitle_, docinfo_, decoration_,
 114 transition_
 115
 116
 117 Bibliographic Elements
 118 ``````````````````````
 119
 120 The docinfo_ element is an optional child of document_.  It groups
 121 bibliographic elements together.
 122
 123 Category members: address_, author_, authors_, contact_, copyright_,
 124 date_, field_, organization_, revision_, status_, version_
 125
 126
 127 Decorative Elements
 128 ```````````````````
 129
 130 The decoration_ element is also an optional child of document_.  It
 131 groups together elements used to generate page headers and footers.
 132
 133 Category members: footer_, header_
 134
 135
 136 Body Elements
 137 =============
 138
 139 Body elements are contained within structural elements and compound
 140 body elements.  There are two subcategories of body elements: simple
 141 and compound.
 142
 143 Category members:  attention_, block_quote_, bullet_list_, caution_,
 144 citation_, comment_, danger_, definition_list_, doctest_block_,
 145 enumerated_list_, error_, field_list_, figure_, footnote_, hint_,
 146 image_, important_, line_block_, literal_block_, note_, option_list_,
 147 paragraph_, pending_, raw_, substitution_definition_,
 148 system_message_, table_, target_, tip_, warning_
 149
 150
 151 Simple Body Elements
 152 --------------------
 153
 154 Simple body elements directly are empty or contain text data.  Those
 155 that contain text data may also contain inline elements.  Such
 156 elements therefore have a "mixed content model".
 157
 158 Category members: comment_, doctest_block_, image_, line_block_,
 159 literal_block_, paragraph_, pending_, raw_, substitution_definition_,
 160 target_
 161
 162
 163 Compound Body Elements
 164 ----------------------
 165
 166 Compound body elements contain local substructure (body subelements)
 167 and further body elements.  They do not directly contain text data.
 168
 169 Category members: attention_, block_quote_, bullet_list_, caution_,
 170 citation_, danger_, definition_list_, enumerated_list_, error_,
 171 field_list_, figure_, footnote_, hint_, important_, note_,
 172 option_list_, system_message_, table_, tip_, warning_
 173
 174
 175 Body Subelements
 176 ````````````````
 177
 178 Compound body elements contain specific subelements (e.g. bullet_list_
 179 contains list_item_).  Subelements may themselves be compound elements
 180 (containing further child elements, like field_) or simple data
 181 elements (containing text data, like field_name_).  These subelements
 182 always occur within specific parent elements, never at the body
 183 element level (beside paragraphs, etc.).
 184
 185 Category members (simple): caption_, classifier_, colspec_,
 186 field_name_, label_, option_argument_, option_string_, term_
 187
 188 Category members (compound): definition_, definition_list_item_,
 189 description_, entry_, field_, field_body_, legend_, list_item_,
 190 option_, option_group_, option_list_item_, row_, tbody_, tgroup_,
 191 thead_
 192
 193
 194 Inline Elements
 195 ===============
 196
 197 Inline elements directly contain text data, and may also contain
 198 further inline elements.  Inline elements are contained within simple
 199 body elements.  Most inline elements have a "mixed content model".
 200
 201 Category members: citation_reference_, emphasis_, footnote_reference_,
 202 generated_, image_, interpreted_, literal_, problematic_, reference_,
 203 strong_, substitution_reference_, target_, raw_
 204
 205
 206 .. _HTML: http://www.w3.org/MarkUp/
 207 .. _DocBook: http://docbook.org/tdg/en/html/docbook.html
 208 .. _XMLSpec: http://www.w3.org/XML/1998/06/xmlspec-report.htm
 209
 210
 211 -------------------
 212  Element Reference
 213 -------------------
 214
 215 .. contents:: :local:
 216               :depth: 1
 217
 218 Each element in the DTD (document type definition) is described in its
 219 own section below.  Each section contains an introduction plus the
 220 following subsections:
 221
 222 * Details (of element relationships and semantics):
 223
 224   - Category: One or more references to the element categories in
 225     `Element Hierarchy`_ above.  Some elements belong to more than one
 226     category.
 227
 228   - Parents: A list of elements which may contain the element.
 229
 230   - Children: A list of elements which may occur within the element.
 231
 232   - Analogues: Describes analogous elements in well-known document
 233     models such as HTML_ or DocBook_.  Lists similarities and
 234     differences.
 235
 236   - Processing: Lists formatting or rendering recommendations for the
 237     element.
 238
 239 * Content Model:
 240
 241   The formal XML content model from the `Docutils DTD`_, followed by:
 242
 243   - Attributes: Describes (or refers to descriptions of) the possible
 244     values and semantics of each attribute.
 245
 246   - Parameter Entities: Lists the parameter entities which directly or
 247     indirectly include the element.
 248
 249 * Examples: reStructuredText examples are shown along with
 250   fragments of the document trees resulting from parsing.
 251   _`Pseudo-XML` is used for the results of parsing and processing.
 252   Pseudo-XML is a representation of XML where nesting is indicated by
 253   indentation and end-tags are not shown.  Some of the precision of
 254   real XML is given up in exchange for easier readability.  For
 255   example, the following are equivalent:
 256
 257   - Real XML::
 258
 259         <document>
 260         <section id="a-title" name="a title">
 261         <title>A Title</title>
 262         <paragraph>A paragraph.</paragraph>
 263         </section>
 264         </document>
 265
 266   - Pseudo-XML::
 267
 268         <document>
 269             <section id="a-title" name="a title">
 270                 <title>
 271                     A Title
 272                 <paragraph>
 273                     A paragraph.
 274
 275 --------------------
 276
 277 Many of the element reference sections below are marked "_`to be
 278 completed`".  Please help complete this document by contributing to
 279 its writing.
 280
 281
 282 ``address``
 283 ===========
 284
 285 The ``address`` element holds the surface mailing address information
 286 for the author (individual or group) of the document, or a third-party
 287 contact address.  Its structure is identical to that of the
 288 line_block_ element: whitespace is significant, especially newlines.
 289
 290
 291 Details
 292 -------
 293
 294 :Category: `Bibliographic Elements`_
 295
 296 :Parents:
 297     The following elements may contain ``address``: docinfo_, authors_
 298
 299 :Children:
 300     ``address`` elements contain text data plus `inline elements`_.
 301
 302 :Analogues:
 303     ``address`` is analogous to the DocBook "address" element.
 304
 305 :Processing:
 306     As with the line_block_ element, newlines and other whitespace is
 307     significant and must be preserved.  However, a monospaced typeface
 308     need not be used.
 309
 310     See also docinfo_.
 311
 312
 313 Content Model
 314 -------------
 315
 316 .. parsed-literal::
 317
 318     `%text.model;`_
 319
 320 :Attributes:
 321     The ``address`` element contains the `common attributes`_ (id_,
 322     name_, dupname_, source_, and class_), plus `xml:space`_.
 323
 324 :Parameter Entities:
 325     The `%bibliographic.elements;`_ parameter entity directly includes
 326     ``address``.
 327
 328
 329
 330 Examples
 331 --------
 332
 333 reStructuredText source::
 334
 335     Document Title
 336     ==============
 337
 338     :Address: 123 Example Ave.
 339               Example, EX
 340
 341 Complete pseudo-XML_ result after parsing and applying transforms::
 342
 343     <document id="document-title" name="document title">
 344         <title>
 345             Document Title
 346         <docinfo>
 347             <address>
 348                 123 Example Ave.
 349                 Example, EX
 350
 351 See docinfo_ for a more complete example, including processing
 352 context.
 353
 354
 355 ``attention``
 356 =============
 357
 358 `To be completed`_.
 359
 360
 361 ``author``
 362 ==========
 363
 364 The ``author`` element holds the name of the author of the document.
 365
 366
 367 Details
 368 -------
 369
 370 :Category: `Bibliographic Elements`_
 371
 372 :Parents:
 373     The following elements may contain ``author``: docinfo_, authors_
 374
 375 :Children:
 376     ``author`` elements may contain text data plus `inline elements`_.
 377
 378 :Analogues:
 379     ``author`` is analogous to the DocBook "author" element.
 380
 381 :Processing:
 382     See docinfo_.
 383
 384
 385 Content Model
 386 -------------
 387
 388 .. parsed-literal::
 389
 390     `%text.model;`_
 391
 392 :Attributes:
 393     The ``author`` element contains only the `common attributes`_:
 394     id_, name_, dupname_, source_, and class_.
 395
 396 :Parameter Entities:
 397     The `%bibliographic.elements;`_ parameter entity directly includes
 398     ``author``.
 399
 400
 401 Examples
 402 --------
 403
 404 reStructuredText source::
 405
 406     Document Title
 407     ==============
 408
 409     :Author: J. Random Hacker
 410
 411 Complete pseudo-XML_ result after parsing and applying transforms::
 412
 413     <document id="document-title" name="document title">
 414         <title>
 415             Document Title
 416         <docinfo>
 417             <author>
 418                 J. Random Hacker
 419
 420 See docinfo_ for a more complete example, including processing
 421 context.
 422
 423
 424 ``authors``
 425 ===========
 426
 427 The ``authors`` element is a container for author information for
 428 documents with multiple authors.
 429
 430
 431 Details
 432 -------
 433
 434 :Category: `Bibliographic Elements`_
 435
 436 :Parents:
 437     Only the docinfo_ element contains ``authors``.
 438
 439 :Children:
 440     ``authors`` elements may contain the following elements: author_,
 441     organization_, address_, contact_
 442
 443 :Analogues:
 444     ``authors`` is analogous to the DocBook "authors" element.
 445
 446 :Processing:
 447     See docinfo_.
 448
 449
 450 Content Model
 451 -------------
 452
 453 .. parsed-literal::
 454
 455     ((author_, organization_?, address_?, contact_?)+)
 456
 457 :Attributes:
 458     The ``authors`` element contains only the `common attributes`_:
 459     id_, name_, dupname_, source_, and class_.
 460
 461 :Parameter Entities:
 462     The `%bibliographic.elements;`_ parameter entity directly includes
 463     ``authors``.
 464
 465
 466 Examples
 467 --------
 468
 469 reStructuredText source::
 470
 471     Document Title
 472     ==============
 473
 474     :Authors: J. Random Hacker; Jane Doe
 475
 476 Complete pseudo-XML_ result after parsing and applying transforms::
 477
 478     <document id="document-title" name="document title">
 479         <title>
 480             Document Title
 481         <docinfo>
 482             <authors>
 483                 <author>
 484                     J. Random Hacker
 485                 <author>
 486                     Jane Doe
 487
 488 In reStructuredText, multiple author's names are separated with
 489 semicolons (";") or commas (","); semicolons take precedence.  There
 490 is currently no way to represent the author's organization, address,
 491 or contact in a reStructuredText "Authors" field.
 492
 493 See docinfo_ for a more complete example, including processing
 494 context.
 495
 496
 497 ``block_quote``
 498 ===============
 499
 500 `To be completed`_.
 501
 502
 503 ``bullet_list``
 504 ===============
 505
 506 The ``bullet_list`` element contains list_item_ elements which are
 507 uniformly marked with bullets.  Bullets are typically simple dingbats
 508 (symbols) such as circles and squares.
 509
 510
 511 Details
 512 -------
 513
 514 :Category: `Compound Body Elements`_
 515
 516 :Parents:
 517     All elements employing the `%body.elements;`_ or
 518     `%structure.model;`_ parameter entities in their content models
 519     may contain ``bullet_list``.
 520
 521 :Children:
 522     ``bullet_list`` elements contain one or more list_item_ elements.
 523
 524 :Analogues:
 525     ``bullet_list`` is analogous to the HTML "ul" element and to the
 526     DocBook "itemizedlist" element.  HTML's "ul" is short for
 527     "unordered list", which we consider to be a misnomer.  "Unordered"
 528     implies that the list items may be randomly rearranged without
 529     affecting the meaning of the list.  Bullet lists *are* often
 530     ordered; the ordering is simply left implicit.
 531
 532 :Processing:
 533     Each list item should begin a new vertical block, prefaced by a
 534     bullet/dingbat.
 535
 536
 537 Content Model
 538 -------------
 539
 540 .. parsed-literal::
 541
 542     (list_item_+)
 543
 544 :Attributes:
 545     The ``bullet_list`` element contains the `common attributes`_
 546     (id_, name_, dupname_, source_, and class_), plus bullet_.
 547
 548     ``bullet`` is used to record the style of bullet from the input
 549     data.  In reStructuredText, it contains one of "-", "+", or "*".
 550     It may be ignored in processing.
 551
 552 :Parameter Entities:
 553     The `%body.elements;`_ parameter entity directly includes
 554     ``bullet_list``.  The `%structure.model;`_ parameter entity
 555     indirectly includes ``bullet_list``.
 556
 557
 558 Examples
 559 --------
 560
 561 reStructuredText source::
 562
 563     - Item 1, paragraph 1.
 564
 565       Item 1, paragraph 2.
 566
 567     - Item 2.
 568
 569 Pseudo-XML_ fragment from simple parsing::
 570
 571     <bullet_list bullet="-">
 572         <list_item>
 573             <paragraph>
 574                 Item 1, paragraph 1.
 575             <paragraph>
 576                 Item 1, paragraph 2.
 577         <list_item>
 578             <paragraph>
 579                 Item 2.
 580
 581 See list_item_ for another example.
 582
 583
 584 ``caption``
 585 ===========
 586
 587 `To be completed`_.
 588
 589
 590 ``caution``
 591 ===========
 592
 593 `To be completed`_.
 594
 595
 596 ``citation``
 597 ============
 598
 599 `To be completed`_.
 600
 601
 602 ``citation_reference``
 603 ======================
 604
 605 `To be completed`_.
 606
 607
 608 ``classifier``
 609 ==============
 610
 611 The ``classifier`` element contains the classification or type of the
 612 term_ being defined in a definition_list_.  For example, it can be
 613 used to indicate the type of a variable.
 614
 615
 616 Details
 617 -------
 618
 619 :Category: `Body Subelements`_ (simple)
 620
 621 :Parents:
 622     Only the definition_list_item_ element contains ``classifier``.
 623
 624 :Children:
 625     ``classifier`` elements may contain text data plus `inline elements`_.
 626
 627 :Analogues:
 628     ``classifier`` has no direct analogues in common DTDs.  It can be
 629     emulated with primitives or type effects.
 630
 631 :Processing:
 632     See definition_list_item_.
 633
 634
 635 Content Model
 636 -------------
 637
 638 .. parsed-literal::
 639
 640     `%text.model;`_
 641
 642 :Attributes:
 643     The ``classifier`` element contains only the `common attributes`_:
 644     id_, name_, dupname_, source_, and class_.
 645
 646
 647 Examples
 648 --------
 649
 650 Here is a hypothetical data dictionary.  reStructuredText source::
 651
 652     name : string
 653         Customer name.
 654     i : int
 655         Temporary index variable.
 656
 657 Pseudo-XML_ fragment from simple parsing::
 658
 659     <definition_list>
 660         <definition_list_item>
 661             <term>
 662                 name
 663             <classifier>
 664                 string
 665             <definition>
 666                 <paragraph>
 667                     Customer name.
 668         <definition_list_item>
 669             <term>
 670                 i
 671             <classifier>
 672                 int
 673             <definition>
 674                 <paragraph>
 675                     Temporary index variable.
 676
 677
 678 ``colspec``
 679 ===========
 680
 681 `To be completed`_.
 682
 683
 684 ``comment``
 685 ===========
 686
 687 `To be completed`_.
 688
 689
 690 ``contact``
 691 ===========
 692
 693 The ``contact`` element holds contact information for the author
 694 (individual or group) of the document, or a third-party contact.  It
 695 is typically used for an email or web address.
 696
 697
 698 Details
 699 -------
 700
 701 :Category: `Bibliographic Elements`_
 702
 703 :Parents:
 704     The following elements may contain ``contact``: docinfo_, authors_
 705
 706 :Children:
 707     ``contact`` elements may contain text data plus `inline
 708     elements`_.
 709
 710 :Analogues:
 711     ``contact`` is analogous to the DocBook "email" element.  The HTML
 712     "address" element serves a similar purpose.
 713
 714 :Processing:
 715     See docinfo_.
 716
 717
 718 Content Model
 719 -------------
 720
 721 .. parsed-literal::
 722
 723     `%text.model;`_
 724
 725 :Attributes:
 726     The ``contact`` element contains only the `common attributes`_:
 727     id_, name_, dupname_, source_, and class_.
 728
 729 :Parameter Entities:
 730     The `%bibliographic.elements;`_ parameter entity directly includes
 731     ``contact``.
 732
 733
 734 Examples
 735 --------
 736
 737 reStructuredText source::
 738
 739     Document Title
 740     ==============
 741
 742     :Contact: jrh@example.com
 743
 744 Complete pseudo-XML_ result after parsing and applying transforms::
 745
 746     <document id="document-title" name="document title">
 747         <title>
 748             Document Title
 749         <docinfo>
 750             <contact>
 751                 <reference refuri="mailto:jrh@example.com">
 752                     jrh@example.com
 753
 754 See docinfo_ for a more complete example, including processing
 755 context.
 756
 757
 758 ``copyright``
 759 =============
 760
 761 The ``copyright`` element contains the document's copyright statement.
 762
 763
 764 Details
 765 -------
 766
 767 :Category: `Bibliographic Elements`_
 768
 769 :Parents:
 770     Only the docinfo_ element contains ``copyright``.
 771
 772 :Children:
 773     ``copyright`` elements may contain text data plus `inline
 774     elements`_.
 775
 776 :Analogues:
 777     ``copyright`` is analogous to the DocBook "copyright" element.
 778
 779 :Processing:
 780     See docinfo_.
 781
 782
 783 Content Model
 784 -------------
 785
 786 .. parsed-literal::
 787
 788     `%text.model;`_
 789
 790 :Attributes:
 791     The ``copyright`` element contains only the `common attributes`_:
 792     id_, name_, dupname_, source_, and class_.
 793
 794 :Parameter Entities:
 795     The `%bibliographic.elements;`_ parameter entity directly includes
 796     ``copyright``.
 797
 798
 799 Examples
 800 --------
 801
 802 reStructuredText source::
 803
 804     Document Title
 805     ==============
 806
 807     :Copyright: This document has been placed in the public domain.
 808
 809 Complete pseudo-XML_ result after parsing and applying transforms::
 810
 811     <document id="document-title" name="document title">
 812         <title>
 813             Document Title
 814         <docinfo>
 815             <copyright>
 816                 This document has been placed in the public domain.
 817
 818 See docinfo_ for a more complete example, including processing
 819 context.
 820
 821
 822 ``danger``
 823 ==========
 824
 825 `To be completed`_.
 826
 827
 828 ``date``
 829 ========
 830
 831 The ``date`` element contains the date of publication, release, or
 832 last modification of the document.
 833
 834
 835 Details
 836 -------
 837
 838 :Category: `Bibliographic Elements`_
 839
 840 :Parents:
 841     Only the docinfo_ element contains ``date``.
 842
 843 :Children:
 844     ``date`` elements may contain text data plus `inline elements`_.
 845
 846 :Analogues:
 847     ``date`` is analogous to the DocBook "date" element.
 848
 849 :Processing:
 850     Often used with the RCS/CVS keyword "Date".  See docinfo_.
 851
 852
 853 Content Model
 854 -------------
 855
 856 .. parsed-literal::
 857
 858     `%text.model;`_
 859
 860 :Attributes:
 861     The ``date`` element contains only the `common attributes`_:
 862     id_, name_, dupname_, source_, and class_.
 863
 864 :Parameter Entities:
 865     The `%bibliographic.elements;`_ parameter entity directly includes
 866     ``date``.
 867
 868
 869 Examples
 870 --------
 871
 872 reStructuredText source::
 873
 874     Document Title
 875     ==============
 876
 877     :Date: 2002-08-20
 878
 879 Complete pseudo-XML_ result after parsing and applying transforms::
 880
 881     <document id="document-title" name="document title">
 882         <title>
 883             Document Title
 884         <docinfo>
 885             <date>
 886                 2002-08-20
 887
 888 See docinfo_ for a more complete example, including processing
 889 context.
 890
 891
 892 ``decoration``
 893 ==============
 894
 895 The ``decoration`` element is a container for header_ and footer_
 896 elements and potential future extensions.  These elements are used for
 897 page navigation, notes, time/datestamp, etc.  Currently only the
 898 footer_ element is implemented, populated with processing information
 899 (datestamp, a link to Docutils_, etc.).
 900
 901
 902 Details
 903 -------
 904
 905 :Category: `Structural Subelements`_
 906
 907 :Parents:
 908     Only the document_ element contains ``decoration``.
 909
 910 :Children:
 911     ``decoration`` elements may contain `decorative elements`_.
 912
 913 :Analogues:
 914     There are no direct analogies to ``decoration`` in HTML or in
 915     DocBook.  Equivalents are typically constructed from primitives
 916     and/or generated by the processing system.
 917
 918 :Processing:
 919     See the individual `decorative elements`_.
 920
 921 Content Model
 922 -------------
 923
 924 .. parsed-literal::
 925
 926     (header_?, footer_?)
 927
 928 Although the content model doesn't specifically require contents, no
 929 empty ``decoration`` elements are ever created.
 930
 931 :Attributes:
 932     The ``decoration`` element contains only the `common attributes`_:
 933     id_, name_, dupname_, source_, and class_.
 934
 935
 936 Examples
 937 --------
 938
 939 reStructuredText source::
 940
 941     A paragraph.
 942
 943 Complete pseudo-XML_ result after parsing and applying transforms,
 944 assuming that the datestamp command-line option or configuration
 945 setting has been supplied::
 946
 947     <document>
 948         <decoration>
 949             <footer>
 950                 <paragraph>
 951                     Generated on: 2002-08-20.
 952         <paragraph>
 953             A paragraph.
 954
 955
 956 ``definition``
 957 ==============
 958
 959 The ``definition`` element is a container for the body elements used
 960 to define a term_ in a definition_list_.
 961
 962
 963 Details
 964 -------
 965
 966 :Category: `Body Subelements`_ (compound)
 967
 968 :Parents:
 969     Only definition_list_item_ elements contain ``definition``.
 970
 971 :Children:
 972     ``definition`` elements may contain `body elements`_.
 973
 974 :Analogues:
 975     ``definition`` is analogous to the HTML "dd" element and to the
 976     DocBook "listitem" element (inside a "variablelistentry" element).
 977
 978 :Processing:
 979     See definition_list_item_.
 980
 981
 982 Content Model
 983 -------------
 984
 985 .. parsed-literal::
 986
 987     (`%body.elements;`_)+
 988
 989 :Attributes:
 990     The ``definition`` element contains only the `common attributes`_:
 991     id_, name_, dupname_, source_, and class_.
 992
 993
 994 Examples
 995 --------
 996
 997 See the examples for the definition_list_, definition_list_item_, and
 998 classifier_ elements.
 999
1000
1001 ``definition_list``
1002 ===================
1003
1004 The ``definition_list`` element contains a list of terms and their
1005 definitions.  It can be used for glossaries or dictionaries, to
1006 describe or classify things, for dialogues, or to itemize subtopics
1007 (such as in this reference).
1008
1009
1010 Details
1011 -------
1012
1013 :Category: `Compound Body Elements`_
1014
1015 :Parents:
1016     All elements employing the `%body.elements;`_ or
1017     `%structure.model;`_ parameter entities in their content models
1018     may contain ``definition_list``.
1019
1020 :Children:
1021     ``definition_list`` elements contain one or more
1022     definition_list_item_ elements.
1023
1024 :Analogues:
1025     ``definition_list`` is analogous to the HTML "dl" element and to
1026     the DocBook "variablelist" element.
1027
1028 :Processing:
1029     See definition_list_item_.
1030
1031
1032 Content Model
1033 -------------
1034
1035 .. parsed-literal::
1036
1037     (definition_list_item_+)
1038
1039 :Attributes:
1040     The ``definition_list`` element contains only the `common
1041     attributes`_: id_, name_, dupname_, source_, and class_.
1042
1043 :Parameter Entities:
1044     The `%body.elements;`_ parameter entity directly includes
1045     ``definition_list``.  The `%structure.model;`_ parameter entity
1046     indirectly includes ``definition_list``.
1047
1048
1049 Examples
1050 --------
1051
1052 reStructuredText source::
1053
1054     Term
1055       Definition.
1056
1057     Term : classifier
1058         The ' : ' indicates a classifier in
1059         definition list item terms only.
1060
1061 Pseudo-XML_ fragment from simple parsing::
1062
1063     <definition_list>
1064         <definition_list_item>
1065             <term>
1066                 Term
1067             <definition>
1068                 <paragraph>
1069                     Definition.
1070         <definition_list_item>
1071             <term>
1072                 Term
1073             <classifier>
1074                 classifier
1075             <definition>
1076                 <paragraph>
1077                     The ' : ' indicates a classifier in
1078                     definition list item terms only.
1079
1080 See definition_list_item_ and classifier_ for further examples.
1081
1082
1083 ``definition_list_item``
1084 ========================
1085
1086 The ``definition_list_item`` element contains a single
1087 term_/definition_ pair (with optional classifier_).
1088
1089
1090 Details
1091 -------
1092
1093 :Category: `Body Subelements`_ (compound)
1094
1095 :Parents:
1096     Only the definition_list_ element contains
1097     ``definition_list_item``.
1098
1099 :Children:
1100     ``definition_list_item`` elements each contain a single term_,
1101     an optional classifier_, and a definition_.
1102
1103 :Analogues:
1104     ``definition_list_item`` is analogous to the DocBook
1105     "variablelistentry" element.
1106
1107 :Processing:
1108     The optional classifier_ can be rendered differently from the
1109     term_.  They should be separated visually, typically by spaces
1110     plus a colon or dash.
1111
1112
1113 Content Model
1114 -------------
1115
1116 .. parsed-literal::
1117
1118     (term_, classifier_?, definition_)
1119
1120 :Attributes:
1121     The ``definition_list_item`` element contains only the `common
1122     attributes`_: id_, name_, dupname_, source_, and class_.
1123
1124
1125 Examples
1126 --------
1127
1128 reStructuredText source::
1129
1130     Tyrannosaurus Rex : carnivore
1131         Big and scary; the "Tyrant King".
1132
1133     Brontosaurus : herbivore
1134         All brontosauruses are thin at one end,
1135         much much thicker in the middle
1136         and then thin again at the far end.
1137
1138         -- Anne Elk (Miss)
1139
1140 Pseudo-XML_ fragment from simple parsing::
1141
1142     <definition_list>
1143         <definition_list_item>
1144             <term>
1145                 Tyrannosaurus Rex
1146             <classifier>
1147                 carnivore
1148             <definition>
1149                 <paragraph>
1150                     Big and scary; the "Tyrant King".
1151         <definition_list_item>
1152             <term>
1153                 Brontosaurus
1154             <classifier>
1155                 herbivore
1156             <definition>
1157                 <paragraph>
1158                     All brontosauruses are thin at one end,
1159                     much much thicker in the middle
1160                     and then thin again at the far end.
1161                 <paragraph>
1162                     -- Anne Elk (Miss)
1163
1164 See definition_list_ and classifier_ for further examples.
1165
1166
1167 ``description``
1168 ===============
1169
1170 `To be completed`_.
1171
1172
1173 ``docinfo``
1174 ===========
1175
1176 The ``docinfo`` element is a container for document bibliographic
1177 data, or meta-data (data about the document).  It corresponds to the
1178 front matter of a book, such as the title page and copyright page.
1179
1180
1181 Details
1182 -------
1183
1184 :Category: `Structural Subelements`_
1185
1186 :Parents:
1187     Only the document_ element contains ``docinfo``.
1188
1189 :Children:
1190     ``docinfo`` elements contain `bibliographic elements`_.
1191
1192 :Analogues:
1193     ``docinfo`` is analogous to DocBook "info" elements ("bookinfo"
1194     etc.).  There are no directly analogous HTML elements; the "meta"
1195     element carries some of the same information, albeit invisibly.
1196
1197 :Processing:
1198     The ``docinfo`` element may be rendered as a two-column table or
1199     in other styles.  It may even be invisible or omitted from the
1200     processed output.  Meta-data may be extracted from ``docinfo``
1201     children; for example, HTML ``<meta>`` tags may be constructed.
1202
1203     When Docutils_ transforms a reStructuredText_ field_list_ into a
1204     ``docinfo`` element (see the examples below), RCS/CVS keywords are
1205     normally stripped from simple (one paragraph) field bodies.  For
1206     complete details, please see `RCS Keywords`_ in the
1207     `reStructuredText Markup Specification`_.
1208
1209     .. _RCS Keywords: rst/reStructuredText.html#rcs-keywords
1210
1211
1212 Content Model
1213 -------------
1214
1215 .. parsed-literal::
1216
1217     (`%bibliographic.elements;`_)+
1218
1219 :Attributes:
1220     The ``docinfo`` element contains only the `common attributes`_:
1221     id_, name_, dupname_, source_, and class_.
1222
1223
1224 Examples
1225 --------
1226
1227 Docinfo is represented in reStructuredText by a field_list_ in a
1228 bibliographic context: the first non-comment element of a document_,
1229 after any document title_/subtitle_.  The field list is transformed
1230 into a ``docinfo`` element and its children by a transform.  Source::
1231
1232     Docinfo Example
1233     ===============
1234
1235     :Author: J. Random Hacker
1236     :Contact: jrh@example.com
1237     :Date: 2002-08-18
1238     :Status: Work In Progress
1239     :Version: 1
1240     :Filename: $RCSfile$
1241     :Copyright: This document has been placed in the public domain.
1242
1243 Complete pseudo-XML_ result after parsing and applying transforms::
1244
1245     <document id="docinfo-example" name="docinfo example">
1246         <title>
1247             Docinfo Example
1248         <docinfo>
1249             <author>
1250                 J. Random Hacker
1251             <contact>
1252                 <reference refuri="mailto:jrh@example.com">
1253                     jrh@example.com
1254             <date>
1255                 2002-08-18
1256             <status>
1257                 Work In Progress
1258             <version>
1259                 1
1260             <field>
1261                 <field_name>
1262                     Filename
1263                 <field_body>
1264                     <paragraph>
1265                         doctree.txt
1266             <copyright>
1267                 This document has been placed in the public domain.
1268
1269 Note that "Filename" is a non-standard ``docinfo`` field, so becomes a
1270 generic ``field`` element.  Also note that the "RCSfile" keyword
1271 syntax has been stripped from the "Filename" data.
1272
1273 See field_list_ for an example in a non-bibliographic context.  Also
1274 see the individual examples for the various `bibliographic elements`_.
1275
1276
1277 ``doctest_block``
1278 =================
1279
1280 `To be completed`_.
1281
1282
1283 ``document``
1284 ============
1285
1286 The ``document`` element is the root (topmost) element of the Docutils
1287 document tree.  ``document`` is the direct or indirect ancestor of
1288 every other element in the tree.  It encloses the entire document
1289 tree.  It is the starting point for a document.
1290
1291
1292 Details
1293 -------
1294
1295 :Category: `Structural Elements`_
1296
1297 :Parents:
1298     The ``document`` element has no parents.
1299
1300 :Children:
1301     ``document`` elements may contain `structural subelements`_,
1302     `structural elements`_, and `body elements`_.
1303
1304 :Analogues:
1305     ``document`` is analogous to the HTML "html" element and to
1306     several DocBook elements such as "book".
1307
1308
1309 Content Model
1310 -------------
1311
1312 .. parsed-literal::
1313
1314     ((title_,
1315       subtitle_?)?,
1316      docinfo_?,
1317      decoration_?,
1318      `%structure.model;`_)
1319
1320 Depending on the source of the data and the stage of processing, the
1321 "document" may not initially contain a "title".  A document title is
1322 not directly representable in reStructuredText_.  Instead, a lone
1323 top-level section may have its title promoted to become the document
1324 title_, and similarly for a lone second-level (sub)section's title to
1325 become the document subtitle_.  The "docinfo_" may be transformed from
1326 an initial field_list_, and "decoration_" is usually constructed
1327 programmatically.
1328
1329 See the `%structure.model;`_ parameter entity for details of the body
1330 of a ``document``.
1331
1332 :Attributes:
1333     The ``document`` element contains only the `common attributes`_:
1334     id_, name_, dupname_, source_, and class_.
1335
1336
1337 Examples
1338 --------
1339
1340 reStructuredText source::
1341
1342     A Title
1343     =======
1344
1345     A paragraph.
1346
1347 Complete pseudo-XML_ result from simple parsing::
1348
1349     <document>
1350         <section id="a-title" name="a title">
1351             <title>
1352                 A Title
1353             <paragraph>
1354                 A paragraph.
1355
1356 After applying transforms, the section title is promoted to become the
1357 document title::
1358
1359     <document id="a-title" name="a title">
1360         <title>
1361             A Title
1362         <paragraph>
1363             A paragraph.
1364
1365
1366 ``emphasis``
1367 ============
1368
1369 `To be completed`_.
1370
1371
1372 ``entry``
1373 =========
1374
1375 `To be completed`_.
1376
1377
1378 ``enumerated_list``
1379 ===================
1380
1381 The ``enumerated_list`` element contains list_item_ elements which are
1382 uniformly marked with enumerator labels.
1383
1384
1385 Details
1386 -------
1387
1388 :Category: `Compound Body Elements`_
1389
1390 :Parents:
1391     All elements employing the `%body.elements;`_ or
1392     `%structure.model;`_ parameter entities in their content models
1393     may contain ``enumerated_list``.
1394
1395 :Children:
1396     ``enumerated_list`` elements contain one or more list_item_
1397     elements.
1398
1399 :Analogues:
1400     ``enumerated_list`` is analogous to the HTML "ol" element and to
1401     the DocBook "orderedlist" element.
1402
1403 :Processing:
1404     Each list item should begin a new vertical block, prefaced by a
1405     enumeration marker (such as "1.").
1406
1407
1408 Content Model
1409 -------------
1410
1411 .. parsed-literal::
1412
1413     (list_item_+)
1414
1415 :Attributes:
1416     The ``enumerated_list`` element contains the `common attributes`_
1417     (id_, name_, dupname_, source_, and class_), plus enumtype_,
1418     prefix_, suffix_, and start_.
1419
1420     ``enumtype`` is used to record the intended enumeration sequence,
1421     one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z),
1422     "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ...,
1423     mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ...,
1424     MMMMCMXCIX [4999]).
1425
1426     ``prefix`` stores the formatting characters used before the
1427     enumerator.  In documents originating from reStructuredText data,
1428     it will contain either "" (empty string) or "(" (left
1429     parenthesis).  It may or may not affect processing.
1430
1431     ``suffix`` stores the formatting characters used after the
1432     enumerator.  In documents originating from reStructuredText data,
1433     it will contain either "." (period) or ")" (right parenthesis).
1434     Depending on the capabilities of the output format, this attribute
1435     may or may not affect processing.
1436
1437     ``start`` contains the ordinal value of the first item in the
1438     list, in decimal.  For lists beginning at value 1 ("1", "a", "A",
1439     "i", or "I"), this attribute may be omitted.
1440
1441 :Parameter Entities:
1442     The `%body.elements;`_ parameter entity directly includes
1443     ``enumerated_list``.  The `%structure.model;`_ parameter entity
1444     indirectly includes ``enumerated_list``.
1445
1446
1447 Examples
1448 --------
1449
1450 reStructuredText source::
1451
1452     1. Item 1.
1453
1454        (A) Item A.
1455        (B) Item B.
1456        (C) Item C.
1457
1458     2. Item 2.
1459
1460 Pseudo-XML_ fragment from simple parsing::
1461
1462     <enumerated_list enumtype="arabic" prefix="" suffix=".">
1463         <list_item>
1464             <paragraph>
1465                 Item 1.
1466             <enumerated_list enumtype="upperalpha" prefix="(" suffix=")">
1467                 <list_item>
1468                     <paragraph>
1469                         Item A.
1470                 <list_item>
1471                     <paragraph>
1472                         Item B.
1473                 <list_item>
1474                     <paragraph>
1475                         Item C.
1476         <list_item>
1477             <paragraph>
1478                 Item 2.
1479
1480 See list_item_ for another example.
1481
1482
1483 ``error``
1484 =========
1485
1486 `To be completed`_.
1487
1488
1489 ``field``
1490 =========
1491
1492 The ``field`` element contains a pair of field_name_ and field_body_
1493 elements.
1494
1495
1496 Details
1497 -------
1498
1499 :Category: `Body Subelements`_
1500
1501 :Parents:
1502     The following elements may contain ``field``: docinfo_,
1503     field_list_
1504
1505 :Children:
1506     Each ``field`` element contains one field_name_ and one
1507     field_body_ element.
1508
1509 :Analogues:
1510     ``field`` has no direct analogues in common DTDs.
1511
1512 :Processing: See field_list_.
1513
1514
1515 Content Model
1516 -------------
1517
1518 .. parsed-literal::
1519
1520    (field_name_, field_body_)
1521
1522 :Attributes:
1523     The ``field`` element contains only the `common attributes`_:
1524     id_, name_, dupname_, source_, and class_.
1525
1526 :Parameter Entities:
1527     The `%bibliographic.elements;`_ parameter entity directly includes
1528     ``field``.
1529
1530
1531 Examples
1532 --------
1533
1534 See the examples for the field_list_ and docinfo_ elements.
1535
1536
1537 ``field_body``
1538 ==============
1539
1540 The ``field_body`` element contains body elements.  It is analogous to
1541 a database field's data.
1542
1543
1544 Details
1545 -------
1546
1547 :Category: `Body Subelements`_
1548
1549 :Parents:
1550     Only the field_ element contains ``field_body``.
1551
1552 :Children:
1553     ``field_body`` elements may contain `body elements`_.
1554
1555 :Analogues:
1556     ``field_body`` has no direct analogues in common DTDs.
1557
1558 :Processing: See field_list_.
1559
1560
1561 Content Model
1562 -------------
1563
1564 .. parsed-literal::
1565
1566    (`%body.elements;`_)*
1567
1568 :Attributes:
1569     The ``field_body`` element contains only the `common attributes`_:
1570     id_, name_, dupname_, source_, and class_.
1571
1572
1573 Examples
1574 --------
1575
1576 See the examples for the field_list_ and docinfo_ elements.
1577
1578
1579 ``field_list``
1580 ==============
1581
1582 The ``field_list`` element contains two-column table-like structures
1583 resembling database records (label & data pairs).  Field lists are
1584 often meant for further processing.  In reStructuredText, field lists
1585 are used to represent bibliographic fields (contents of the docinfo_
1586 element) and directive options.
1587
1588
1589 Details
1590 -------
1591
1592 :Category: `Compound Body Elements`_
1593
1594 :Parents:
1595     All elements employing the `%body.elements;`_ or
1596     `%structure.model;`_ parameter entities in their content models
1597     may contain ``field_list``.
1598
1599 :Children:
1600     ``field_list`` elements contain one or more field_ elements.
1601
1602 :Analogues:
1603     ``field_list`` has no direct analogues in common DTDs.  It can be
1604     emulated with primitives such as tables.
1605
1606 :Processing:
1607     A ``field_list`` is typically rendered as a two-column list, where
1608     the first column contains "labels" (usually with a colon suffix).
1609     However, field lists are often used for extension syntax or
1610     special processing.  Such structures do not survive as field lists
1611     to be rendered.
1612
1613
1614 Content Model
1615 -------------
1616
1617 .. parsed-literal::
1618
1619    (field_+)
1620
1621 :Attributes:
1622     The ``field_list`` element contains only the `common attributes`_:
1623     id_, name_, dupname_, source_, and class_.
1624
1625 :Parameter Entities:
1626     The `%body.elements;`_ parameter entity directly includes
1627     ``field_list``.  The `%structure.model;`_ parameter entity
1628     indirectly includes ``field_list``.
1629
1630
1631 Examples
1632 --------
1633
1634 reStructuredText source::
1635
1636     :Author: Me
1637     :Version: 1
1638     :Date: 2001-08-11
1639     :Parameter i: integer
1640
1641 Pseudo-XML_ fragment from simple parsing::
1642
1643     <field_list>
1644         <field>
1645             <field_name>
1646                 Author
1647             <field_body>
1648                 <paragraph>
1649                     Me
1650         <field>
1651             <field_name>
1652                 Version
1653             <field_body>
1654                 <paragraph>
1655                     1
1656         <field>
1657             <field_name>
1658                 Date
1659             <field_body>
1660                 <paragraph>
1661                     2001-08-11
1662         <field>
1663             <field_name>
1664                 Parameter i
1665             <field_body>
1666                 <paragraph>
1667                     integer
1668
1669
1670 ``field_name``
1671 ==============
1672
1673 The ``field_name`` element contains text data only.  It is analogous
1674 to a database field's name.
1675
1676
1677 Details
1678 -------
1679
1680 :Category: `Body Subelements`_
1681
1682 :Parents:
1683     Only the field_ element contains ``field_name``.
1684
1685 :Children:
1686     ``field_name`` elements have no children.  They may contain text
1687     data only.
1688
1689 :Analogues:
1690     ``field_name`` has no direct analogues in common DTDs.
1691
1692 :Processing: See field_list_.
1693
1694
1695 Content Model
1696 -------------
1697
1698 .. parsed-literal::
1699
1700    (#PCDATA)
1701
1702 :Attributes:
1703     The ``field_name`` element contains only the `common attributes`_:
1704     id_, name_, dupname_, source_, and class_.
1705
1706
1707 Examples
1708 --------
1709
1710 See the examples for the field_list_ and docinfo_ elements.
1711
1712
1713 ``figure``
1714 ==========
1715
1716 `To be completed`_.
1717
1718
1719 ``footer``
1720 ==========
1721
1722 The ``footer`` element is a container element whose contents are meant
1723 to appear at the bottom of a web page, or repeated at the bottom of
1724 every printed page.  Currently the ``footer`` element may contain
1725 processing information (datestamp, a link to Docutils_, etc.).
1726
1727
1728 Details
1729 -------
1730
1731 :Category: `Decorative Elements`_
1732
1733 :Parents:
1734     Only the decoration_ element contains ``footer``.
1735
1736 :Children:
1737     ``footer`` elements may contain `body elements`_.
1738
1739 :Analogues:
1740     There are no direct analogies to ``footer`` in HTML or DocBook.
1741     Equivalents are typically constructed from primitives and/or
1742     generated by the processing system.
1743
1744
1745 Content Model
1746 -------------
1747
1748 .. parsed-literal::
1749
1750     (`%body.elements;`_)+
1751
1752 :Attributes:
1753     The ``footer`` element contains only the `common attributes`_:
1754     id_, name_, dupname_, source_, and class_.
1755
1756
1757 Examples
1758 --------
1759
1760 reStructuredText source::
1761
1762     A paragraph.
1763
1764 Complete pseudo-XML_ result after parsing and applying transforms,
1765 assuming that the datestamp command-line option or configuration
1766 setting has been supplied::
1767
1768     <document>
1769         <decoration>
1770             <footer>
1771                 <paragraph>
1772                     Generated on: 2002-08-20.
1773         <paragraph>
1774             A paragraph.
1775
1776
1777 ``footnote``
1778 ============
1779
1780 `To be completed`_.
1781
1782
1783 ``footnote_reference``
1784 ======================
1785
1786 `To be completed`_.
1787
1788
1789 ``generated``
1790 =============
1791
1792 `To be completed`_.
1793
1794
1795 ``header``
1796 ==========
1797
1798 The ``header`` element is a container element whose contents are meant
1799 to appear at the top of a web page, or at the top of every printed
1800 page.  Docutils does not yet make use of the ``header`` element.
1801
1802
1803 Details
1804 -------
1805
1806 :Category: `Decorative Elements`_
1807
1808 :Parents:
1809     Only the decoration_ element contains ``header``.
1810
1811 :Children:
1812     ``header`` elements may contain `body elements`_.
1813
1814 :Analogues:
1815     There are no direct analogies to ``header`` in HTML or DocBook.
1816     Equivalents are typically constructed from primitives and/or
1817     generated by the processing system.
1818
1819
1820 Content Model
1821 -------------
1822
1823 .. parsed-literal::
1824
1825     (`%body.elements;`_)+
1826
1827 :Attributes:
1828     The ``header`` element contains only the `common attributes`_:
1829     id_, name_, dupname_, source_, and class_.
1830
1831
1832 Examples
1833 --------
1834
1835 None.
1836
1837
1838 ``hint``
1839 ========
1840
1841 `To be completed`_.
1842
1843
1844 ``image``
1845 =========
1846
1847 `To be completed`_.
1848
1849
1850 ``important``
1851 =============
1852
1853 `To be completed`_.
1854
1855
1856 ``interpreted``
1857 ===============
1858
1859 `To be completed`_.
1860
1861
1862 ``label``
1863 =========
1864
1865 `To be completed`_.
1866
1867
1868 ``legend``
1869 ==========
1870
1871 `To be completed`_.
1872
1873
1874 ``line_block``
1875 ==============
1876
1877 `To be completed`_.
1878
1879
1880 ``list_item``
1881 =============
1882
1883 The ``list_item`` element is a container for the elements of a list
1884 item.
1885
1886
1887 Details
1888 -------
1889
1890 :Category: `Body Subelements`_ (compound)
1891
1892 :Parents:
1893     The bullet_list_ and enumerated_list_ elements contain
1894     ``list_item``.
1895
1896 :Children:
1897     ``list_item`` elements may contain `body elements`_.
1898
1899 :Analogues:
1900     ``list_item`` is analogous to the HTML "li" element and to the
1901     DocBook "listitem" element.
1902
1903 :Processing:
1904     See bullet_list_ or enumerated_list_.
1905
1906
1907 Content Model
1908 -------------
1909
1910 .. parsed-literal::
1911
1912     (`%body.elements;`_)+
1913
1914 :Attributes:
1915     The ``list_item`` element contains only the `common attributes`_:
1916     id_, name_, dupname_, source_, and class_.
1917
1918
1919 Examples
1920 --------
1921
1922 reStructuredText source::
1923
1924     1. Outer list, item 1.
1925
1926        * Inner list, item 1.
1927        * Inner list, item 2.
1928
1929     2. Outer list, item 2.
1930
1931 Pseudo-XML_ fragment from simple parsing::
1932
1933     <enumerated_list enumtype="arabic" prefix="" suffix=".">
1934         <list_item>
1935             <paragraph>
1936                 Outer list, item 1.
1937             <bullet_list bullet="*">
1938                 <list_item>
1939                     <paragraph>
1940                         Inner list, item 1.
1941                 <list_item>
1942                     <paragraph>
1943                         Inner list, item 2.
1944         <list_item>
1945             <paragraph>
1946                 Outer list, item 2.
1947
1948 See bullet_list_ or enumerated_list_ for further examples.
1949
1950
1951 ``literal``
1952 ===========
1953
1954 `To be completed`_.
1955
1956
1957 ``literal_block``
1958 =================
1959
1960 `To be completed`_.
1961
1962
1963 ``note``
1964 ========
1965
1966 `To be completed`_.
1967
1968
1969 ``option``
1970 ==========
1971
1972 `To be completed`_.
1973
1974
1975 ``option_argument``
1976 ===================
1977
1978 `To be completed`_.
1979
1980
1981 ``option_group``
1982 ================
1983
1984 `To be completed`_.
1985
1986
1987 ``option_list``
1988 ===============
1989
1990 `To be completed`_.
1991
1992
1993 ``option_list_item``
1994 ====================
1995
1996 `To be completed`_.
1997
1998
1999 ``option_string``
2000 =================
2001
2002 `To be completed`_.
2003
2004
2005 ``organization``
2006 ================
2007
2008 The ``organization`` element contains the name of document author's
2009 organization, or the organization responsible for the document.
2010
2011
2012 Details
2013 -------
2014
2015 :Category: `Bibliographic Elements`_
2016
2017 :Parents:
2018     Only the docinfo_ element contains ``organization``.
2019
2020 :Children:
2021     ``organization`` elements may contain text data plus `inline
2022     elements`_.
2023
2024 :Analogues:
2025     ``organization`` is analogous to the DocBook "orgname",
2026     "corpname", or "publishername" elements.
2027
2028 :Processing:
2029     See docinfo_.
2030
2031
2032 Content Model
2033 -------------
2034
2035 .. parsed-literal::
2036
2037     `%text.model;`_
2038
2039 :Attributes:
2040     The ``organization`` element contains only the `common attributes`_:
2041     id_, name_, dupname_, source_, and class_.
2042
2043 :Parameter Entities:
2044     The `%bibliographic.elements;`_ parameter entity directly includes
2045     ``organization``.
2046
2047
2048 Examples
2049 --------
2050
2051 reStructuredText source::
2052
2053     Document Title
2054     ==============
2055
2056     :Organization: Humankind
2057
2058 Complete pseudo-XML_ result after parsing and applying transforms::
2059
2060     <document id="document-title" name="document title">
2061         <title>
2062             Document Title
2063         <docinfo>
2064             <organization>
2065                 Humankind
2066
2067 See docinfo_ for a more complete example, including processing
2068 context.
2069
2070
2071 ``paragraph``
2072 =============
2073
2074 The ``paragraph`` element contains the text and inline elements of a
2075 single paragraph, a fundamental building block of documents.
2076
2077
2078 Details
2079 -------
2080
2081 :Category: `Simple Body Elements`_
2082
2083 :Parents:
2084     All elements employing the `%body.elements;`_ or
2085     `%structure.model;`_ parameter entities in their content models
2086     may contain ``paragraph``.
2087
2088 :Children:
2089     ``paragraph`` elements may contain text data plus `inline
2090     elements`_.
2091
2092 :Analogues:
2093     ``paragraph`` is analogous to the HTML "p" element and to the
2094     DocBook "para" elements.
2095
2096
2097 Content Model
2098 -------------
2099
2100 .. parsed-literal::
2101
2102     `%text.model;`_
2103
2104 :Attributes:
2105     The ``paragraph`` element contains only the `common attributes`_:
2106     id_, name_, dupname_, source_, and class_.
2107
2108 :Parameter Entities:
2109     The `%body.elements;`_ parameter entity directly includes
2110     ``paragraph``.  The `%structure.model;`_ parameter entity
2111     indirectly includes ``paragraph``.
2112
2113
2114 Examples
2115 --------
2116
2117 reStructuredText source::
2118
2119     A paragraph.
2120
2121 Pseudo-XML_ fragment from simple parsing::
2122
2123     <paragraph>
2124         A paragraph.
2125
2126
2127 ``pending``
2128 ===========
2129
2130 `To be completed`_.
2131
2132
2133 ``problematic``
2134 ===============
2135
2136 `To be completed`_.
2137
2138
2139 ``raw``
2140 =======
2141
2142 `To be completed`_.
2143
2144
2145 ``reference``
2146 =============
2147
2148 `To be completed`_.
2149
2150
2151 ``revision``
2152 ============
2153
2154 The ``revision`` element contains the revision number of the document.
2155 It can be used alone or in conjunction with version_.
2156
2157
2158 Details
2159 -------
2160
2161 :Category: `Bibliographic Elements`_
2162
2163 :Parents:
2164     Only the docinfo_ element contains ``revision``.
2165
2166 :Children:
2167     ``revision`` elements may contain text data plus `inline
2168     elements`_.
2169
2170 :Analogues:
2171     ``revision`` is analogous to but simpler than the DocBook
2172     "revision" element.  It closely matches the DocBook "revnumber"
2173     element, but in a simpler context.
2174
2175 :Processing:
2176     Often used with the RCS/CVS keyword "Revision".  See docinfo_.
2177
2178
2179 Content Model
2180 -------------
2181
2182 .. parsed-literal::
2183
2184     `%text.model;`_
2185
2186 :Attributes:
2187     The ``revision`` element contains only the `common attributes`_:
2188     id_, name_, dupname_, source_, and class_.
2189
2190 :Parameter Entities:
2191     The `%bibliographic.elements;`_ parameter entity directly includes
2192     ``revision``.
2193
2194
2195 Examples
2196 --------
2197
2198 reStructuredText source::
2199
2200     Document Title
2201     ==============
2202
2203     :Version: 1
2204     :Revision: b
2205
2206 Complete pseudo-XML_ result after parsing and applying transforms::
2207
2208     <document id="document-title" name="document title">
2209         <title>
2210             Document Title
2211         <docinfo>
2212             <version>
2213                 1
2214             <revision>
2215                 b
2216
2217 See docinfo_ for a more complete example, including processing
2218 context.
2219
2220
2221 ``row``
2222 =======
2223
2224 `To be completed`_.
2225
2226
2227 ``section``
2228 ===========
2229
2230 The ``section`` element is the main unit of hierarchy for Docutils
2231 documents.  Docutils ``section`` elements are a recursive structure; a
2232 ``section`` may contain other ``section`` elements, without limit.
2233 Paragraphs and other body elements may occur before a ``section``, but
2234 not after it.
2235
2236
2237 Details
2238 -------
2239
2240 :Category: `Structural Elements`_
2241
2242 :Parents:
2243     The following elements may contain ``section``: document_,
2244     section_
2245
2246 :Children:
2247     ``section`` elements begin with a title_, and may contain `body
2248     elements`_ and transition_ and topic_ elements.
2249
2250 :Analogues:
2251     ``section`` is analogous to DocBook recursive "section" elements,
2252     and to HTML "div" elements combined with "h1" etc. title elements.
2253
2254
2255 Content Model
2256 -------------
2257
2258 .. parsed-literal::
2259
2260     (title_,
2261      `%structure.model;`_)
2262
2263 See the `%structure.model;`_ parameter entity for details of the body
2264 of a ``section``.
2265
2266 :Attributes:
2267     The ``section`` element contains only the `common attributes`_:
2268     id_, name_, dupname_, source_, and class_.
2269
2270 :Parameter Entities:
2271     The `%section.elements;`_ parameter entity directly includes
2272     ``section``.  The `%structure.model;`_ parameter entity indirectly
2273     includes ``section``.
2274
2275
2276 Examples
2277 --------
2278
2279 reStructuredText source::
2280
2281     Title 1
2282     =======
2283     Paragraph 1.
2284
2285     Title 2
2286     -------
2287     Paragraph 2.
2288
2289     Title 3
2290     =======
2291     Paragraph 3.
2292
2293     Title 4
2294     -------
2295     Paragraph 4.
2296
2297 Complete pseudo-XML_ result after parsing::
2298
2299     <document>
2300         <section id="title-1" name="title 1">
2301             <title>
2302                 Title 1
2303             <paragraph>
2304                 Paragraph 1.
2305             <section id="title-2" name="title 2">
2306                 <title>
2307                     Title 2
2308                 <paragraph>
2309                     Paragraph 2.
2310         <section id="title-3" name="title 3">
2311             <title>
2312                 Title 3
2313             <paragraph>
2314                 Paragraph 3.
2315             <section id="title-4" name="title 4">
2316                 <title>
2317                     Title 4
2318                 <paragraph>
2319                     Paragraph 4.
2320
2321
2322 ``status``
2323 ==========
2324
2325 The ``status`` element contains a status statement for the document,
2326 such as "Draft", "Final", "Work In Progress", etc.
2327
2328
2329 Details
2330 -------
2331
2332 :Category: `Bibliographic Elements`_
2333
2334 :Parents:
2335     Only the docinfo_ element contains ``status``.
2336
2337 :Children:
2338     ``status`` elements may contain text data plus `inline elements`_.
2339
2340 :Analogues:
2341     ``status`` is analogous to the DocBook "status" element.
2342
2343 :Processing:
2344     See docinfo_.
2345
2346
2347 Content Model
2348 -------------
2349
2350 .. parsed-literal::
2351
2352     `%text.model;`_
2353
2354 :Attributes:
2355     The ``status`` element contains only the `common attributes`_:
2356     id_, name_, dupname_, source_, and class_.
2357
2358 :Parameter Entities:
2359     The `%bibliographic.elements;`_ parameter entity directly includes
2360     ``status``.
2361
2362
2363 Examples
2364 --------
2365
2366 reStructuredText source::
2367
2368     Document Title
2369     ==============
2370
2371     :Status: Work In Progress
2372
2373 Complete pseudo-XML_ result after parsing and applying transforms::
2374
2375     <document id="document-title" name="document title">
2376         <title>
2377             Document Title
2378         <docinfo>
2379             <status>
2380                 Work In Progress
2381
2382 See docinfo_ for a more complete example, including processing
2383 context.
2384
2385
2386 ``strong``
2387 ==========
2388
2389 `To be completed`_.
2390
2391
2392 ``substitution_definition``
2393 ===========================
2394
2395 `To be completed`_.
2396
2397
2398 ``substitution_reference``
2399 ==========================
2400
2401 `To be completed`_.
2402
2403
2404 ``subtitle``
2405 ============
2406
2407 The ``subtitle`` element stores the subtitle of a document_.
2408
2409
2410 Details
2411 -------
2412
2413 :Category: `Structural Subelements`_
2414
2415 :Parents:
2416     Only the document_ element contains ``subtitle``.
2417
2418 :Children:
2419     ``subtitle`` elements may contain text data plus `inline
2420     elements`_.
2421
2422 :Analogues:
2423     ``subtitle`` is analogous to HTML header elements ("h2" etc.) and
2424     to the DocBook "subtitle" element.
2425
2426 :Processing:
2427     A document's subtitle is usually rendered smaller than its title_.
2428
2429
2430 Content Model
2431 -------------
2432
2433 .. parsed-literal::
2434
2435     `%text.model;`_
2436
2437 :Attributes:
2438     The ``subtitle`` element contains only the `common attributes`_:
2439     id_, name_, dupname_, source_, and class_.
2440
2441
2442 Examples
2443 --------
2444
2445 reStructuredText source::
2446
2447     =======
2448      Title
2449     =======
2450     ----------
2451      Subtitle
2452     ----------
2453
2454     A paragraph.
2455
2456 Complete pseudo-XML_ result after parsing and applying transforms::
2457
2458     <document id="title" name="title">
2459         <title>
2460             Title
2461         <subtitle id="subtitle" name="subtitle">
2462             Subtitle
2463         <paragraph>
2464             A paragraph.
2465
2466 Note how two section levels have collapsed, promoting their titles to
2467 become the document's title and subtitle.  Since there is only one
2468 structural element (document), the subsection's ``id`` and ``name``
2469 attributes are stored in the ``subtitle`` element.
2470
2471
2472 ``system_message``
2473 ==================
2474
2475 `To be completed`_.
2476
2477
2478 ``table``
2479 =========
2480
2481 `To be completed`_.
2482
2483
2484 ``target``
2485 ==========
2486
2487 `To be completed`_.
2488
2489
2490 ``tbody``
2491 =========
2492
2493 `To be completed`_.
2494
2495
2496 ``term``
2497 ========
2498
2499 The ``term`` element contains a word or phrase being defined in a
2500 definition_list_.
2501
2502
2503 Details
2504 -------
2505
2506 :Category: `Body Subelements`_ (simple)
2507
2508 :Parents:
2509     Only the definition_list_item_ element contains ``term``.
2510
2511 :Children:
2512     ``term`` elements may contain text data plus `inline elements`_.
2513
2514 :Analogues:
2515     ``term`` is analogous to the HTML "dt" element and to the DocBook
2516     "term" element.
2517
2518 :Processing:
2519     See definition_list_item_.
2520
2521
2522 Content Model
2523 -------------
2524
2525 .. parsed-literal::
2526
2527     `%text.model;`_
2528
2529 :Attributes:
2530     The ``term`` element contains only the `common attributes`_:
2531     id_, name_, dupname_, source_, and class_.
2532
2533
2534 Examples
2535 --------
2536
2537 See the examples for the definition_list_, definition_list_item_, and
2538 classifier_ elements.
2539
2540
2541 ``tgroup``
2542 ==========
2543
2544 `To be completed`_.
2545
2546
2547 ``thead``
2548 =========
2549
2550 `To be completed`_.
2551
2552
2553 ``tip``
2554 =======
2555
2556 `To be completed`_.
2557
2558
2559 ``title``
2560 =========
2561
2562 The ``title`` element stores the title of a document_, section_, or
2563 topic_.
2564
2565
2566 Details
2567 -------
2568
2569 :Category: `Structural Subelements`_
2570
2571 :Parents:
2572     The following elements may contain ``title``: document_, section_,
2573     topic_
2574
2575 :Children:
2576     ``title`` elements may contain text data plus `inline elements`_.
2577
2578 :Analogues:
2579     ``title`` is analogous to HTML "title" and header ("h1" etc.)
2580     elements, and to the DocBook "title" element.
2581
2582
2583 Content Model
2584 -------------
2585
2586 .. parsed-literal::
2587
2588     `%text.model;`_
2589
2590 :Attributes:
2591     The ``title`` element contains the `common attributes`_ (id_,
2592     name_, dupname_, source_, and class_), plus refid_ and auto_.
2593
2594     ``refid`` is used as a backlink to a table of contents entry.
2595
2596     ``auto`` is used to indicate (with value "1") that the ``title``
2597     has been numbered automatically.
2598
2599
2600 Examples
2601 --------
2602
2603 reStructuredText source::
2604
2605     A Title
2606     =======
2607
2608     A paragraph.
2609
2610 Pseudo-XML_ fragment from simple parsing::
2611
2612     <section id="a-title" name="a title">
2613         <title>
2614             A Title
2615         <paragraph>
2616             A paragraph.
2617
2618
2619 ``topic``
2620 =========
2621
2622 The ``topic`` element is a nonrecursive section_-like construct which
2623 may occur at the top level of a section_ wherever a body element
2624 (list, table, etc.) is allowed.  In other words, ``topic`` elements
2625 cannot nest inside body elements, so you can't have a ``topic`` inside
2626 a ``table`` or a ``list``, or inside another ``topic``.
2627
2628
2629 Details
2630 -------
2631
2632 :Category: `Structural Elements`_
2633
2634 :Parents:
2635     The following elements may contain ``topic``: document_, section_
2636
2637 :Children:
2638     ``topic`` elements begin with a title_ and may contain `body
2639     elements`_.
2640
2641 :Analogues:
2642     ``topic`` is analogous to the DocBook "simplesect" element.
2643
2644 :Processing:
2645     A ``topic`` element should be set off from the rest of the
2646     document somehow, such as with indentation or a border.
2647
2648
2649 Content Model
2650 -------------
2651
2652 .. parsed-literal::
2653
2654     (title_?,
2655      (`%body.elements;`_)+)
2656
2657 :Attributes:
2658     The ``topic`` element contains only the `common attributes`_:
2659     id_, name_, dupname_, source_, and class_.
2660
2661 :Parameter Entities:
2662     The `%structure.model;`_ parameter entity directly includes
2663     ``topic``.
2664
2665
2666 Examples
2667 --------
2668
2669 The `"topic" directive`_ is used to create a ``topic`` element.
2670 reStructuredText source::
2671
2672     .. topic:: Title
2673
2674        Body.
2675
2676 Pseudo-XML_ fragment from simple parsing::
2677
2678     <topic>
2679         <title>
2680             Title
2681         <paragraph>
2682             Body.
2683
2684 .. _"topic" directive: rst/directives.html#topic
2685
2686
2687 ``transition``
2688 ==============
2689
2690 The ``transition`` element is commonly seen in novels and short
2691 fiction, as a gap spanning one or more lines, with or without a type
2692 ornament such as a row of asterisks.  Transitions separate other body
2693 elements, dividing a section into untitled divisions.  A transition
2694 may not begin or end a section or document, nor may two transitions be
2695 immediately adjacent.
2696
2697 See `Representation of Horizontal Rules`_ below.
2698
2699
2700 Details
2701 -------
2702
2703 :Category: `Structural Subelements`_
2704
2705 :Parents:
2706     The following elements may contain ``transition``: document_,
2707     section_
2708
2709 :Children:
2710     ``transition`` is an empty element and has no children.
2711
2712 :Analogues:
2713     ``transition`` is analogous to the HTML "hr" element.
2714
2715 :Processing:
2716     The ``transition`` element is typically rendered as vertical
2717     whitespace (more than that separating paragraphs), with or without
2718     a horizontal line or row of asterisks.  In novels, transitions are
2719     often represented as a row of three well-spaced asterisks with
2720     vertical space above and below.
2721
2722
2723 Content Model
2724 -------------
2725
2726 ::
2727
2728     EMPTY
2729
2730 The ``transition`` element has no content; it is a "point element".
2731
2732 :Attributes:
2733     The ``transition`` element contains only the `common attributes`_:
2734     id_, name_, dupname_, source_, and class_.
2735
2736 :Parameter Entities:
2737     The `%structure.model;`_ parameter entity directly includes
2738     ``transition``.
2739
2740
2741 Examples
2742 --------
2743
2744 reStructuredText source::
2745
2746     Paragraph 1.
2747
2748     --------
2749
2750     Paragraph 2.
2751
2752 Complete pseudo-XML_ result after parsing::
2753
2754     <document>
2755         <paragraph>
2756             Paragraph 1.
2757         <transition>
2758         <paragraph>
2759             Paragraph 2.
2760
2761
2762 ``version``
2763 ===========
2764
2765 The ``version`` element contains the version number of the document.
2766 It can be used alone or in conjunction with revision_.
2767
2768
2769 Details
2770 -------
2771
2772 :Category: `Bibliographic Elements`_
2773
2774 :Parents:
2775     Only the docinfo_ element contains ``version``.
2776
2777 :Children:
2778     ``version`` elements may contain text data plus `inline
2779     elements`_.
2780
2781 :Analogues:
2782     ``version`` may be considered analogous to the DocBook "revision",
2783     "revnumber", or "biblioid" elements.
2784
2785 :Processing:
2786     Sometimes used with the RCS/CVS keyword "Revision".  See docinfo_
2787     and revision_.
2788
2789
2790 Content Model
2791 -------------
2792
2793 .. parsed-literal::
2794
2795     `%text.model;`_
2796
2797 :Attributes:
2798     The ``version`` element contains only the `common attributes`_:
2799     id_, name_, dupname_, source_, and class_.
2800
2801 :Parameter Entities:
2802     The `%bibliographic.elements;`_ parameter entity directly includes
2803     ``version``.
2804
2805
2806 Examples
2807 --------
2808
2809 reStructuredText source::
2810
2811     Document Title
2812     ==============
2813
2814     :Version: 1.1
2815
2816 Complete pseudo-XML_ result after parsing and applying transforms::
2817
2818     <document id="document-title" name="document title">
2819         <title>
2820             Document Title
2821         <docinfo>
2822             <version>
2823                 1.1
2824
2825 See docinfo_ for a more complete example, including processing
2826 context.
2827
2828
2829 ``warning``
2830 ===========
2831
2832 `To be completed`_.
2833
2834
2835 ---------------------
2836  Attribute Reference
2837 ---------------------
2838
2839 .. contents:: :local:
2840               :depth: 1
2841
2842 _`Common Attributes`: Through the `%basic.atts;`_ parameter entity,
2843 all elements contain the following attributes: id_, name_, dupname_,
2844 source_, and class_.
2845
2846 .. _attribute type:
2847
2848 Attribute types:
2849
2850 ``CDATA``
2851     Character data.  ``CDATA`` attributes may contain arbitrary text.
2852
2853 ``ID``
2854     Like a ``NMTOKEN``, but it must begin with a letter (a "name
2855     production").  Identical ``ID`` values must not appear more than
2856     once in a document; i.e., ID values must uniquely identify their
2857     elements.
2858
2859 ``IDREF``
2860     A reference to an ``ID`` value (a name production) of another
2861     element.
2862
2863 ``IDREFS``
2864     One or more space-separated ``ID`` references (name productions).
2865
2866 ``NMTOKEN``
2867     A "name token".  One or more of letters, digits, ".", "-", and
2868     "_".
2869
2870 ``NMTOKENS``
2871     One or more space-separated ``NMTOKEN`` names.
2872
2873 ``%yesorno;``
2874     No if zero ("0"), yes if any other value.  This is a parameter
2875     entity which resolves to a ``NMTOKEN`` attribute type.
2876
2877 ``%number;``
2878     This emphasizes that the attribute value must be a number.  This
2879     is a parameter entity which resolves to a ``NMTOKEN`` attribute
2880     type.
2881
2882 enumeration
2883     The attribute value may be one of a specified list of values.
2884
2885
2886 ``anonymous``
2887 =============
2888
2889 `Attribute type`_: ``%yesorno;``.  Default value: none (implies no).
2890
2891 The ``anonymous`` attribute is used for unnamed hyperlinks in the
2892 target_ and reference_ elements (via the `%anonymous.att;`_ parameter
2893 entity).
2894
2895
2896 ``auto``
2897 ========
2898
2899 `Attribute type`_: ``CDATA``.  Default value: none.
2900
2901 The ``auto`` attribute is used to indicate automatically-numbered
2902 footnote_, footnote_reference_ and title_ elements (via the
2903 `%auto.att;`_ parameter entity).
2904
2905
2906 ``backrefs``
2907 ============
2908
2909 `Attribute type`_: ``IDREFS``.  Default value: none.
2910
2911 The ``backrefs`` attribute contains a space-separated list of id_
2912 references, used for backlinks from footnote_, citation_, and
2913 system_message_ elements (via the `%backrefs.att;`_ parameter entity).
2914
2915
2916 ``bullet``
2917 ==========
2918
2919 `Attribute type`_: ``CDATA``.  Default value: none.
2920
2921 The ``bullet`` attribute is used in the bullet_list_ element.
2922
2923
2924 ``class``
2925 =========
2926
2927 `Attribute type`_: ``NMTOKENS``.  Default value: none.
2928
2929 The ``class`` attribute contains one or more names used to classify an
2930 element.  It can be used to carry context forward between a Docutils
2931 Reader and Writer, when a custom structure is reduced to a
2932 standardized document tree.  ``class`` is one of the `common
2933 attributes`_, shared by all Docutils elements.
2934
2935
2936 ``dupname``
2937 ===========
2938
2939 `Attribute type`_: ``NMTOKENS``.  Default value: none.
2940
2941 The ``dupname`` attribute contains the name of an element when there
2942 has been a naming conflict.  The contents of the ``dupname`` attribute
2943 would have been transferred from the `name`_ attribute.  An element
2944 may have at most one of the ``name`` or ``dupname`` attributes, but
2945 not both.  ``dupname`` is one of the `common attributes`_, shared by
2946 all Docutils elements.
2947
2948
2949 ``enumtype``
2950 ============
2951
2952 `Attribute type`_: enumeration, one of "arabic", "loweralpha",
2953 "upperalpha", "lowerroman", or "upperroman".  Default value: none.
2954
2955 The ``enumtype`` attribute is used in the enumerated_list_ element.
2956
2957
2958 ``id``
2959 ======
2960
2961 `Attribute type`_: ``ID``.  Default value: none.
2962
2963 The ``id`` attribute contains a unique identifier key.  ``id`` is one
2964 of the `common attributes`_, shared by all Docutils elements.
2965
2966
2967 ``name``
2968 ========
2969
2970 `Attribute type`_: ``NMTOKENS``.  Default value: none.
2971
2972 The ``name`` attribute contains the name of an element, typically
2973 originating from the element's title or content.  ``name`` must be
2974 unique; if there are name conflicts (two or more elements want to the
2975 same name), the contents will be transferred to the `dupname`_
2976 attribute on the duplicate elements.  An element may have at most one
2977 of the ``name`` or ``dupname`` attributes, but not both.  ``name`` is
2978 one of the `common attributes`_, shared by all Docutils elements.
2979
2980
2981 ``prefix``
2982 ==========
2983
2984 `Attribute type`_: ``CDATA``.  Default value: none.
2985
2986 The ``prefix`` attribute is used in the enumerated_list_ element.
2987
2988
2989 ``refid``
2990 =========
2991
2992 `Attribute type`_: ``IDREF``.  Default value: none.
2993
2994 The ``refid`` attribute contains references to `id`_ attributes in
2995 other elements.  It is used by the target_, reference_,
2996 footnote_reference_, citation_reference_, title_ and problematic_
2997 elements (via the `%refid.att;`_ and `%reference.atts;`_ parameter
2998 entities).
2999
3000
3001 ``refname``
3002 ===========
3003
3004 `Attribute type`_: ``NMTOKENS``.  Default value: none.
3005
3006 The ``refname`` attribute contains an internal reference to the
3007 `name`_ attribute of another element.  On a `target`_ element,
3008 ``refname`` indicates an indirect target which may resolve to either
3009 an internal or external reference.  ``refname`` is used by the
3010 target_, reference_, footnote_reference_, citation_reference_, and
3011 substitution_reference_ elements (via the `%refname.att;`_ and
3012 `%reference.atts;`_ parameter entities).
3013
3014
3015 ``refuri``
3016 ==========
3017
3018 `Attribute type`_: ``CDATA``.  Default value: none.
3019
3020 The ``refuri`` attribute contains an external reference to a URI/URL.
3021 It is used by the target_, reference_, footnote_reference_, and
3022 citation_reference_ elements (via the `%reference.atts;`_ parameter
3023 entity).
3024
3025
3026 ``source``
3027 ==========
3028
3029 `Attribute type`_: ``CDATA``.  Default value: none.
3030
3031 The ``source`` attribute is used to store the path or URL to the
3032 source text that was used to produce the document tree.  It is one of
3033 the `common attributes`_, shared by all Docutils elements.
3034
3035
3036 ``start``
3037 =========
3038
3039 `Attribute type`_: ``%number;``.  Default value: none.
3040
3041 The ``start`` attribute is used in the enumerated_list_ element.
3042
3043
3044 ``suffix``
3045 ==========
3046
3047 `Attribute type`_: ``CDATA``.  Default value: none.
3048
3049 The ``suffix`` attribute is used in the enumerated_list_ element.
3050
3051
3052 ``xml:space``
3053 =============
3054
3055 `Attribute type`_: one of "default" or "preserve".  Default value:
3056 "preserve" (fixed).
3057
3058 The ``xml:space`` attribute is a standard XML attribute for
3059 whitespace-preserving elements.  It is used by the literal_block_,
3060 line_block_, doctest_block_, comment_, and raw_ elements (via the
3061 `%fixedspace.att;`_ parameter entity).  It is a fixed attribute, meant
3062 to communicate to an XML parser that the element contains significant
3063 whitespace.  The attribute value should not be set in a document
3064 instance.
3065
3066
3067 ----------------------------
3068  Parameter Entity Reference
3069 ----------------------------
3070
3071 .. contents:: :local:
3072               :depth: 1
3073
3074 Parameter entities are used to simplify the DTD (to share definitions
3075 and reduce duplication) and to allow the DTD to be customized by
3076 wrapper DTDs (external client DTDs that use or import the Docutils
3077 DTD).  Parameter entities may be overridden by wrapper DTDs, replacing
3078 the definitions below with custom definitions.  Parameter entities
3079 whose names begin with "additional" are meant to allow easy extension
3080 by wrapper DTDs.
3081
3082
3083 ``%anonymous.att;``
3084 ===================
3085
3086 The ``%anonymous.att;`` parameter entity contains the anonymous_
3087 attribute, used for unnamed hyperlinks.
3088
3089 Entity definition:
3090
3091 .. parsed-literal::
3092
3093     anonymous_ %yesorno; #IMPLIED
3094
3095 The reference_ and target_ elements directly employ the
3096 ``%anonymous.att;`` parameter entity in their attribute lists.
3097
3098
3099 ``%auto.att;``
3100 ==============
3101
3102 The ``%auto.att;`` parameter entity contains the auto_ attribute, used
3103 to indicate an automatically-numbered footnote or title.
3104
3105 Entity definition:
3106
3107 .. parsed-literal::
3108
3109     auto_     CDATA     #IMPLIED
3110
3111 The footnote_, footnote_reference_, and title_ elements directly
3112 employ the ``%auto.att;`` parameter entity in their attribute lists.
3113
3114
3115 ``%backrefs.att;``
3116 ==================
3117
3118 The ``%backrefs.att;`` parameter entity contains the backrefs_
3119 attribute, a space-separated list of id references, for backlinks.
3120
3121 Entity definition:
3122
3123 .. parsed-literal::
3124
3125     backrefs_  IDREFS    #IMPLIED
3126
3127 The citation_, footnote_, and system_message_ elements directly employ
3128 the ``%backrefs.att;`` parameter entity in their attribute lists.
3129
3130
3131 ``%basic.atts;``
3132 ================
3133
3134 The ``%basic.atts;`` parameter entity lists attributes common to all
3135 Docutils elements.  See `Common Attributes`_.
3136
3137 Entity definition:
3138
3139 .. parsed-literal::
3140
3141     id_       ID        #IMPLIED
3142     name_     NMTOKENS  #IMPLIED
3143     dupname_  NMTOKENS  #IMPLIED
3144     source_   CDATA     #IMPLIED
3145     class_    NMTOKENS  #IMPLIED
3146     %additional.basic.atts;
3147
3148 The ``%additional.basic.atts;`` parameter entity can be used by
3149 wrapper DTDs to extend ``%basic.atts;``.
3150
3151
3152 ``%bibliographic.elements;``
3153 ============================
3154
3155 The ``%bibliographic.elements;`` parameter entity contains an OR-list of all
3156 `bibliographic elements`_.
3157
3158 Entity definition:
3159
3160 .. parsed-literal::
3161
3162     author_ | authors_ | organization_ | contact_ | address_
3163     | version_ | revision_ | status_ | date_ | copyright_
3164     | field_
3165     %additional.bibliographic.elements;
3166
3167 The ``%additional.bibliographic.elements;`` parameter entity can be used by
3168 wrapper DTDs to extend ``%bibliographic.elements;``.
3169
3170 Only the docinfo_ element directly employs the
3171 ``%bibliographic.elements;`` parameter entity in its content model.
3172
3173
3174 ``%body.elements;``
3175 ===================
3176
3177 The ``%body.elements;`` parameter entity contains an OR-list of all
3178 `body elements`_.  ``%body.elements;`` is itself contained within the
3179 `%structure.model;`_ parameter entity.
3180
3181 Entity definition:
3182
3183 .. parsed-literal::
3184
3185     paragraph_ | literal_block_ | doctest_block_ | line_block_
3186     | block_quote_ | table_ | figure_ | image_ | footnote_ | citation_
3187     | bullet_list_ | enumerated_list_ | definition_list_ | field_list_
3188     | option_list_
3189     | attention_ | caution_ | danger_ | error_ | hint_ | important_
3190     | note_ | tip_ | warning_
3191     | target_ | substitution_definition_ | comment_ | pending_
3192     | system_message_ | raw_
3193     %additional.body.elements;
3194
3195 The ``%additional.body.elements;`` parameter entity can be used by
3196 wrapper DTDs to extend ``%body.elements;``.
3197
3198 The ``%body.elements;`` parameter entity is directly employed in the
3199 content models of the following elements: attention_, block_quote_,
3200 caution_, citation_, danger_, definition_, description_, entry_,
3201 error_, field_body_, footer_, footnote_, header_, hint_, important_,
3202 legend_, list_item_, note_, system_message_, tip_, topic_, warning_
3203
3204 Via `%structure.model;`_, the ``%body.elements;`` parameter entity is
3205 indirectly employed in the content models of the document_ and
3206 section_ elements.
3207
3208
3209 ``%fixedspace.att;``
3210 ====================
3211
3212 The ``%fixedspace.att;`` parameter entity contains the `xml:space`_
3213 attribute, a standard XML attribute for whitespace-preserving
3214 elements.
3215
3216 Entity definition:
3217
3218 .. parsed-literal::
3219
3220     `xml:space`_ (default | preserve) #FIXED 'preserve'
3221
3222 The ``%fixedspace.att;`` parameter entity is directly employed in the
3223 attribute lists of the following elements: address_, comment_,
3224 doctest_block_, line_block_, literal_block_, raw_
3225
3226
3227 ``%inline.elements;``
3228 =====================
3229
3230 The ``%inline.elements;`` parameter entity contains an OR-list of all
3231 `inline elements`_.
3232
3233 Entity definition:
3234
3235 .. parsed-literal::
3236
3237     emphasis_ | strong_ | interpreted_ | literal_
3238     | reference_ | footnote_reference_ | citation_reference_
3239     | substitution_reference_ | problematic_ | generated_
3240     | target_ | image_ | raw_
3241     %additional.inline.elements;
3242
3243 The ``%additional.inline.elements;`` parameter entity can be used by
3244 wrapper DTDs to extend ``%inline.elements;``.
3245
3246 Via `%text.model;`_, the ``%inline.elements;`` parameter entity is
3247 indirectly employed in the content models of the following elements:
3248 address_, author_, caption_, classifier_, contact_, copyright_, date_,
3249 doctest_block_, emphasis_, generated_, interpreted_, line_block_,
3250 literal_block_, organization_, paragraph_, problematic_, raw_,
3251 reference_, revision_, status_, strong_, substitution_definition_,
3252 substitution_reference_, subtitle_, target_, term_, title_, version_
3253
3254
3255 ``%reference.atts;``
3256 ====================
3257
3258 The ``%reference.atts;`` parameter entity groups together the refuri_,
3259 refid_, and refname_ attributes.
3260
3261 Entity definition:
3262
3263 .. parsed-literal::
3264
3265     `%refuri.att;`_
3266     `%refid.att;`_
3267     `%refname.att;`_
3268     %additional.reference.atts;
3269
3270 The ``%additional.reference.atts;`` parameter entity can be used by
3271 wrapper DTDs to extend ``%additional.reference.atts;``.
3272
3273 The citation_reference_, footnote_reference_, reference_, and target_
3274 elements directly employ the ``%reference.att;`` parameter entity in
3275 their attribute lists.
3276
3277
3278 ``%refid.att;``
3279 ================
3280
3281 The ``%refid.att;`` parameter entity contains the refid_ attribute, an
3282 internal reference to the `id`_ attribute of another element.
3283
3284 Entity definition:
3285
3286 .. parsed-literal::
3287
3288     refid_   CDATA     #IMPLIED
3289
3290 The title_ and problematic_ elements directly employ the
3291 ``%refid.att;`` parameter entity in their attribute lists.
3292
3293 Via `%reference.atts;`_, the ``%refid.att;`` parameter entity is
3294 indirectly employed in the attribute lists of the citation_reference_,
3295 footnote_reference_, reference_, and target_ elements.
3296
3297
3298 ``%refname.att;``
3299 =================
3300
3301 The ``%refname.att;`` parameter entity contains the refname_
3302 attribute, an internal reference to the `name`_ attribute of another
3303 element.  On a `target`_ element, ``refname`` indicates an indirect
3304 target which may resolve to either an internal or external
3305 reference.
3306
3307 Entity definition:
3308
3309 .. parsed-literal::
3310
3311     refname_  NMTOKENS  #IMPLIED
3312
3313 The substitution_reference_ element directly employs the
3314 ``%refname.att;`` parameter entity in its attribute list.
3315
3316 Via `%reference.atts;`_, the ``%refname.att;`` parameter entity is
3317 indirectly employed in the attribute lists of the citation_reference_,
3318 footnote_reference_, reference_, and target_ elements.
3319
3320
3321 ``%refuri.att;``
3322 ================
3323
3324 The ``%refuri.att;`` parameter entity contains the refuri_ attribute,
3325 an external reference to a URI/URL.
3326
3327 Entity definition:
3328
3329 .. parsed-literal::
3330
3331     refuri_   CDATA     #IMPLIED
3332
3333 Via `%reference.atts;`_, the ``%refuri.att;`` parameter entity is
3334 indirectly employed in the attribute lists of the citation_reference_,
3335 footnote_reference_, reference_, and target_ elements.
3336
3337
3338 ``%section.elements;``
3339 ======================
3340
3341 The ``%section.elements;`` parameter entity contains an OR-list of all
3342 section_-equivalent elements.  ``%section.elements;`` is itself
3343 contained within the `%structure.model;`_ parameter entity.
3344
3345 Entity definition:
3346
3347 .. parsed-literal::
3348
3349     section_
3350     %additional.section.elements;
3351
3352 The ``%additional.section.elements;`` parameter entity can be used
3353 by wrapper DTDs to extend ``%section.elements;``.
3354
3355 Via `%structure.model;`_, the ``%section.elements;`` parameter entity
3356 is indirectly employed in the content models of the document_ and
3357 section_ elements.
3358
3359
3360 ``%structure.model;``
3361 =====================
3362
3363 The ``%structure.model;`` parameter entity encapsulates the
3364 hierarchical structure of a document and of its constituent parts.
3365 See the discussion of the `element hierarchy`_ above.
3366
3367 Entity definition:
3368
3369 .. parsed-literal::
3370
3371     ( ( (`%body.elements;`_ | topic_)+,
3372         (transition_, (`%body.elements;`_ | topic_)+ )*,
3373         (`%section.elements;`_)* )
3374     | (`%section.elements;`_)+ )
3375
3376 Each document_ or section_ contains either:
3377
3378 - multiple body elements and/or topics, optionally interspersed with
3379   transitions (but transitions cannot occur at the beginning or end,
3380   nor may there be two transitions in a row), followed by zero or more
3381   sections; or
3382
3383 - one or more sections (whose contents are recursively the same as this
3384   model).
3385
3386 The `%structure.model;`_ parameter entity is directly employed in the
3387 content models of the document_ and section_ elements.
3388
3389
3390 ``%text.model;``
3391 ================
3392
3393 The ``%text.model;`` parameter entity is used by many elements to
3394 represent text data mixed with `inline elements`_.
3395
3396 Entity definition:
3397
3398 .. parsed-literal::
3399
3400     (#PCDATA | `%inline.elements;`_)*
3401
3402 The ``%text.model;`` parameter entity is directly employed in the
3403 content models of the following elements: address_, author_, caption_,
3404 classifier_, contact_, copyright_, date_, doctest_block_, emphasis_,
3405 generated_, interpreted_, line_block_, literal_block_, organization_,
3406 paragraph_, problematic_, raw_, reference_, revision_, status_,
3407 strong_, substitution_definition_, substitution_reference_, subtitle_,
3408 target_, term_, title_, version_
3409
3410
3411 \f
3412 ..
3413    Local Variables:
3414    mode: indented-text
3415    indent-tabs-mode: nil
3416    sentence-end-double-space: t
3417    fill-column: 70
3418    End: