62
62
contain further body elements, etc. ::
64
64
+--------------------------------------------------------------------+
65
| document [may begin with a title, subtitle, docinfo, decoration] |
65
| document [may begin with a title, subtitle, decoration, docinfo] |
66
66
| +--------------------------------------+
67
67
| | sections [each begins with a title] |
68
68
+-----------------------------+-------------------------+------------+
112
112
Simple structuctural subelements (title_, subtitle_) contain text
113
113
data; the others are compound and do not directly contain text data.
115
Category members: title_, subtitle_, docinfo_, decoration_,
115
Category members: title_, subtitle_, decoration_, docinfo_,
148
148
Category members: admonition_, attention_, block_quote_, bullet_list_,
149
caution_, citation_, comment_, danger_, definition_list_,
149
caution_, citation_, comment_, compound_, danger_, definition_list_,
150
150
doctest_block_, enumerated_list_, error_, field_list_, figure_,
151
151
footnote_, hint_, image_, important_, line_block_, literal_block_,
152
152
note_, option_list_, paragraph_, pending_, raw_, rubric_,
161
161
that contain text data may also contain inline elements. Such
162
162
elements therefore have a "mixed content model".
164
Category members: comment_, doctest_block_, image_, line_block_,
165
literal_block_, paragraph_, pending_, raw_, rubric_,
166
substitution_definition_, target_
164
Category members: comment_, doctest_block_, image_, literal_block_,
165
paragraph_, pending_, raw_, rubric_, substitution_definition_, target_
169
168
Compound Body Elements
173
172
and further body elements. They do not directly contain text data.
175
174
Category members: admonition_, attention_, block_quote_, bullet_list_,
176
caution_, citation_, danger_, definition_list_, enumerated_list_,
177
error_, field_list_, figure_, footnote_, hint_, important_, note_,
178
option_list_, system_message_, table_, tip_, warning_
175
caution_, citation_, compound_, danger_, definition_list_,
176
enumerated_list_, error_, field_list_, figure_, footnote_, hint_,
177
important_, line_block, note_, option_list_, system_message_, table_,
189
189
element level (beside paragraphs, etc.).
191
191
Category members (simple): attribution_, caption_, classifier_,
192
colspec_, field_name_, label_, option_argument_, option_string_, term_
192
colspec_, field_name_, label_, line_, option_argument_,
193
option_string_, term_
194
195
Category members (compound): definition_, definition_list_item_,
195
196
description_, entry_, field_, field_body_, legend_, list_item_,
323
325
``address`` is analogous to the DocBook "address" element.
326
As with the line_block_ element, newlines and other whitespace is
327
significant and must be preserved. However, a monospaced typeface
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.
330
332
See also docinfo_.
1227
1235
The ``decoration`` element is a container for header_ and footer_
1228
1236
elements and potential future extensions. These elements are used for
1229
page navigation, notes, time/datestamp, etc. Currently only the
1230
footer_ element is implemented, populated with processing information
1231
(datestamp, a link to Docutils_, etc.).
1237
notes, time/datestamp, processing information, etc.
1759
1766
.. parsed-literal::
1765
`%structure.model;`_)
1768
( (title_, subtitle_?)?,
1770
(docinfo_, transition_?)?,
1771
`%structure.model;`_ )
1767
1773
Depending on the source of the data and the stage of processing, the
1768
1774
"document" may not initially contain a "title". A document title is
1769
1775
not directly representable in reStructuredText_. Instead, a lone
1770
1776
top-level section may have its title promoted to become the document
1771
1777
title_, and similarly for a lone second-level (sub)section's title to
1772
become the document subtitle_. The "docinfo_" may be transformed from
1773
an initial field_list_, and "decoration_" is usually constructed
1778
become the document subtitle_.
1780
The contents of "decoration_" may be specified in a document,
1781
constructed programmatically, or both. The "docinfo_" may be
1782
transformed from an initial field_list_.
1776
1784
See the `%structure.model;`_ parameter entity for details of the body
1777
1785
of a ``document``.
2234
2242
The ``footer`` element is a container element whose contents are meant
2235
2243
to appear at the bottom of a web page, or repeated at the bottom of
2236
every printed page. Currently the ``footer`` element may contain
2237
processing information (datestamp, a link to Docutils_, etc.).
2244
every printed page. The ``footer`` element may contain processing
2245
information (datestamp, a link to Docutils_, etc.) as well as custom
2520
2539
`To be completed`_.
2545
The ``line`` element contains a single line of text, part of a
2553
`Body Subelements`_ (simple)
2556
Only the `line_block`_ element contains ``line``.
2559
``line`` elements may contain text data plus `inline elements`_.
2562
``line`` has no direct analogues in common DTDs. It can be
2563
emulated with primitives or type effects.
2577
The ``line`` element contains the `common attributes`_ (id_,
2578
name_, dupname_, source_, and class_), plus `xml:space`_.
2526
The ``line_block`` element contains a block of text where line breaks
2527
and whitespace are significant and must be preserved. ``line_block``
2528
elements are commonly used for verse and addresses. See `line_block`_
2529
for an alternative useful for program listings and interactive
2590
The ``line_block`` element contains a sequence of lines and nested
2591
line blocks. Line breaks (implied between elements) and leading
2592
whitespace (indicated by nesting) is significant and must be
2593
preserved. ``line_block`` elements are commonly used for verse and
2594
addresses. See `literal_block`_ for an alternative useful for program
2595
listings and interactive computer sessions.
2537
`Simple Body Elements`_
2602
`Compound Body Elements`_
2540
2605
All elements employing the `%body.elements;`_ or
2582
2647
Take it away, Eric the Orchestra Leader!
2586
A one, two, a one two three four
2588
Half a bee, philosophically,
2589
must, *ipso facto*, half not be.
2590
But half the bee has got to be,
2591
*vis a vis* its entity. D'you see?
2593
But can a bee be said to be
2594
or not to be an entire bee,
2595
when half the bee is not a bee,
2596
due to some ancient injury?
2649
| A one, two, a one two three four
2651
| Half a bee, philosophically,
2652
| must, *ipso facto*, half not be.
2653
| But half the bee has got to be,
2654
| *vis a vis* its entity. D'you see?
2656
| But can a bee be said to be
2657
| or not to be an entire bee,
2658
| when half the bee is not a bee,
2659
| due to some ancient injury?
2600
2663
Pseudo-XML_ fragment from simple parsing::
2603
2666
Take it away, Eric the Orchestra Leader!
2604
<line_block xml:space="preserve">
2605
A one, two, a one two three four
2607
Half a bee, philosophically,
2608
must, <emphasis>ipso facto</emphasis>, half not be.
2609
But half the bee has got to be,
2610
<emphasis>vis a vis</emphasis>its entity. D'you see?
2612
But can a bee be said to be
2613
or not to be an entire bee,
2614
when half the bee is not a bee,
2615
due to some ancient injury?
2669
A one, two, a one two three four
2672
Half a bee, philosophically,
2680
But half the bee has got to be,
2685
its entity. D'you see?
2688
But can a bee be said to be
2691
or not to be an entire bee,
2694
when half the bee is not a bee,
2697
due to some ancient injury?
3479
3562
Complete pseudo-XML_ result after parsing::
3482
<section id="title-1" name="title 1">
3565
<section ids="title-1" names="title 1">
3487
<section id="title-2" name="title 2">
3570
<section ids="title-2" names="title 2">
3492
<section id="title-3" name="title 3">
3575
<section ids="title-3" names="title 3">
3497
<section id="title-4" name="title 4">
3580
<section ids="title-4" names="title 4">
3966
4049
may occur at the top level of a section_ wherever a body element
3967
4050
(list, table, etc.) is allowed. In other words, ``topic`` elements
3968
4051
cannot nest inside body elements, so you can't have a ``topic`` inside
3969
a ``table`` or a ``list``, or inside another ``topic`` (or sidebar_).
4052
a ``table`` or a ``list``, or inside another ``topic``.
4612
4696
.. parsed-literal::
4614
paragraph_ | literal_block_ | doctest_block_ | line_block_
4615
| block_quote_ | table_ | figure_ | image_ | footnote_ | citation_
4698
paragraph_ | compound_ | literal_block_ | doctest_block_
4699
| line_block_ | block_quote_
4700
| table_ | figure_ | image_ | footnote_ | citation_ | rubric_
4617
4701
| bullet_list_ | enumerated_list_ | definition_list_ | field_list_
4619
| attention_ | caution_ | danger_ | error_ | hint_ | important_
4620
| note_ | tip_ | warning_ | admonition_
4621
| target_ | substitution_definition_ | comment_ | pending_
4703
| attention_ | caution_ | danger_ | error_ | hint_ | important_ | note_
4704
| tip_ | warning_ | admonition_
4705
| reference_ | target_ | substitution_definition_ | comment_ | pending_
4622
4706
| system_message_ | raw_
4623
4707
%additional.body.elements;
4628
4712
The ``%body.elements;`` parameter entity is directly employed in the
4629
4713
content models of the following elements: admonition_, attention_,
4630
block_quote_, caution_, citation_, danger_, definition_, description_,
4631
entry_, error_, field_body_, footer_, footnote_, header_, hint_,
4632
important_, legend_, list_item_, note_, sidebar_, system_message_,
4633
tip_, topic_, warning_
4714
block_quote_, caution_, citation_, compound_, danger_, definition_,
4715
description_, entry_, error_, field_body_, footer_, footnote_,
4716
header_, hint_, important_, legend_, list_item_, note_, sidebar_,
4717
system_message_, tip_, topic_, warning_
4635
4719
Via `%structure.model;`_, the ``%body.elements;`` parameter entity is
4636
4720
indirectly employed in the content models of the document_ and
added
removed
docs/ref/doctree.txt
