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