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