"SfR Fresh" - the SfR Freeware/Shareware Archive 
Member "docutils-0.5/docs/ref/doctree.txt" of archive docutils-0.5.tar.gz:
As a special service "SfR Fresh" has tried to format the requested source page into HTML format using source code syntax highlighting with prefixed line numbers.
Alternatively you can here view or download the uninterpreted source code file.
That can be also achieved for any archive member file by clicking within an archive contents listing on the first character of the file(path) respectively on the according byte size field.
1 ============================
2 The Docutils Document Tree
3 ============================
4
5 A Guide to the Docutils DTD
6 ***************************
7
8 :Author: David Goodger
9 :Contact: goodger@python.org
10 :Revision: $Revision: 5492 $
11 :Date: $Date: 2008-01-01 20:41:50 +0100 (Die, 01 Jän 2008) $
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: ../user/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, decoration, docinfo] |
66 | +--------------------------------------+
67 | | sections [each begins with a title] |
68 +-----------------------------+-------------------------+------------+
69 | [body elements:] | (sections) |
70 | | - literal | - lists | | - hyperlink +------------+
71 | | blocks | - tables | | targets |
72 | para- | - doctest | - block | foot- | - sub. defs |
73 | graphs | blocks | quotes | notes | - comments |
74 +---------+-----------+----------+-------+--------------+
75 | [text]+ | [text] | (body elements) | [text] |
76 | (inline +-----------+------------------+--------------+
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_, sidebar_
106
107
108 Structural Subelements
109 ----------------------
110
111 Structural subelements are child elements of structural elements.
112 Simple structuctural subelements (title_, subtitle_) contain text
113 data; the others are compound and do not directly contain text data.
114
115 Category members: title_, subtitle_, decoration_, docinfo_,
116 transition_
117
118
119 Bibliographic Elements
120 ``````````````````````
121
122 The docinfo_ element is an optional child of document_. It groups
123 bibliographic elements together. All bibliographic elements except
124 authors_ and field_ contain text data. authors_ contains further
125 bibliographic elements (most notably author_). field_ contains
126 field_name_ and field_body_ body subelements.
127
128 Category members: address_, author_, authors_, contact_, copyright_,
129 date_, field_, organization_, revision_, status_, version_
130
131
132 Decorative Elements
133 ```````````````````
134
135 The decoration_ element is also an optional child of document_. It
136 groups together elements used to generate page headers and footers.
137
138 Category members: footer_, header_
139
140
141 Body Elements
142 =============
143
144 Body elements are contained within structural elements and compound
145 body elements. There are two subcategories of body elements: simple
146 and compound.
147
148 Category members: admonition_, attention_, block_quote_, bullet_list_,
149 caution_, citation_, comment_, compound_, container_, danger_,
150 definition_list_, doctest_block_, enumerated_list_, error_,
151 field_list_, figure_, footnote_, hint_, image_, important_,
152 line_block_, literal_block_, note_, option_list_, paragraph_,
153 pending_, raw_, rubric_, substitution_definition_, system_message_,
154 table_, target_, tip_, warning_
155
156
157 Simple Body Elements
158 --------------------
159
160 Simple body elements are empty or directly contain text data. Those
161 that contain text data may also contain inline elements. Such
162 elements therefore have a "mixed content model".
163
164 Category members: comment_, doctest_block_, image_, literal_block_,
165 paragraph_, pending_, raw_, rubric_, substitution_definition_, target_
166
167
168 Compound Body Elements
169 ----------------------
170
171 Compound body elements contain local substructure (body subelements)
172 and further body elements. They do not directly contain text data.
173
174 Category members: admonition_, attention_, block_quote_, bullet_list_,
175 caution_, citation_, compound_, container_, danger_, definition_list_,
176 enumerated_list_, error_, field_list_, figure_, footnote_, hint_,
177 important_, line_block, note_, option_list_, system_message_, table_,
178 tip_, warning_
179
180
181 Body Subelements
182 ````````````````
183
184 Compound body elements contain specific subelements (e.g. bullet_list_
185 contains list_item_). Subelements may themselves be compound elements
186 (containing further child elements, like field_) or simple data
187 elements (containing text data, like field_name_). These subelements
188 always occur within specific parent elements, never at the body
189 element level (beside paragraphs, etc.).
190
191 Category members (simple): attribution_, caption_, classifier_,
192 colspec_, field_name_, label_, line_, option_argument_,
193 option_string_, term_
194
195 Category members (compound): definition_, definition_list_item_,
196 description_, entry_, field_, field_body_, legend_, list_item_,
197 option_, option_group_, option_list_item_, row_, tbody_, tgroup_,
198 thead_
199
200
201 Inline Elements
202 ===============
203
204 Inline elements directly contain text data, and may also contain
205 further inline elements. Inline elements are contained within simple
206 body elements. Most inline elements have a "mixed content model".
207
208 Category members: abbreviation_, acronym_, citation_reference_,
209 emphasis_, footnote_reference_, generated_, image_, inline_, literal_,
210 problematic_, reference_, strong_, subscript_,
211 substitution_reference_, superscript_, target_, title_reference_, raw_
212
213
214 .. _HTML: http://www.w3.org/MarkUp/
215 .. _DocBook: http://docbook.org/tdg/en/html/docbook.html
216 .. _XMLSpec: http://www.w3.org/XML/1998/06/xmlspec-report.htm
217
218
219 -------------------
220 Element Reference
221 -------------------
222
223 .. contents:: :local:
224 :depth: 1
225
226 Each element in the DTD (document type definition) is described in its
227 own section below. Each section contains an introduction plus the
228 following subsections:
229
230 * Details (of element relationships and semantics):
231
232 - Category: One or more references to the element categories in
233 `Element Hierarchy`_ above. Some elements belong to more than one
234 category.
235
236 - Parents: A list of elements which may contain the element.
237
238 - Children: A list of elements which may occur within the element.
239
240 - Analogues: Describes analogous elements in well-known document
241 models such as HTML_ or DocBook_. Lists similarities and
242 differences.
243
244 - Processing: Lists formatting or rendering recommendations for the
245 element.
246
247 * Content Model:
248
249 The formal XML content model from the `Docutils DTD`_, followed by:
250
251 - Attributes: Describes (or refers to descriptions of) the possible
252 values and semantics of each attribute.
253
254 - Parameter Entities: Lists the parameter entities which directly or
255 indirectly include the element.
256
257 * Examples: reStructuredText_ examples are shown along with
258 fragments of the document trees resulting from parsing.
259 _`Pseudo-XML` is used for the results of parsing and processing.
260 Pseudo-XML is a representation of XML where nesting is indicated by
261 indentation and end-tags are not shown. Some of the precision of
262 real XML is given up in exchange for easier readability. For
263 example, the following are equivalent:
264
265 - Real XML::
266
267 <document>
268 <section ids="a-title" names="a title">
269 <title>A Title</title>
270 <paragraph>A paragraph.</paragraph>
271 </section>
272 </document>
273
274 - Pseudo-XML::
275
276 <document>
277 <section ids="a-title" names="a title">
278 <title>
279 A Title
280 <paragraph>
281 A paragraph.
282
283 --------------------
284
285 Many of the element reference sections below are marked "_`to be
286 completed`". Please help complete this document by contributing to
287 its writing.
288
289
290 ``abbreviation``
291 ================
292
293 `To be completed`_.
294
295
296 ``acronym``
297 ===========
298
299 `To be completed`_.
300
301
302 ``address``
303 ===========
304
305 The ``address`` element holds the surface mailing address information
306 for the author (individual or group) of the document, or a third-party
307 contact address. Its structure is identical to that of the
308 literal_block_ element: whitespace is significant, especially
309 newlines.
310
311
312 Details
313 -------
314
315 :Category:
316 `Bibliographic Elements`_
317
318 :Parents:
319 The following elements may contain ``address``: docinfo_, authors_
320
321 :Children:
322 ``address`` elements contain text data plus `inline elements`_.
323
324 :Analogues:
325 ``address`` is analogous to the DocBook "address" element.
326
327 :Processing:
328 As with the literal_block_ element, newlines and other whitespace
329 is significant and must be preserved. However, a monospaced
330 typeface need not be used.
331
332 See also docinfo_.
333
334
335 Content Model
336 -------------
337
338 .. parsed-literal::
339
340 `%text.model;`_
341
342 :Attributes:
343 The ``address`` element contains the `common attributes`_ (ids_,
344 names_, dupnames_, source_, and classes_), plus `xml:space`_.
345
346 :Parameter Entities:
347 The `%bibliographic.elements;`_ parameter entity directly includes
348 ``address``.
349
350
351 Examples
352 --------
353
354 reStructuredText_ source::
355
356 Document Title
357 ==============
358
359 :Address: 123 Example Ave.
360 Example, EX
361
362 Complete pseudo-XML_ result after parsing and applying transforms::
363
364 <document ids="document-title" names="document title">
365 <title>
366 Document Title
367 <docinfo>
368 <address>
369 123 Example Ave.
370 Example, EX
371
372 See docinfo_ for a more complete example, including processing
373 context.
374
375
376 ``admonition``
377 ==============
378
379 This element is a generic, titled admonition. Also see the specific
380 admonition elements Docutils offers (in alphabetical order): caution_,
381 danger_, error_, hint_, important_, note_, tip_, warning_.
382
383
384 Details
385 -------
386
387 :Category:
388 `Compound Body Elements`_
389
390 :Parents:
391 All elements employing the `%body.elements;`_ or
392 `%structure.model;`_ parameter entities in their content models
393 may contain ``admonition``.
394
395 :Children:
396 ``admonition`` elements begin with a title_ and may contain one or
397 more `body elements`_.
398
399 :Analogues:
400 ``admonition`` has no direct analogues in common DTDs. It can be
401 emulated with primitives and type effects.
402
403 :Processing:
404 Rendered distinctly (inset and/or in a box, etc.).
405
406
407 Content Model
408 -------------
409
410 .. parsed-literal::
411
412 (title_, (`%body.elements;`_)+)
413
414 :Attributes:
415 The ``admonition`` element contains only the `common attributes`_:
416 ids_, names_, dupnames_, source_, and classes_.
417
418 :Parameter Entities:
419 The `%body.elements;`_ parameter entity directly includes
420 ``admonition``. The `%structure.model;`_ parameter entity
421 indirectly includes ``admonition``.
422
423
424 Examples
425 --------
426
427 reStructuredText source::
428
429 .. admonition:: And, by the way...
430
431 You can make up your own admonition too.
432
433 Pseudo-XML_ fragment from simple parsing::
434
435 <admonition class="admonition-and-by-the-way">
436 <title>
437 And, by the way...
438 <paragraph>
439 You can make up your own admonition too.
440
441
442 ``attention``
443 =============
444
445 The ``attention`` element is an admonition, a distinctive and
446 self-contained notice. Also see the other admonition elements
447 Docutils offers (in alphabetical order): caution_, danger_, error_,
448 hint_, important_, note_, tip_, warning_, and the generic admonition_.
449
450
451 Details
452 -------
453
454 :Category:
455 `Compound Body Elements`_
456
457 :Parents:
458 All elements employing the `%body.elements;`_ or
459 `%structure.model;`_ parameter entities in their content models
460 may contain ``attention``.
461
462 :Children:
463 ``attention`` elements contain one or more `body elements`_.
464
465 :Analogues:
466 ``attention`` has no direct analogues in common DTDs. It can be
467 emulated with primitives and type effects.
468
469 :Processing:
470 Rendered distinctly (inset and/or in a box, etc.), with the
471 generated title "Attention!" (or similar).
472
473
474 Content Model
475 -------------
476
477 .. parsed-literal::
478
479 (`%body.elements;`_)+
480
481 :Attributes:
482 The ``attention`` element contains only the `common attributes`_:
483 ids_, names_, dupnames_, source_, and classes_.
484
485 :Parameter Entities:
486 The `%body.elements;`_ parameter entity directly includes
487 ``attention``. The `%structure.model;`_ parameter entity
488 indirectly includes ``attention``.
489
490
491 Examples
492 --------
493
494 reStructuredText source::
495
496 .. Attention:: All your base are belong to us.
497
498 Pseudo-XML_ fragment from simple parsing::
499
500 <attention>
501 <paragraph>
502 All your base are belong to us.
503
504
505 ``attribution``
506 ===============
507
508 `To be completed`_.
509
510
511 ``author``
512 ==========
513
514 The ``author`` element holds the name of the author of the document.
515
516
517 Details
518 -------
519
520 :Category:
521 `Bibliographic Elements`_
522
523 :Parents:
524 The following elements may contain ``author``: docinfo_, authors_
525
526 :Children:
527 ``author`` elements may contain text data plus `inline elements`_.
528
529 :Analogues:
530 ``author`` is analogous to the DocBook "author" element.
531
532 :Processing:
533 See docinfo_.
534
535
536 Content Model
537 -------------
538
539 .. parsed-literal::
540
541 `%text.model;`_
542
543 :Attributes:
544 The ``author`` element contains only the `common attributes`_:
545 ids_, names_, dupnames_, source_, and classes_.
546
547 :Parameter Entities:
548 The `%bibliographic.elements;`_ parameter entity directly includes
549 ``author``.
550
551
552 Examples
553 --------
554
555 reStructuredText_ source::
556
557 Document Title
558 ==============
559
560 :Author: J. Random Hacker
561
562 Complete pseudo-XML_ result after parsing and applying transforms::
563
564 <document ids="document-title" names="document title">
565 <title>
566 Document Title
567 <docinfo>
568 <author>
569 J. Random Hacker
570
571 See docinfo_ for a more complete example, including processing
572 context.
573
574
575 ``authors``
576 ===========
577
578 The ``authors`` element is a container for author information for
579 documents with multiple authors.
580
581
582 Details
583 -------
584
585 :Category:
586 `Bibliographic Elements`_
587
588 :Parents:
589 Only the docinfo_ element contains ``authors``.
590
591 :Children:
592 ``authors`` elements may contain the following elements: author_,
593 organization_, address_, contact_
594
595 :Analogues:
596 ``authors`` is analogous to the DocBook "authors" element.
597
598 :Processing:
599 See docinfo_.
600
601
602 Content Model
603 -------------
604
605 .. parsed-literal::
606
607 ((author_, organization_?, address_?, contact_?)+)
608
609 :Attributes:
610 The ``authors`` element contains only the `common attributes`_:
611 ids_, names_, dupnames_, source_, and classes_.
612
613 :Parameter Entities:
614 The `%bibliographic.elements;`_ parameter entity directly includes
615 ``authors``.
616
617
618 Examples
619 --------
620
621 reStructuredText_ source::
622
623 Document Title
624 ==============
625
626 :Authors: J. Random Hacker; Jane Doe
627
628 Complete pseudo-XML_ result after parsing and applying transforms::
629
630 <document ids="document-title" names="document title">
631 <title>
632 Document Title
633 <docinfo>
634 <authors>
635 <author>
636 J. Random Hacker
637 <author>
638 Jane Doe
639
640 In reStructuredText, multiple author's names are separated with
641 semicolons (";") or commas (","); semicolons take precedence. There
642 is currently no way to represent the author's organization, address,
643 or contact in a reStructuredText "Authors" field.
644
645 See docinfo_ for a more complete example, including processing
646 context.
647
648
649 ``block_quote``
650 ===============
651
652 The ``block_quote`` element is used for quotations set off from the
653 main text (standalone).
654
655
656 Details
657 -------
658
659 :Category:
660 `Compound Body Elements`_
661
662 :Parents:
663 All elements employing the `%body.elements;`_ or
664 `%structure.model;`_ parameter entities in their content models
665 may contain ``block_quote``.
666
667 :Children:
668 ``block_quote`` elements contain `body elements`_ followed by an
669 optional attribution_ element.
670
671 :Analogues:
672 ``block_quote`` is analogous to the "blockquote" element in both
673 HTML and DocBook.
674
675 :Processing:
676 ``block_quote`` elements serve to set their contents off from the
677 main text, typically with indentation and/or other decoration.
678
679
680 Content Model
681 -------------
682
683 .. parsed-literal::
684
685 ((`%body.elements;`_)+, attribution_?)
686
687 :Attributes:
688 The ``block_quote`` element contains only the `common
689 attributes`_: ids_, names_, dupnames_, source_, and classes_.
690
691 :Parameter Entities:
692 The `%body.elements;`_ parameter entity directly includes
693 ``block_quote``. The `%structure.model;`_ parameter entity
694 indirectly includes ``block_quote``.
695
696
697 Examples
698 --------
699
700 reStructuredText source::
701
702 As a great paleontologist once said,
703
704 This theory, that is mine, is mine.
705
706 -- Anne Elk (Miss)
707
708 Pseudo-XML_ fragment from simple parsing::
709
710 <paragraph>
711 As a great paleontologist once said,
712 <block_quote>
713 <paragraph>
714 This theory, that is mine, is mine.
715 <attribution>
716 Anne Elk (Miss)
717
718
719 ``bullet_list``
720 ===============
721
722 The ``bullet_list`` element contains list_item_ elements which are
723 uniformly marked with bullets. Bullets are typically simple dingbats
724 (symbols) such as circles and squares.
725
726
727 Details
728 -------
729
730 :Category:
731 `Compound Body Elements`_
732
733 :Parents:
734 All elements employing the `%body.elements;`_ or
735 `%structure.model;`_ parameter entities in their content models
736 may contain ``bullet_list``.
737
738 :Children:
739 ``bullet_list`` elements contain one or more list_item_ elements.
740
741 :Analogues:
742 ``bullet_list`` is analogous to the HTML "ul" element and to the
743 DocBook "itemizedlist" element. HTML's "ul" is short for
744 "unordered list", which we consider to be a misnomer. "Unordered"
745 implies that the list items may be randomly rearranged without
746 affecting the meaning of the list. Bullet lists *are* often
747 ordered; the ordering is simply left implicit.
748
749 :Processing:
750 Each list item should begin a new vertical block, prefaced by a
751 bullet/dingbat.
752
753
754 Content Model
755 -------------
756
757 .. parsed-literal::
758
759 (list_item_ +)
760
761 :Attributes:
762 The ``bullet_list`` element contains the `common attributes`_
763 (ids_, names_, dupnames_, source_, and classes_), plus bullet_.
764
765 ``bullet`` is used to record the style of bullet from the input
766 data. In documents processed from reStructuredText_, it contains
767 one of "-", "+", or "*". It may be ignored in processing.
768
769 :Parameter Entities:
770 The `%body.elements;`_ parameter entity directly includes
771 ``bullet_list``. The `%structure.model;`_ parameter entity
772 indirectly includes ``bullet_list``.
773
774
775 Examples
776 --------
777
778 reStructuredText_ source::
779
780 - Item 1, paragraph 1.
781
782 Item 1, paragraph 2.
783
784 - Item 2.
785
786 Pseudo-XML_ fragment from simple parsing::
787
788 <bullet_list bullet="-">
789 <list_item>
790 <paragraph>
791 Item 1, paragraph 1.
792 <paragraph>
793 Item 1, paragraph 2.
794 <list_item>
795 <paragraph>
796 Item 2.
797
798 See list_item_ for another example.
799
800
801 ``caption``
802 ===========
803
804 `To be completed`_.
805
806
807 ``caution``
808 ===========
809
810 The ``caution`` element is an admonition, a distinctive and
811 self-contained notice. Also see the other admonition elements
812 Docutils offers (in alphabetical order): attention_, danger_, error_,
813 hint_, important_, note_, tip_, warning_, and the generic admonition_.
814
815
816 Details
817 -------
818
819 :Category:
820 `Compound Body Elements`_
821
822 :Parents:
823 All elements employing the `%body.elements;`_ or
824 `%structure.model;`_ parameter entities in their content models
825 may contain ``caution``.
826
827 :Children:
828 ``caution`` elements contain one or more `body elements`_.
829
830 :Analogues:
831 ``caution`` is analogous to the DocBook "caution" element.
832
833 :Processing:
834 Rendered distinctly (inset and/or in a box, etc.), with the
835 generated title "Caution" (or similar).
836
837
838 Content Model
839 -------------
840
841 .. parsed-literal::
842
843 (`%body.elements;`_)+
844
845 :Attributes:
846 The ``caution`` element contains only the `common attributes`_:
847 ids_, names_, dupnames_, source_, and classes_.
848
849 :Parameter Entities:
850 The `%body.elements;`_ parameter entity directly includes
851 ``caution``. The `%structure.model;`_ parameter entity
852 indirectly includes ``caution``.
853
854
855 Examples
856 --------
857
858 reStructuredText source::
859
860 .. Caution:: Don't take any wooden nickels.
861
862 Pseudo-XML_ fragment from simple parsing::
863
864 <caution>
865 <paragraph>
866 Don't take any wooden nickels.
867
868
869 ``citation``
870 ============
871
872 `To be completed`_.
873
874
875 ``citation_reference``
876 ======================
877
878 `To be completed`_.
879
880
881 ``classifier``
882 ==============
883
884 The ``classifier`` element contains the classification or type of the
885 term_ being defined in a definition_list_. For example, it can be
886 used to indicate the type of a variable.
887
888
889 Details
890 -------
891
892 :Category:
893 `Body Subelements`_ (simple)
894
895 :Parents:
896 Only the definition_list_item_ element contains ``classifier``.
897
898 :Children:
899 ``classifier`` elements may contain text data plus `inline elements`_.
900
901 :Analogues:
902 ``classifier`` has no direct analogues in common DTDs. It can be
903 emulated with primitives or type effects.
904
905 :Processing:
906 See definition_list_item_.
907
908
909 Content Model
910 -------------
911
912 .. parsed-literal::
913
914 `%text.model;`_
915
916 :Attributes:
917 The ``classifier`` element contains only the `common attributes`_:
918 ids_, names_, dupnames_, source_, and classes_.
919
920
921 Examples
922 --------
923
924 Here is a hypothetical data dictionary. reStructuredText_ source::
925
926 name : string
927 Customer name.
928 i : int
929 Temporary index variable.
930
931 Pseudo-XML_ fragment from simple parsing::
932
933 <definition_list>
934 <definition_list_item>
935 <term>
936 name
937 <classifier>
938 string
939 <definition>
940 <paragraph>
941 Customer name.
942 <definition_list_item>
943 <term>
944 i
945 <classifier>
946 int
947 <definition>
948 <paragraph>
949 Temporary index variable.
950
951
952 ``colspec``
953 ===========
954
955 `To be completed`_.
956
957
958 ``comment``
959 ===========
960
961 `To be completed`_.
962
963
964 ``compound``
965 ============
966
967 `To be completed`_.
968
969
970 ``contact``
971 ===========
972
973 The ``contact`` element holds contact information for the author
974 (individual or group) of the document, or a third-party contact. It
975 is typically used for an email or web address.
976
977
978 Details
979 -------
980
981 :Category:
982 `Bibliographic Elements`_
983
984 :Parents:
985 The following elements may contain ``contact``: docinfo_, authors_
986
987 :Children:
988 ``contact`` elements may contain text data plus `inline
989 elements`_.
990
991 :Analogues:
992 ``contact`` is analogous to the DocBook "email" element. The HTML
993 "address" element serves a similar purpose.
994
995 :Processing:
996 See docinfo_.
997
998
999 Content Model
1000 -------------
1001
1002 .. parsed-literal::
1003
1004 `%text.model;`_
1005
1006 :Attributes:
1007 The ``contact`` element contains only the `common attributes`_:
1008 ids_, names_, dupnames_, source_, and classes_.
1009
1010 :Parameter Entities:
1011 The `%bibliographic.elements;`_ parameter entity directly includes
1012 ``contact``.
1013
1014
1015 Examples
1016 --------
1017
1018 reStructuredText_ source::
1019
1020 Document Title
1021 ==============
1022
1023 :Contact: jrh@example.com
1024
1025 Complete pseudo-XML_ result after parsing and applying transforms::
1026
1027 <document ids="document-title" names="document title">
1028 <title>
1029 Document Title
1030 <docinfo>
1031 <contact>
1032 <reference refuri="mailto:jrh@example.com">
1033 jrh@example.com
1034
1035 See docinfo_ for a more complete example, including processing
1036 context.
1037
1038
1039 ``container``
1040 =============
1041
1042 `To be completed`_.
1043
1044
1045 ``copyright``
1046 =============
1047
1048 The ``copyright`` element contains the document's copyright statement.
1049
1050
1051 Details
1052 -------
1053
1054 :Category:
1055 `Bibliographic Elements`_
1056
1057 :Parents:
1058 Only the docinfo_ element contains ``copyright``.
1059
1060 :Children:
1061 ``copyright`` elements may contain text data plus `inline
1062 elements`_.
1063
1064 :Analogues:
1065 ``copyright`` is analogous to the DocBook "copyright" element.
1066
1067 :Processing:
1068 See docinfo_.
1069
1070
1071 Content Model
1072 -------------
1073
1074 .. parsed-literal::
1075
1076 `%text.model;`_
1077
1078 :Attributes:
1079 The ``copyright`` element contains only the `common attributes`_:
1080 ids_, names_, dupnames_, source_, and classes_.
1081
1082 :Parameter Entities:
1083 The `%bibliographic.elements;`_ parameter entity directly includes
1084 ``copyright``.
1085
1086
1087 Examples
1088 --------
1089
1090 reStructuredText_ source::
1091
1092 Document Title
1093 ==============
1094
1095 :Copyright: This document has been placed in the public domain.
1096
1097 Complete pseudo-XML_ result after parsing and applying transforms::
1098
1099 <document ids="document-title" names="document title">
1100 <title>
1101 Document Title
1102 <docinfo>
1103 <copyright>
1104 This document has been placed in the public domain.
1105
1106 See docinfo_ for a more complete example, including processing
1107 context.
1108
1109
1110 ``danger``
1111 ==========
1112
1113 The ``danger`` element is an admonition, a distinctive and
1114 self-contained notice. Also see the other admonition elements
1115 Docutils offers (in alphabetical order): attention_, caution_, error_,
1116 hint_, important_, note_, tip_, warning_, and the generic admonition_.
1117
1118
1119 Details
1120 -------
1121
1122 :Category:
1123 `Compound Body Elements`_
1124
1125 :Parents:
1126 All elements employing the `%body.elements;`_ or
1127 `%structure.model;`_ parameter entities in their content models
1128 may contain ``danger``.
1129
1130 :Children:
1131 ``danger`` elements contain one or more `body elements`_.
1132
1133 :Analogues:
1134 ``danger`` has no direct analogues in common DTDs. It can be
1135 emulated with primitives and type effects.
1136
1137 :Processing:
1138 Rendered distinctly (inset and/or in a box, etc.), with the
1139 generated title "!DANGER!" (or similar).
1140
1141
1142 Content Model
1143 -------------
1144
1145 .. parsed-literal::
1146
1147 (`%body.elements;`_)+
1148
1149 :Attributes:
1150 The ``danger`` element contains only the `common attributes`_:
1151 ids_, names_, dupnames_, source_, and classes_.
1152
1153 :Parameter Entities:
1154 The `%body.elements;`_ parameter entity directly includes
1155 ``danger``. The `%structure.model;`_ parameter entity
1156 indirectly includes ``danger``.
1157
1158
1159 Examples
1160 --------
1161
1162 reStructuredText source::
1163
1164 .. DANGER:: Mad scientist at work!
1165
1166 Pseudo-XML_ fragment from simple parsing::
1167
1168 <danger>
1169 <paragraph>
1170 Mad scientist at work!
1171
1172
1173 ``date``
1174 ========
1175
1176 The ``date`` element contains the date of publication, release, or
1177 last modification of the document.
1178
1179
1180 Details
1181 -------
1182
1183 :Category:
1184 `Bibliographic Elements`_
1185
1186 :Parents:
1187 Only the docinfo_ element contains ``date``.
1188
1189 :Children:
1190 ``date`` elements may contain text data plus `inline elements`_.
1191
1192 :Analogues:
1193 ``date`` is analogous to the DocBook "date" element.
1194
1195 :Processing:
1196 Often used with the RCS/CVS keyword "Date". See docinfo_.
1197
1198
1199 Content Model
1200 -------------
1201
1202 .. parsed-literal::
1203
1204 `%text.model;`_
1205
1206 :Attributes:
1207 The ``date`` element contains only the `common attributes`_:
1208 ids_, names_, dupnames_, source_, and classes_.
1209
1210 :Parameter Entities:
1211 The `%bibliographic.elements;`_ parameter entity directly includes
1212 ``date``.
1213
1214
1215 Examples
1216 --------
1217
1218 reStructuredText_ source::
1219
1220 Document Title
1221 ==============
1222
1223 :Date: 2002-08-20
1224
1225 Complete pseudo-XML_ result after parsing and applying transforms::
1226
1227 <document ids="document-title" names="document title">
1228 <title>
1229 Document Title
1230 <docinfo>
1231 <date>
1232 2002-08-20
1233
1234 See docinfo_ for a more complete example, including processing
1235 context.
1236
1237
1238 ``decoration``
1239 ==============
1240
1241 The ``decoration`` element is a container for header_ and footer_
1242 elements and potential future extensions. These elements are used for
1243 notes, time/datestamp, processing information, etc.
1244
1245
1246 Details
1247 -------
1248
1249 :Category:
1250 `Structural Subelements`_
1251
1252 :Parents:
1253 Only the document_ element contains ``decoration``.
1254
1255 :Children:
1256 ``decoration`` elements may contain `decorative elements`_.
1257
1258 :Analogues:
1259 There are no direct analogies to ``decoration`` in HTML or in
1260 DocBook. Equivalents are typically constructed from primitives
1261 and/or generated by the processing system.
1262
1263 :Processing:
1264 See the individual `decorative elements`_.
1265
1266
1267 Content Model
1268 -------------
1269
1270 .. parsed-literal::
1271
1272 (header_?, footer_?)
1273
1274 Although the content model doesn't specifically require contents, no
1275 empty ``decoration`` elements are ever created.
1276
1277 :Attributes:
1278 The ``decoration`` element contains only the `common attributes`_:
1279 ids_, names_, dupnames_, source_, and classes_.
1280
1281
1282 Examples
1283 --------
1284
1285 reStructuredText_ source::
1286
1287 A paragraph.
1288
1289 Complete pseudo-XML_ result after parsing and applying transforms,
1290 assuming that the datestamp command-line option or configuration
1291 setting has been supplied::
1292
1293 <document>
1294 <decoration>
1295 <footer>
1296 <paragraph>
1297 Generated on: 2002-08-20.
1298 <paragraph>
1299 A paragraph.
1300
1301
1302 ``definition``
1303 ==============
1304
1305 The ``definition`` element is a container for the body elements used
1306 to define a term_ in a definition_list_.
1307
1308
1309 Details
1310 -------
1311
1312 :Category:
1313 `Body Subelements`_ (compound)
1314
1315 :Parents:
1316 Only definition_list_item_ elements contain ``definition``.
1317
1318 :Children:
1319 ``definition`` elements may contain `body elements`_.
1320
1321 :Analogues:
1322 ``definition`` is analogous to the HTML "dd" element and to the
1323 DocBook "listitem" element (inside a "variablelistentry" element).
1324
1325 :Processing:
1326 See definition_list_item_.
1327
1328
1329 Content Model
1330 -------------
1331
1332 .. parsed-literal::
1333
1334 (`%body.elements;`_)+
1335
1336 :Attributes:
1337 The ``definition`` element contains only the `common attributes`_:
1338 ids_, names_, dupnames_, source_, and classes_.
1339
1340
1341 Examples
1342 --------
1343
1344 See the examples for the definition_list_, definition_list_item_, and
1345 classifier_ elements.
1346
1347
1348 ``definition_list``
1349 ===================
1350
1351 The ``definition_list`` element contains a list of terms and their
1352 definitions. It can be used for glossaries or dictionaries, to
1353 describe or classify things, for dialogues, or to itemize subtopics
1354 (such as in this reference).
1355
1356
1357 Details
1358 -------
1359
1360 :Category:
1361 `Compound Body Elements`_
1362
1363 :Parents:
1364 All elements employing the `%body.elements;`_ or
1365 `%structure.model;`_ parameter entities in their content models
1366 may contain ``definition_list``.
1367
1368 :Children:
1369 ``definition_list`` elements contain one or more
1370 definition_list_item_ elements.
1371
1372 :Analogues:
1373 ``definition_list`` is analogous to the HTML "dl" element and to
1374 the DocBook "variablelist" element.
1375
1376 :Processing:
1377 See definition_list_item_.
1378
1379
1380 Content Model
1381 -------------
1382
1383 .. parsed-literal::
1384
1385 (definition_list_item_ +)
1386
1387 :Attributes:
1388 The ``definition_list`` element contains only the `common
1389 attributes`_: ids_, names_, dupnames_, source_, and classes_.
1390
1391 :Parameter Entities:
1392 The `%body.elements;`_ parameter entity directly includes
1393 ``definition_list``. The `%structure.model;`_ parameter entity
1394 indirectly includes ``definition_list``.
1395
1396
1397 Examples
1398 --------
1399
1400 reStructuredText_ source::
1401
1402 Term
1403 Definition.
1404
1405 Term : classifier
1406 The ' : ' indicates a classifier in
1407 definition list item terms only.
1408
1409 Pseudo-XML_ fragment from simple parsing::
1410
1411 <definition_list>
1412 <definition_list_item>
1413 <term>
1414 Term
1415 <definition>
1416 <paragraph>
1417 Definition.
1418 <definition_list_item>
1419 <term>
1420 Term
1421 <classifier>
1422 classifier
1423 <definition>
1424 <paragraph>
1425 The ' : ' indicates a classifier in
1426 definition list item terms only.
1427
1428 See definition_list_item_ and classifier_ for further examples.
1429
1430
1431 ``definition_list_item``
1432 ========================
1433
1434 The ``definition_list_item`` element contains a single
1435 term_/definition_ pair (with optional classifier_).
1436
1437
1438 Details
1439 -------
1440
1441 :Category:
1442 `Body Subelements`_ (compound)
1443
1444 :Parents:
1445 Only the definition_list_ element contains
1446 ``definition_list_item``.
1447
1448 :Children:
1449 ``definition_list_item`` elements each contain a single term_,
1450 an optional classifier_, and a definition_.
1451
1452 :Analogues:
1453 ``definition_list_item`` is analogous to the DocBook
1454 "variablelistentry" element.
1455
1456 :Processing:
1457 The optional classifier_ can be rendered differently from the
1458 term_. They should be separated visually, typically by spaces
1459 plus a colon or dash.
1460
1461
1462 Content Model
1463 -------------
1464
1465 .. parsed-literal::
1466
1467 (term_, classifier_?, definition_)
1468
1469 :Attributes:
1470 The ``definition_list_item`` element contains only the `common
1471 attributes`_: ids_, names_, dupnames_, source_, and classes_.
1472
1473
1474 Examples
1475 --------
1476
1477 reStructuredText_ source::
1478
1479 Tyrannosaurus Rex : carnivore
1480 Big and scary; the "Tyrant King".
1481
1482 Brontosaurus : herbivore
1483 All brontosauruses are thin at one end,
1484 much much thicker in the middle
1485 and then thin again at the far end.
1486
1487 -- Anne Elk (Miss)
1488
1489 Pseudo-XML_ fragment from simple parsing::
1490
1491 <definition_list>
1492 <definition_list_item>
1493 <term>
1494 Tyrannosaurus Rex
1495 <classifier>
1496 carnivore
1497 <definition>
1498 <paragraph>
1499 Big and scary; the "Tyrant King".
1500 <definition_list_item>
1501 <term>
1502 Brontosaurus
1503 <classifier>
1504 herbivore
1505 <definition>
1506 <paragraph>
1507 All brontosauruses are thin at one end,
1508 much much thicker in the middle
1509 and then thin again at the far end.
1510 <paragraph>
1511 -- Anne Elk (Miss)
1512
1513 See definition_list_ and classifier_ for further examples.
1514
1515
1516 ``description``
1517 ===============
1518
1519 The ``description`` element contains body elements, describing the
1520 purpose or effect of a command-line option or group of options.
1521
1522
1523 Details
1524 -------
1525
1526 :Category:
1527 `Body Subelements`_
1528
1529 :Parents:
1530 Only the option_list_item_ element contains ``description``.
1531
1532 :Children:
1533 ``description`` elements may contain `body elements`_.
1534
1535 :Analogues:
1536 ``description`` has no direct analogues in common DTDs.
1537
1538 :Processing:
1539 See option_list_.
1540
1541
1542 Content Model
1543 -------------
1544
1545 .. parsed-literal::
1546
1547 (`%body.elements;`_)+
1548
1549 :Attributes:
1550 The ``description`` element contains only the `common attributes`_:
1551 ids_, names_, dupnames_, source_, and classes_.
1552
1553
1554 Examples
1555 --------
1556
1557 See the examples for the option_list_ element.
1558
1559
1560 ``docinfo``
1561 ===========
1562
1563 The ``docinfo`` element is a container for document bibliographic
1564 data, or meta-data (data about the document). It corresponds to the
1565 front matter of a book, such as the title page and copyright page.
1566
1567
1568 Details
1569 -------
1570
1571 :Category:
1572 `Structural Subelements`_
1573
1574 :Parents:
1575 Only the document_ element contains ``docinfo``.
1576
1577 :Children:
1578 ``docinfo`` elements contain `bibliographic elements`_.
1579
1580 :Analogues:
1581 ``docinfo`` is analogous to DocBook "info" elements ("bookinfo"
1582 etc.). There are no directly analogous HTML elements; the "meta"
1583 element carries some of the same information, albeit invisibly.
1584
1585 :Processing:
1586 The ``docinfo`` element may be rendered as a two-column table or
1587 in other styles. It may even be invisible or omitted from the
1588 processed output. Meta-data may be extracted from ``docinfo``
1589 children; for example, HTML ``<meta>`` tags may be constructed.
1590
1591 When Docutils_ transforms a reStructuredText_ field_list_ into a
1592 ``docinfo`` element (see the examples below), RCS/CVS keywords are
1593 normally stripped from simple (one paragraph) field bodies. For
1594 complete details, please see `RCS Keywords`_ in the
1595 `reStructuredText Markup Specification`_.
1596
1597 .. _RCS Keywords: rst/restructuredtext.html#rcs-keywords
1598
1599
1600 Content Model
1601 -------------
1602
1603 .. parsed-literal::
1604
1605 (`%bibliographic.elements;`_)+
1606
1607 :Attributes:
1608 The ``docinfo`` element contains only the `common attributes`_:
1609 ids_, names_, dupnames_, source_, and classes_.
1610
1611
1612 Examples
1613 --------
1614
1615 Docinfo is represented in reStructuredText_ by a field_list_ in a
1616 bibliographic context: the first non-comment element of a document_,
1617 after any document title_/subtitle_. The field list is transformed
1618 into a ``docinfo`` element and its children by a transform. Source::
1619
1620 Docinfo Example
1621 ===============
1622
1623 :Author: J. Random Hacker
1624 :Contact: jrh@example.com
1625 :Date: 2002-08-18
1626 :Status: Work In Progress
1627 :Version: 1
1628 :Filename: $RCSfile$
1629 :Copyright: This document has been placed in the public domain.
1630
1631 Complete pseudo-XML_ result after parsing and applying transforms::
1632
1633 <document ids="docinfo-example" names="docinfo example">
1634 <title>
1635 Docinfo Example
1636 <docinfo>
1637 <author>
1638 J. Random Hacker
1639 <contact>
1640 <reference refuri="mailto:jrh@example.com">
1641 jrh@example.com
1642 <date>
1643 2002-08-18
1644 <status>
1645 Work In Progress
1646 <version>
1647 1
1648 <field>
1649 <field_name>
1650 Filename
1651 <field_body>
1652 <paragraph>
1653 doctree.txt
1654 <copyright>
1655 This document has been placed in the public domain.
1656
1657 Note that "Filename" is a non-standard ``docinfo`` field, so becomes a
1658 generic ``field`` element. Also note that the "RCSfile" keyword
1659 syntax has been stripped from the "Filename" data.
1660
1661 See field_list_ for an example in a non-bibliographic context. Also
1662 see the individual examples for the various `bibliographic elements`_.
1663
1664
1665 ``doctest_block``
1666 =================
1667
1668 The ``doctest_block`` element is a Python-specific variant of
1669 literal_block_. It is a block of text where line breaks and
1670 whitespace are significant and must be preserved. ``doctest_block``
1671 elements are used for interactive Python interpreter sessions, which
1672 are distinguished by their input prompt: ``>>>``. They are meant to
1673 illustrate usage by example, and provide an elegant and powerful
1674 testing environment via the `doctest module`_ in the Python standard
1675 library.
1676
1677 .. _doctest module:
1678 http://www.python.org/doc/current/lib/module-doctest.html
1679
1680
1681 Details
1682 -------
1683
1684 :Category:
1685 `Simple Body Elements`_
1686
1687 :Parents:
1688 All elements employing the `%body.elements;`_ or
1689 `%structure.model;`_ parameter entities in their content models
1690 may contain ``doctest_block``.
1691
1692 :Children:
1693 ``doctest_block`` elements may contain text data plus `inline
1694 elements`_.
1695
1696 :Analogues:
1697 ``doctest_block`` is analogous to the HTML "pre" element and to
1698 the DocBook "programlisting" and "screen" elements.
1699
1700 :Processing:
1701 As with literal_block_, ``doctest_block`` elements are typically
1702 rendered in a monospaced typeface. It is crucial that all
1703 whitespace and line breaks are preserved in the rendered form.
1704
1705
1706 Content Model
1707 -------------
1708
1709 .. parsed-literal::
1710
1711 `%text.model;`_
1712
1713 :Attributes:
1714 The ``doctest_block`` element contains the `common attributes`_
1715 (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_.
1716
1717 :Parameter Entities:
1718 The `%body.elements;`_ parameter entity directly includes
1719 ``doctest_block``. The `%structure.model;`_ parameter entity
1720 indirectly includes ``doctest_block``.
1721
1722
1723 Examples
1724 --------
1725
1726 reStructuredText source::
1727
1728 This is an ordinary paragraph.
1729
1730 >>> print 'this is a Doctest block'
1731 this is a Doctest block
1732
1733 Pseudo-XML_ fragment from simple parsing::
1734
1735 <paragraph>
1736 This is an ordinary paragraph.
1737 <doctest_block xml:space="preserve">
1738 >>> print 'this is a Doctest block'
1739 this is a Doctest block
1740
1741
1742 ``document``
1743 ============
1744
1745 The ``document`` element is the root (topmost) element of the Docutils
1746 document tree. ``document`` is the direct or indirect ancestor of
1747 every other element in the tree. It encloses the entire document
1748 tree. It is the starting point for a document.
1749
1750
1751 Details
1752 -------
1753
1754 :Category:
1755 `Structural Elements`_
1756
1757 :Parents:
1758 The ``document`` element has no parents.
1759
1760 :Children:
1761 ``document`` elements may contain `structural subelements`_,
1762 `structural elements`_, and `body elements`_.
1763
1764 :Analogues:
1765 ``document`` is analogous to the HTML "html" element and to
1766 several DocBook elements such as "book".
1767
1768
1769 Content Model
1770 -------------
1771
1772 .. parsed-literal::
1773
1774 ( (title_, subtitle_?)?,
1775 decoration_?,
1776 (docinfo_, transition_?)?,
1777 `%structure.model;`_ )
1778
1779 Depending on the source of the data and the stage of processing, the
1780 "document" may not initially contain a "title". A document title is
1781 not directly representable in reStructuredText_. Instead, a lone
1782 top-level section may have its title promoted to become the document
1783 title_, and similarly for a lone second-level (sub)section's title to
1784 become the document subtitle_.
1785
1786 The contents of "decoration_" may be specified in a document,
1787 constructed programmatically, or both. The "docinfo_" may be
1788 transformed from an initial field_list_.
1789
1790 See the `%structure.model;`_ parameter entity for details of the body
1791 of a ``document``.
1792
1793 :Attributes:
1794 The ``document`` element contains the `common attributes`_ (ids_,
1795 names_, dupnames_, source_, and classes_), plus an optional title__
1796 attribute which stores the document title metadata.
1797
1798 __ `title (attribute)`_
1799
1800
1801 Examples
1802 --------
1803
1804 reStructuredText_ source::
1805
1806 A Title
1807 =======
1808
1809 A paragraph.
1810
1811 Complete pseudo-XML_ result from simple parsing::
1812
1813 <document>
1814 <section ids="a-title" names="a title">
1815 <title>
1816 A Title
1817 <paragraph>
1818 A paragraph.
1819
1820 After applying transforms, the section title is promoted to become the
1821 document title::
1822
1823 <document ids="a-title" names="a title">
1824 <title>
1825 A Title
1826 <paragraph>
1827 A paragraph.
1828
1829
1830 ``emphasis``
1831 ============
1832
1833 `To be completed`_.
1834
1835
1836 ``entry``
1837 =========
1838
1839 `To be completed`_.
1840
1841
1842 ``enumerated_list``
1843 ===================
1844
1845 The ``enumerated_list`` element contains list_item_ elements which are
1846 uniformly marked with enumerator labels.
1847
1848
1849 Details
1850 -------
1851
1852 :Category:
1853 `Compound Body Elements`_
1854
1855 :Parents:
1856 All elements employing the `%body.elements;`_ or
1857 `%structure.model;`_ parameter entities in their content models
1858 may contain ``enumerated_list``.
1859
1860 :Children:
1861 ``enumerated_list`` elements contain one or more list_item_
1862 elements.
1863
1864 :Analogues:
1865 ``enumerated_list`` is analogous to the HTML "ol" element and to
1866 the DocBook "orderedlist" element.
1867
1868 :Processing:
1869 Each list item should begin a new vertical block, prefaced by a
1870 enumeration marker (such as "1.").
1871
1872
1873 Content Model
1874 -------------
1875
1876 .. parsed-literal::
1877
1878 (list_item_ +)
1879
1880 :Attributes:
1881 The ``enumerated_list`` element contains the `common attributes`_
1882 (ids_, names_, dupnames_, source_, and classes_), plus enumtype_,
1883 prefix_, suffix_, and start_.
1884
1885 ``enumtype`` is used to record the intended enumeration sequence,
1886 one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z),
1887 "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ...,
1888 mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ...,
1889 MMMMCMXCIX [4999]).
1890
1891 ``prefix`` stores the formatting characters used before the
1892 enumerator. In documents originating from reStructuredText_ data,
1893 it will contain either "" (empty string) or "(" (left
1894 parenthesis). It may or may not affect processing.
1895
1896 ``suffix`` stores the formatting characters used after the
1897 enumerator. In documents originating from reStructuredText_ data,
1898 it will contain either "." (period) or ")" (right parenthesis).
1899 Depending on the capabilities of the output format, this attribute
1900 may or may not affect processing.
1901
1902 ``start`` contains the ordinal value of the first item in the
1903 list, in decimal. For lists beginning at value 1 ("1", "a", "A",
1904 "i", or "I"), this attribute may be omitted.
1905
1906 :Parameter Entities:
1907 The `%body.elements;`_ parameter entity directly includes
1908 ``enumerated_list``. The `%structure.model;`_ parameter entity
1909 indirectly includes ``enumerated_list``.
1910
1911
1912 Examples
1913 --------
1914
1915 reStructuredText_ source::
1916
1917 1. Item 1.
1918
1919 (A) Item A.
1920 (B) Item B.
1921 (C) Item C.
1922
1923 2. Item 2.
1924
1925 Pseudo-XML_ fragment from simple parsing::
1926
1927 <enumerated_list enumtype="arabic" prefix="" suffix=".">
1928 <list_item>
1929 <paragraph>
1930 Item 1.
1931 <enumerated_list enumtype="upperalpha" prefix="(" suffix=")">
1932 <list_item>
1933 <paragraph>
1934 Item A.
1935 <list_item>
1936 <paragraph>
1937 Item B.
1938 <list_item>
1939 <paragraph>
1940 Item C.
1941 <list_item>
1942 <paragraph>
1943 Item 2.
1944
1945 See list_item_ for another example.
1946
1947
1948 ``error``
1949 =========
1950
1951 The ``error`` element is an admonition, a distinctive and
1952 self-contained notice. Also see the other admonition elements
1953 Docutils offers (in alphabetical order): attention_, caution_,
1954 danger_, hint_, important_, note_, tip_, warning_, and the generic
1955 admonition_.
1956
1957
1958 Details
1959 -------
1960
1961 :Category:
1962 `Compound Body Elements`_
1963
1964 :Parents:
1965 All elements employing the `%body.elements;`_ or
1966 `%structure.model;`_ parameter entities in their content models
1967 may contain ``error``.
1968
1969 :Children:
1970 ``error`` elements contain one or more `body elements`_.
1971
1972 :Analogues:
1973 ``error`` has no direct analogues in common DTDs. It can be
1974 emulated with primitives and type effects.
1975
1976 :Processing:
1977 Rendered distinctly (inset and/or in a box, etc.), with the
1978 generated title "Error" (or similar).
1979
1980
1981 Content Model
1982 -------------
1983
1984 .. parsed-literal::
1985
1986 (`%body.elements;`_)+
1987
1988 :Attributes:
1989 The ``error`` element contains only the `common attributes`_: ids_,
1990 names_, dupnames_, source_, and classes_.
1991
1992 :Parameter Entities:
1993 The `%body.elements;`_ parameter entity directly includes
1994 ``error``. The `%structure.model;`_ parameter entity indirectly
1995 includes ``error``.
1996
1997
1998 Examples
1999 --------
2000
2001 reStructuredText source::
2002
2003 .. Error:: Does not compute.
2004
2005 Pseudo-XML_ fragment from simple parsing::
2006
2007 <error>
2008 <paragraph>
2009 Does not compute.
2010
2011
2012 ``field``
2013 =========
2014
2015 The ``field`` element contains a pair of field_name_ and field_body_
2016 elements.
2017
2018
2019 Details
2020 -------
2021
2022 :Category:
2023 `Body Subelements`_
2024
2025 :Parents:
2026 The following elements may contain ``field``: docinfo_,
2027 field_list_
2028
2029 :Children:
2030 Each ``field`` element contains one field_name_ and one
2031 field_body_ element.
2032
2033 :Analogues:
2034 ``field`` has no direct analogues in common DTDs.
2035
2036 :Processing:
2037 See field_list_.
2038
2039
2040 Content Model
2041 -------------
2042
2043 .. parsed-literal::
2044
2045 (field_name_, field_body_)
2046
2047 :Attributes:
2048 The ``field`` element contains only the `common attributes`_:
2049 ids_, names_, dupnames_, source_, and classes_.
2050
2051 :Parameter Entities:
2052 The `%bibliographic.elements;`_ parameter entity directly includes
2053 ``field``.
2054
2055
2056 Examples
2057 --------
2058
2059 See the examples for the field_list_ and docinfo_ elements.
2060
2061
2062 ``field_body``
2063 ==============
2064
2065 The ``field_body`` element contains body elements. It is analogous to
2066 a database field's data.
2067
2068
2069 Details
2070 -------
2071
2072 :Category:
2073 `Body Subelements`_
2074
2075 :Parents:
2076 Only the field_ element contains ``field_body``.
2077
2078 :Children:
2079 ``field_body`` elements may contain `body elements`_.
2080
2081 :Analogues:
2082 ``field_body`` has no direct analogues in common DTDs.
2083
2084 :Processing:
2085 See field_list_.
2086
2087
2088 Content Model
2089 -------------
2090
2091 .. parsed-literal::
2092
2093 (`%body.elements;`_)*
2094
2095 :Attributes:
2096 The ``field_body`` element contains only the `common attributes`_:
2097 ids_, names_, dupnames_, source_, and classes_.
2098
2099
2100 Examples
2101 --------
2102
2103 See the examples for the field_list_ and docinfo_ elements.
2104
2105
2106 ``field_list``
2107 ==============
2108
2109 The ``field_list`` element contains two-column table-like structures
2110 resembling database records (label & data pairs). Field lists are
2111 often meant for further processing. In reStructuredText_, field lists
2112 are used to represent bibliographic fields (contents of the docinfo_
2113 element) and directive options.
2114
2115
2116 Details
2117 -------
2118
2119 :Category:
2120 `Compound Body Elements`_
2121
2122 :Parents:
2123 All elements employing the `%body.elements;`_ or
2124 `%structure.model;`_ parameter entities in their content models
2125 may contain ``field_list``.
2126
2127 :Children:
2128 ``field_list`` elements contain one or more field_ elements.
2129
2130 :Analogues:
2131 ``field_list`` has no direct analogues in common DTDs. It can be
2132 emulated with primitives such as tables.
2133
2134 :Processing:
2135 A ``field_list`` is typically rendered as a two-column list, where
2136 the first column contains "labels" (usually with a colon suffix).
2137 However, field lists are often used for extension syntax or
2138 special processing. Such structures do not survive as field lists
2139 to be rendered.
2140
2141
2142 Content Model
2143 -------------
2144
2145 .. parsed-literal::
2146
2147 (field_ +)
2148
2149 :Attributes:
2150 The ``field_list`` element contains only the `common attributes`_:
2151 ids_, names_, dupnames_, source_, and classes_.
2152
2153 :Parameter Entities:
2154 The `%body.elements;`_ parameter entity directly includes
2155 ``field_list``. The `%structure.model;`_ parameter entity
2156 indirectly includes ``field_list``.
2157
2158