1 <document ids="restructuredtext-test-document doctitle" names="restructuredtext\ test\ document doctitle" source="functional/input/standalone_rst_pseudoxml.txt" title="reStructuredText Test Document">
3 reStructuredText Test Document
4 <subtitle ids="examples-of-syntax-constructs subtitle" names="examples\ of\ syntax\ constructs subtitle">
5 Examples of Syntax Constructs
16 <address xml:space="preserve">
21 <reference refuri="mailto:goodger@python.org">
33 Now, or yesterday. Or maybe even
38 This is a "work in progress"
40 is managed by a version control system.
44 This document has been placed in the public domain. You
45 may do with it as you wish. You may copy, modify,
46 redistribute, reattribute, sell, buy, rent, lease,
47 destroy, or improve it, quote it at length, excerpt,
48 incorporate, collate, fold, staple, or mutilate it, or do
49 anything else to it that your or anyone else's heart
56 This is a "generic bibliographic field".
62 Generic bibliographic fields may contain multiple body elements.
65 <topic classes="dedication">
69 For Docutils users & co-developers.
70 <topic classes="abstract">
74 This is a test document, containing at least one example of each
75 reStructuredText construct.
76 <comment xml:space="preserve">
77 This is a comment. Note how any initial comments are moved by
78 transforms to after the document title, subtitle, and docinfo.
79 <target refid="doctitle">
80 <comment xml:space="preserve">
81 Above is the document title, and below is the subtitle.
82 They are transformed from section titles after parsing.
83 <target refid="subtitle">
84 <comment xml:space="preserve">
85 bibliographic fields (which also require a transform):
86 <meta content="reStructuredText, test, parser" name="keywords">
87 <meta content="A test document, containing at least one example of each reStructuredText construct." lang="en" name="description">
88 <raw format="latex" xml:space="preserve">
89 \pagebreak[4] % start ToC on new page
90 <topic classes="contents" ids="table-of-contents" names="table\ of\ contents">
93 <bullet_list classes="auto-toc">
96 <reference ids="id34" refid="structural-elements">
97 <generated classes="sectnum">
100 <bullet_list classes="auto-toc">
103 <reference ids="id35" refid="section-title">
104 <generated classes="sectnum">
109 <reference ids="id36" refid="empty-section">
110 <generated classes="sectnum">
115 <reference ids="id37" refid="transitions">
116 <generated classes="sectnum">
121 <reference ids="id38" refid="body-elements">
122 <generated classes="sectnum">
125 <bullet_list classes="auto-toc">
128 <reference ids="id39" refid="paragraphs">
129 <generated classes="sectnum">
132 <bullet_list classes="auto-toc">
135 <reference ids="id40" refid="inline-markup">
136 <generated classes="sectnum">
141 <reference ids="id41" refid="bullet-lists">
142 <generated classes="sectnum">
147 <reference ids="id42" refid="enumerated-lists">
148 <generated classes="sectnum">
153 <reference ids="id43" refid="definition-lists">
154 <generated classes="sectnum">
159 <reference ids="id44" refid="field-lists">
160 <generated classes="sectnum">
165 <reference ids="id45" refid="option-lists">
166 <generated classes="sectnum">
171 <reference ids="id46" refid="literal-blocks">
172 <generated classes="sectnum">
177 <reference ids="id47" refid="line-blocks">
178 <generated classes="sectnum">
183 <reference ids="id48" refid="block-quotes">
184 <generated classes="sectnum">
189 <reference ids="id49" refid="doctest-blocks">
190 <generated classes="sectnum">
195 <reference ids="id50" refid="footnotes">
196 <generated classes="sectnum">
201 <reference ids="id51" refid="citations">
202 <generated classes="sectnum">
207 <reference ids="id52" refid="targets">
208 <generated classes="sectnum">
211 <bullet_list classes="auto-toc">
214 <reference ids="id53" refid="duplicate-target-names">
215 <generated classes="sectnum">
217 Duplicate Target Names
220 <reference ids="id54" refid="id21">
221 <generated classes="sectnum">
223 Duplicate Target Names
226 <reference ids="id55" refid="directives">
227 <generated classes="sectnum">
230 <bullet_list classes="auto-toc">
233 <reference ids="id56" refid="document-parts">
234 <generated classes="sectnum">
239 <reference ids="id57" refid="images-and-figures">
240 <generated classes="sectnum">
245 <reference ids="id58" refid="admonitions">
246 <generated classes="sectnum">
251 <reference ids="id59" refid="topics-sidebars-and-rubrics">
252 <generated classes="sectnum">
254 Topics, Sidebars, and Rubrics
257 <reference ids="id60" refid="target-footnotes">
258 <generated classes="sectnum">
263 <reference ids="id61" refid="replacement-text">
264 <generated classes="sectnum">
269 <reference ids="id62" refid="compound-paragraph">
270 <generated classes="sectnum">
275 <reference ids="id63" refid="parsed-literal-blocks">
276 <generated classes="sectnum">
278 Parsed Literal Blocks
281 <reference ids="id64" refid="code">
282 <generated classes="sectnum">
287 <reference ids="id65" refid="substitution-definitions">
288 <generated classes="sectnum">
290 Substitution Definitions
293 <reference ids="id66" refid="comments">
294 <generated classes="sectnum">
299 <reference ids="id67" refid="raw-text">
300 <generated classes="sectnum">
305 <reference ids="id68" refid="container">
306 <generated classes="sectnum">
311 <reference ids="id69" refid="colspanning-tables">
312 <generated classes="sectnum">
317 <reference ids="id70" refid="rowspanning-tables">
318 <generated classes="sectnum">
323 <reference ids="id71" refid="complex-tables">
324 <generated classes="sectnum">
329 <reference ids="id72" refid="list-tables">
330 <generated classes="sectnum">
335 <reference ids="id73" refid="error-handling">
336 <generated classes="sectnum">
339 <section ids="structural-elements" names="structural\ elements">
340 <title auto="1" refid="id34">
341 <generated classes="sectnum">
344 <section ids="section-title" names="section\ title">
345 <title auto="1" refid="id35">
346 <generated classes="sectnum">
349 <subtitle ids="section-subtitle" names="section\ subtitle">
352 Lone subsections are converted to a section subtitle by a transform
356 command line option or the
360 <section ids="empty-section" names="empty\ section">
361 <title auto="1" refid="id36">
362 <generated classes="sectnum">
365 <section ids="transitions" names="transitions">
366 <title auto="1" refid="id37">
367 <generated classes="sectnum">
374 It divides the section. Transitions may also occur between sections:
376 <section ids="body-elements" names="body\ elements">
377 <title auto="1" refid="id38">
378 <generated classes="sectnum">
381 <section ids="paragraphs" names="paragraphs">
382 <title auto="1" refid="id39">
383 <generated classes="sectnum">
388 <section ids="inline-markup" names="inline\ markup">
389 <title auto="1" refid="id40">
390 <generated classes="sectnum">
394 Paragraphs contain text and may contain inline markup:
403 , standalone hyperlinks
405 <reference refuri="http://www.python.org">
406 http://www.python.org
407 ), external hyperlinks (
408 <reference name="Python" refuri="http://www.python.org/">
411 <footnote_reference auto="1" ids="id26" refid="id25">
415 <reference name="example" refid="example">
417 ), external hyperlinks with embedded URIs
419 <reference name="Python web site" refuri="http://www.python.org">
422 <reference anonymous="1" name="anonymous hyperlink references" refuri="http://www.python.org/">
426 <footnote_reference auto="1" ids="id31" refid="id25">
429 <reference anonymous="1" name="a second reference" refuri="http://docutils.sourceforge.net/">
432 <footnote_reference auto="1" ids="id33" refid="id32">
434 ), footnote references (manually
436 <footnote_reference ids="id1" refid="id8">
438 , anonymous auto-numbered
439 <footnote_reference auto="1" ids="id2" refid="id12">
441 , labeled auto-numbered
442 <footnote_reference auto="1" ids="id3" refid="label">
445 <footnote_reference auto="*" ids="id4" refid="id13">
447 ), citation references (
448 <citation_reference ids="id5" refid="cit2002">
451 substitution references (
452 <image alt="EXAMPLE" uri="../../../docs/user/rst/images/biohazard.png">
454 <target ids="inline-hyperlink-targets" names="inline\ hyperlink\ targets">
455 inline hyperlink targets
458 <reference name="Targets" refid="targets">
460 below for a reference back to here). Character-level
461 inline markup is also possible (although exceedingly ugly!) in
468 . Problems are indicated by
469 <problematic ids="id24" refid="id23">
472 (generated by processing errors; this one is intentional). Here is a
474 <reference name="doctitle" refid="doctitle">
477 <reference name="subtitle" refid="subtitle">
480 <target anonymous="1" ids="id6" refuri="http://www.python.org/">
481 <target anonymous="1" ids="id7" refuri="http://docutils.sourceforge.net/">
483 The default role for interpreted text is
487 some explicit interpreted text roles: a PEP reference (
488 <reference refuri="http://www.python.org/dev/peps/pep-0287">
492 <reference refuri="http://www.faqs.org/rfcs/rfc2822.html">
502 <literal classes="code">
511 and explicit roles for
524 <comment xml:space="preserve">
525 DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
527 Let's test wrapping and whitespace significance in inline literals:
529 This is an example of --inline-literal --text, --including some--
530 strangely--hyphenated-words. Adjust-the-width-of-your-browser-window
531 to see how the text is wrapped. -- ---- -------- Now note the
532 spacing between the words of this sentence (words
533 should be grouped in pairs).
538 option was supplied, there should be a
539 live link to PEP 258 here.
540 <section ids="bullet-lists" names="bullet\ lists">
541 <title auto="1" refid="id41">
542 <generated classes="sectnum">
545 <bullet_list bullet="-">
549 <bullet_list bullet="+">
560 Paragraph 2 of item 2.
561 <bullet_list bullet="*">
568 <bullet_list bullet="-">
580 This nested list should be compacted by the HTML writer.
581 <target ids="target" names="target">
582 <comment xml:space="preserve">
583 Even if this item contains a target and a comment.
584 <section ids="enumerated-lists" names="enumerated\ lists">
585 <title auto="1" refid="id42">
586 <generated classes="sectnum">
589 <enumerated_list enumtype="arabic" prefix="" suffix=".">
593 <enumerated_list enumtype="loweralpha" prefix="" suffix=")">
597 <enumerated_list enumtype="lowerroman" prefix="(" suffix=")">
601 <enumerated_list enumtype="upperalpha" prefix="" suffix=".">
605 <enumerated_list enumtype="upperroman" prefix="" suffix=")">
611 Lists that don't start at 1:
612 <enumerated_list enumtype="arabic" prefix="" start="3" suffix=".">
619 <system_message level="1" line="8" source="functional/input/data/standard.txt" type="INFO">
621 Enumerated list start value not ordinal-1: "3" (ordinal 3)
622 <enumerated_list enumtype="upperalpha" prefix="" start="3" suffix=".">
629 <system_message level="1" line="8" source="functional/input/data/standard.txt" type="INFO">
631 Enumerated list start value not ordinal-1: "C" (ordinal 3)
632 <enumerated_list enumtype="lowerroman" prefix="" start="3" suffix=".">
639 <system_message level="1" line="8" source="functional/input/data/standard.txt" type="INFO">
641 Enumerated list start value not ordinal-1: "iii" (ordinal 3)
642 <section ids="definition-lists" names="definition\ lists">
643 <title auto="1" refid="id43">
644 <generated classes="sectnum">
648 <definition_list_item>
654 <definition_list_item>
661 Definition paragraph 1.
663 Definition paragraph 2.
664 <definition_list_item>
670 <definition_list_item>
680 <section ids="field-lists" names="field\ lists">
681 <title auto="1" refid="id44">
682 <generated classes="sectnum">
691 Field lists map field names to field bodies, like database
692 records. They are often part of an extension syntax. They are
693 an unambiguous variant of RFC 2822 fields.
699 The field marker is a colon, the field name, and a colon.
701 The field body may contain one or more body elements, indented
702 relative to the field marker.
707 <paragraph classes="credits">
708 This paragraph has the
711 class set. (This is actually not
712 about credits but just for ensuring that the class attribute
713 doesn't get stripped away.)
714 <section ids="option-lists" names="option\ lists">
715 <title auto="1" refid="id45">
716 <generated classes="sectnum">
720 For listing command-line options:
729 command-line option "a"
735 <option_argument delimiter=" ">
739 options can have arguments
740 and long descriptions
748 options can be long also
754 <option_argument delimiter="=">
758 long options can also have
767 The description can also start on the next line.
769 The description may contain multiple body elements,
770 regardless of where it starts.
784 Multiple options are an "option group".
795 Commonly-seen: short & long options.
801 <option_argument delimiter=" ">
806 <option_argument delimiter="=">
811 <option_argument delimiter=" ">
815 Multiple options with arguments.
823 DOS/VMS-style options too
825 There must be at least two spaces between the option and the
827 <section ids="literal-blocks" names="literal\ blocks">
828 <title auto="1" refid="id46">
829 <generated classes="sectnum">
833 Literal blocks are indicated with a double-colon ("::") at the end of
834 the preceding paragraph (over there
837 ). They can be indented:
838 <literal_block xml:space="preserve">
840 text = 'is left as-is'
841 spaces_and_linebreaks = 'are preserved'
842 markup_processing = None
844 Or they can be quoted without indentation:
845 <literal_block xml:space="preserve">
848 > Why didn't I think of that?
849 <section ids="line-blocks" names="line\ blocks">
850 <title auto="1" refid="id47">
851 <generated classes="sectnum">
855 This section tests line blocks. Line blocks are body elements which
856 consist of lines and other line blocks. Nested line blocks cause
860 This is a line block. It ends with a blank line.
863 New lines begin with a vertical bar ("|").
865 Line breaks and initial indent are significant, and preserved.
868 Continuation lines are also possible. A long line that is intended
869 to wrap should begin with a space in place of the vertical bar.
871 The left edge of a continuation line need not be aligned with
872 the left edge of the text above it.
875 This is a second line block.
878 Blank lines are permitted internally, but they must begin with a "|".
880 Another line block, surrounded by paragraphs:
883 And it's no good waiting by the window
885 It's no good waiting for the sun
887 Please believe me, the things you dream of
889 They don't fall in the lap of no-one
891 Take it away, Eric the Orchestra Leader!
895 A one, two, a one two three four
898 Half a bee, philosophically,
906 But half the bee has got to be,
911 its entity. D'you see?
914 But can a bee be said to be
917 or not to be an entire bee,
920 when half the bee is not a bee,
923 due to some ancient injury?
928 A line block, like the following poem by Christian Morgenstern, can
929 also be centre-aligned:
930 <line_block classes="language-de align-center">
936 Zwei Trichter wandeln durch die Nacht.
938 Durch ihres Rumpfs verengten Schacht
940 fließt weißes Mondlicht
952 <section ids="block-quotes" names="block\ quotes">
953 <title auto="1" refid="id48">
954 <generated classes="sectnum">
958 Block quotes consist of indented body elements:
961 My theory by A. Elk. Brackets Miss, brackets. This theory goes
962 as follows and begins now. All brontosauruses are thin at one
963 end, much much thicker in the middle and then thin again at the
964 far end. That is my theory, it is mine, and belongs to me and I
965 own it, and what it is too.
969 The language of a quote (like any other object) can be specified by
971 <comment xml:space="preserve">
972 <block_quote classes="language-fr">
974 ReStructuredText est un langage de balisage léger utilisé
975 notamment dans la documentation du langage Python.
976 <section ids="doctest-blocks" names="doctest\ blocks">
977 <title auto="1" refid="id49">
978 <generated classes="sectnum">
981 <doctest_block xml:space="preserve">
982 >>> print 'Python-specific usage examples; begun with ">>>"'
983 Python-specific usage examples; begun with ">>>"
984 >>> print '(cut and pasted from interactive Python sessions)'
985 (cut and pasted from interactive Python sessions)
986 <section ids="footnotes" names="footnotes">
987 <title auto="1" refid="id50">
988 <generated classes="sectnum">
991 <footnote backrefs="id1 id9 id22" ids="id8" names="1">
995 A footnote contains body elements, consistently indented by at
998 This is the footnote's second paragraph.
999 <footnote auto="1" backrefs="id3 id10" ids="label" names="label">
1003 Footnotes may be numbered, either manually (as in
1004 <footnote_reference ids="id9" refid="id8">
1007 automatically using a "#"-prefixed label. This footnote has a
1008 label so it can be referred to from multiple places, both as a
1009 footnote reference (
1010 <footnote_reference auto="1" ids="id10" refid="label">
1013 <reference anonymous="1" name="hyperlink reference" refid="label">
1016 <target anonymous="1" ids="id11" refid="label">
1017 <footnote auto="1" backrefs="id2" ids="id12" names="3">
1021 This footnote is numbered automatically and anonymously using a
1024 This is the second paragraph.
1026 And this is the third paragraph.
1027 <footnote auto="*" backrefs="id4" ids="id13">
1031 Footnotes may also use symbols, specified with a "*" label.
1032 Here's a reference to the next footnote:
1033 <footnote_reference auto="*" ids="id14" refid="id15">
1036 <footnote auto="*" backrefs="id14" ids="id15">
1040 This footnote shows the next symbol in the sequence.
1041 <footnote ids="id16" names="4">
1045 Here's an unreferenced footnote, with a reference to a
1046 nonexistent footnote:
1047 <problematic ids="id84 id17" refid="id83">
1050 <section ids="citations" names="citations">
1051 <title auto="1" refid="id51">
1052 <generated classes="sectnum">
1055 <citation backrefs="id5 id18" ids="cit2002" names="cit2002">
1059 Citations are text-labeled footnotes. They may be
1060 rendered separately and differently from footnotes.
1062 Here's a reference to the above,
1063 <citation_reference ids="id18" refid="cit2002">
1066 <problematic ids="id86 id19" refid="id85">
1070 <target refid="another-target">
1071 <section ids="targets another-target" names="targets another\ target">
1072 <title auto="1" refid="id52">
1073 <generated classes="sectnum">
1076 <target refid="example">
1077 <paragraph ids="example" names="example">
1078 This paragraph is pointed to by the explicit "example" target. A
1079 reference can be found under
1080 <reference name="Inline Markup" refid="inline-markup">
1083 <reference name="Inline hyperlink targets" refid="inline-hyperlink-targets">
1088 Section headers are implicit targets, referred to by name. See
1089 <reference name="Targets" refid="targets">
1091 , which is a subsection of
1092 <reference name="Body Elements" refid="body-elements">
1096 Explicit external targets are interpolated into references such as
1098 <reference name="Python" refuri="http://www.python.org/">
1101 <footnote_reference auto="1" ids="id27" refid="id25">
1104 <target ids="python" names="python" refuri="http://www.python.org/">
1106 Targets may be indirect and anonymous. Thus
1107 <reference anonymous="1" name="this phrase" refid="targets">
1111 <reference name="Targets" refid="targets">
1114 <target anonymous="1" ids="id20" refid="targets">
1117 <problematic ids="id88" refid="id87">
1118 `hyperlink reference without a target`_
1119 , which generates an
1121 <section dupnames="duplicate\ target\ names" ids="duplicate-target-names">
1122 <title auto="1" refid="id53">
1123 <generated classes="sectnum">
1125 Duplicate Target Names
1127 Duplicate names in section headers or other implicit targets will
1128 generate "info" (level-1) system messages. Duplicate names in
1129 explicit targets will generate "warning" (level-2) system messages.
1130 <section dupnames="duplicate\ target\ names" ids="id21">
1131 <title auto="1" refid="id54">
1132 <generated classes="sectnum">
1134 Duplicate Target Names
1135 <system_message backrefs="id21" level="1" line="438" source="functional/input/data/standard.txt" type="INFO">
1137 Duplicate implicit target name: "duplicate target names".
1139 Since there are two "Duplicate Target Names" section headers, we
1140 cannot uniquely refer to either of them by name. If we try to (like
1142 <problematic ids="id90" refid="id89">
1143 `Duplicate Target Names`_
1144 ), an error is generated.
1145 <section ids="directives" names="directives">
1146 <title auto="1" refid="id55">
1147 <generated classes="sectnum">
1150 <topic classes="contents local" ids="contents" names="contents">
1151 <bullet_list classes="auto-toc">
1154 <reference ids="id74" refid="document-parts">
1155 <generated classes="sectnum">
1160 <reference ids="id75" refid="images-and-figures">
1161 <generated classes="sectnum">
1166 <reference ids="id76" refid="admonitions">
1167 <generated classes="sectnum">
1172 <reference ids="id77" refid="topics-sidebars-and-rubrics">
1173 <generated classes="sectnum">
1175 Topics, Sidebars, and Rubrics
1178 <reference ids="id78" refid="target-footnotes">
1179 <generated classes="sectnum">
1184 <reference ids="id79" refid="replacement-text">
1185 <generated classes="sectnum">
1190 <reference ids="id80" refid="compound-paragraph">
1191 <generated classes="sectnum">
1196 <reference ids="id81" refid="parsed-literal-blocks">
1197 <generated classes="sectnum">
1199 Parsed Literal Blocks
1202 <reference ids="id82" refid="code">
1203 <generated classes="sectnum">
1207 These are just a sample of the many reStructuredText Directives. For
1209 <reference refuri="http://docutils.sourceforge.net/docs/ref/rst/directives.html">
1210 http://docutils.sourceforge.net/docs/ref/rst/directives.html
1212 <section ids="document-parts" names="document\ parts">
1213 <title auto="1" refid="id74">
1214 <generated classes="sectnum">
1218 An example of the "contents" directive can be seen above this section
1219 (a local, untitled table of
1220 <reference name="contents" refid="contents">
1222 ) and at the beginning of the
1223 document (a document-wide
1224 <reference name="table of contents" refid="table-of-contents">
1227 <section ids="images-and-figures" names="images\ and\ figures">
1228 <title auto="1" refid="id75">
1229 <generated classes="sectnum">
1233 An image directive (also clickable -- a hyperlink reference):
1234 <reference name="directives" refid="directives">
1235 <image classes="class1 class2" uri="../../../docs/user/rst/images/title.png">
1237 Image with multiple IDs:
1238 <target refid="image-target-1">
1239 <target refid="image-target-2">
1240 <target refid="image-target-3">
1241 <image ids="image-target-3 image-target-2 image-target-1" names="image\ target\ 3 image\ target\ 2 image\ target\ 1" uri="../../../docs/user/rst/images/title.png">
1244 <image align="center" uri="../../../docs/user/rst/images/biohazard.png">
1246 A left-aligned image:
1247 <image align="left" uri="../../../docs/user/rst/images/biohazard.png">
1249 This paragraph might flow around the image.
1250 The specific behavior depends upon the style sheet and
1251 the browser or rendering software used.
1253 A right-aligned image:
1254 <image align="right" uri="../../../docs/user/rst/images/biohazard.png">
1256 This paragraph might flow around the image.
1257 The specific behavior depends upon the style sheet and
1258 the browser or rendering software used.
1260 For inline images see
1261 <reference name="Substitution Definitions" refid="substitution-definitions">
1262 Substitution Definitions
1268 <image uri="../../../docs/user/rst/images/biohazard.png" width="2em">
1270 An image 2 em wide and 15 pixel high:
1271 <image height="15px" uri="../../../docs/user/rst/images/biohazard.png" width="2em">
1273 An image occupying 50% of the line width:
1274 <image uri="../../../docs/user/rst/images/title.png" width="50%">
1277 <image height="2cm" uri="../../../docs/user/rst/images/biohazard.png">
1282 is an image with a caption and/or a legend. With page-based output
1283 media, figures might float to a different position if this helps the page
1285 <figure classes="figclass1 figclass2">
1286 <image alt="reStructuredText, the markup syntax" classes="class1 class2" uri="../../../docs/user/rst/images/title.png" width="258">
1288 Plaintext markup syntax and parser system.
1292 <colspec colwidth="12">
1293 <colspec colwidth="47">
1301 Revised, revisited, based on 're' module.
1308 Structure-enhanced text, structuredtext.
1315 Well it is, isn't it?
1317 This paragraph is also part of the legend.
1319 A left-aligned figure:
1320 <figure align="left" classes="figclass1 figclass2" width="70%">
1321 <image alt="reStructuredText, the markup syntax" classes="class1 class2" uri="../../../docs/user/rst/images/biohazard.png" width="40px">
1323 This is the caption.
1328 The legend may consist of several paragraphs.
1330 This paragraph might flow around the figure.
1332 The specific behavior depends upon the style sheet and the browser or
1333 rendering software used.
1336 <figure align="center">
1337 <image uri="../../../docs/user/rst/images/biohazard.png" width="40px">
1339 This is the caption.
1344 The legend may consist of several paragraphs.
1346 This paragraph might flow around the figure.
1348 The specific behavior depends upon the style sheet and the browser or
1349 rendering software used.
1351 A right-aligned figure:
1352 <figure align="right">
1353 <image uri="../../../docs/user/rst/images/biohazard.png" width="40px">
1355 This is the caption.
1360 The legend may consist of several paragraphs.
1362 This paragraph might flow around the figure. The specific behavior depends
1363 upon the style sheet and the browser or rendering software used.
1364 <section ids="admonitions" names="admonitions">
1365 <title auto="1" refid="id76">
1366 <generated classes="sectnum">
1371 Directives at large.
1374 Don't take any wooden nickels.
1377 Mad scientist at work!
1383 It's bigger than a bread box.
1385 <bullet_list bullet="-">
1388 Wash behind your ears.
1403 15% if the service is good.
1406 Strong prose may provoke extreme mental exertion.
1407 Reader discretion is strongly advised.
1408 <admonition classes="admonition-and-by-the-way">
1412 You can make up your own admonition too.
1413 <target ids="docutils" names="docutils" refuri="http://docutils.sourceforge.net/">
1414 <section ids="topics-sidebars-and-rubrics" names="topics,\ sidebars,\ and\ rubrics">
1415 <title auto="1" refid="id77">
1416 <generated classes="sectnum">
1418 Topics, Sidebars, and Rubrics
1422 are like miniature, parallel documents.
1429 This is a sidebar. It is for text outside the flow of the main
1432 This is a rubric inside a sidebar
1434 Sidebars often appear beside the main text with a border and a different
1435 background or font color.
1440 is like a block quote with a title, or a self-contained section
1441 with no subsections.
1451 is like an informal heading that doesn't correspond to the
1452 document's structure. It is typically highlighted in red (hence the name).
1456 Topics and rubrics can be used at places where a
1457 <reference name="section title" refid="section-title">
1460 allowed (e.g. inside a directive).
1461 <section ids="target-footnotes" names="target\ footnotes">
1462 <title auto="1" refid="id78">
1463 <generated classes="sectnum">
1466 <footnote auto="1" backrefs="id26 id27 id28 id31" ids="id25" names="TARGET_NOTE:\ id25">
1470 <reference refuri="http://www.python.org/">
1471 http://www.python.org/
1472 <footnote auto="1" backrefs="id30" ids="id29" names="TARGET_NOTE:\ id29">
1476 <reference refuri="http://pygments.org/">
1477 http://pygments.org/
1478 <footnote auto="1" backrefs="id33" ids="id32" names="TARGET_NOTE:\ id32">
1482 <reference refuri="http://docutils.sourceforge.net/">
1483 http://docutils.sourceforge.net/
1484 <section ids="replacement-text" names="replacement\ text">
1485 <title auto="1" refid="id79">
1486 <generated classes="sectnum">
1491 <reference refuri="http://www.python.org/">
1495 best language around
1497 <footnote_reference auto="1" ids="id28" refid="id25">
1500 <substitution_definition names="Python">
1504 best language around
1505 <section ids="compound-paragraph" names="compound\ paragraph">
1506 <title auto="1" refid="id80">
1507 <generated classes="sectnum">
1510 <compound classes="some-class">
1512 Compound 1, paragraph 1.
1514 Compound 1, paragraph 2.
1515 <bullet_list bullet="*">
1518 Compound 1, list item one.
1521 Compound 1, list item two.
1523 Another compound statement:
1526 Compound 2, a literal block:
1527 <literal_block xml:space="preserve">
1528 Compound 2, literal.
1530 Compound 2, this is a test.
1533 Compound 3, only consisting of one paragraph.
1535 <literal_block xml:space="preserve">
1537 This one starts with a literal block.
1539 Compound 4, a paragraph.
1544 perverted -- a nested compound block. This is
1545 just to test that it works at all; the results don't have to be
1549 Compound 5, block 1 (a paragraph).
1552 Compound 6, block 2 in compound 5.
1554 Compound 6, another paragraph.
1556 Compound 5, block 3 (a paragraph).
1559 Compound 7, with a table inside:
1562 <colspec colwidth="20">
1563 <colspec colwidth="20">
1564 <colspec colwidth="20">
1588 Compound 7, a paragraph after the table.
1590 Compound 7, another paragraph.
1591 <section ids="parsed-literal-blocks" names="parsed\ literal\ blocks">
1592 <title auto="1" refid="id81">
1593 <generated classes="sectnum">
1595 Parsed Literal Blocks
1596 <literal_block xml:space="preserve">
1597 This is a parsed literal block.
1598 This line is indented. The next line is blank.
1600 Inline markup is supported, e.g.
1611 <footnote_reference ids="id22" refid="id8">
1614 <target ids="hyperlink-targets" names="hyperlink\ targets">
1617 <reference name="references" refuri="http://www.python.org/">
1619 <target ids="references" names="references" refuri="http://www.python.org/">
1621 <section ids="code" names="code">
1622 <title auto="1" refid="id82">
1623 <generated classes="sectnum">
1627 Blocks of source code can be set with the
1630 directive. If the code
1631 language is specified, the content is parsed and tagged by the
1632 <reference name="Pygments" refuri="http://pygments.org/">
1635 <footnote_reference auto="1" ids="id30" refid="id29">
1638 syntax highlighter and can be formatted with a style sheet. (Code parsing
1639 is turned off using the
1642 config setting in the test
1643 conversions in order to get identical results with/without installed
1644 Pygments highlighter.)
1645 <literal_block classes="code python" xml:space="preserve">
1646 print 'This is Python code.'
1651 option (with optional start value) generates line
1653 <literal_block classes="code python" xml:space="preserve">
1654 <inline classes="ln">
1656 # print integers from 0 to 9:
1657 <inline classes="ln">
1660 <inline classes="ln">
1664 For inline code snippets, there is the
1667 role, which can be used
1668 directly (the code will not be parsed/tagged, as the language is not known)
1669 or as base for special code roles, e.g. the LaTeX code in the next
1672 Docutils uses LaTeX syntax for math directives and roles:
1673 <literal classes="code tex">
1686 directive sets the included content
1687 as a code block, here the rst file
1691 <literal_block classes="code rst" source="functional/input/data/header_footer.txt" xml:space="preserve">
1692 <inline classes="ln">
1694 .. header:: Document header
1695 <inline classes="ln">
1697 .. footer:: Document footer
1698 <target ids="pygments" names="pygments" refuri="http://pygments.org/">
1699 <section ids="substitution-definitions" names="substitution\ definitions">
1700 <title auto="1" refid="id65">
1701 <generated classes="sectnum">
1703 Substitution Definitions
1706 <image alt="EXAMPLE" uri="../../../docs/user/rst/images/biohazard.png">
1708 <substitution_definition names="EXAMPLE">
1709 <image alt="EXAMPLE" uri="../../../docs/user/rst/images/biohazard.png">
1711 (Substitution definitions are not visible in the HTML source.)
1712 <section ids="comments" names="comments">
1713 <title auto="1" refid="id66">
1714 <generated classes="sectnum">
1719 <comment xml:space="preserve">
1720 Comments begin with two dots and a space. Anything may
1721 follow, except for the syntax of footnotes, hyperlink
1722 targets, directives, or substitution definitions.
1724 Double-dashes -- "--" -- must be escaped somehow in HTML output.
1726 Comments may contain non-ASCII characters: ä ö ü æ ø å
1728 (View the HTML source to see the comment.)
1729 <section ids="raw-text" names="raw\ text">
1730 <title auto="1" refid="id67">
1731 <generated classes="sectnum">
1735 This does not necessarily look nice, because there may be missing white space.
1737 It's just there to freeze the behavior.
1738 <raw format="html latex" xml:space="preserve">
1740 <raw format="html latex" xml:space="preserve">
1742 <raw classes="myclass" format="html latex" xml:space="preserve">
1743 Another test with myclass set.
1746 <raw classes="myrawroleclass" format="html latex" xml:space="preserve">
1748 with myrawroleclass set.
1749 <raw format="html" xml:space="preserve">
1750 Fifth test in HTML.<br />Line two.
1751 <raw format="latex" xml:space="preserve">
1752 Fifth test in LaTeX.\\Line two.
1753 <section ids="container" names="container">
1754 <title auto="1" refid="id68">
1755 <generated classes="sectnum">
1758 <container classes="custom">
1763 <section ids="colspanning-tables" names="colspanning\ tables">
1764 <title auto="1" refid="id69">
1765 <generated classes="sectnum">
1769 This table has a cell spanning two columns:
1772 <colspec colwidth="5">
1773 <colspec colwidth="5">
1774 <colspec colwidth="6">
1777 <entry morecols="1">
1834 <section ids="rowspanning-tables" names="rowspanning\ tables">
1835 <title auto="1" refid="id70">
1836 <generated classes="sectnum">
1840 Here's a table with cells spanning several rows:
1843 <colspec colwidth="24">
1844 <colspec colwidth="12">
1845 <colspec colwidth="18">
1850 Header row, column 1
1851 (header rows optional)
1862 body row 1, column 1
1873 <entry morerows="1">
1877 <entry morerows="1">
1886 <section ids="complex-tables" names="complex\ tables">
1887 <title auto="1" refid="id71">
1888 <generated classes="sectnum">
1892 Here's a complex table, which should test all features.
1895 <colspec colwidth="24">
1896 <colspec colwidth="12">
1897 <colspec colwidth="10">
1898 <colspec colwidth="10">
1903 Header row, column 1
1904 (header rows optional)
1918 body row 1, column 1
1932 <entry morecols="2">
1934 Cells may span columns.
1939 <entry morerows="1">
1945 <entry morecols="1" morerows="1">
1946 <bullet_list bullet="-">
1964 <entry morecols="1">
1971 <section ids="list-tables" names="list\ tables">
1972 <title auto="1" refid="id72">
1973 <generated classes="sectnum">
1977 Here's a list table exercising all features:
1978 <table classes="test">
1980 list table with integral header
1982 <colspec colwidth="10" stub="1">
1983 <colspec colwidth="20">
1984 <colspec colwidth="30">
2016 If we took the bones out, it wouldn't be
2017 crunchy, now would it?
2028 <section ids="error-handling" names="error\ handling">
2029 <title auto="1" refid="id73">
2030 <generated classes="sectnum">
2034 Any errors caught during processing will generate system messages.
2036 There should be five messages in the following, auto-generated
2037 section, "Docutils System Messages":
2038 <comment xml:space="preserve">
2039 section should be added by Docutils automatically
2040 <section classes="system-messages">
2042 Docutils System Messages
2043 <system_message backrefs="id24" ids="id23" level="3" line="104" source="functional/input/data/standard.txt" type="ERROR">
2045 Undefined substitution referenced: "problematic".
2046 <system_message backrefs="id84" ids="id83" level="3" line="391" source="functional/input/data/standard.txt" type="ERROR">
2048 Unknown target name: "5".
2049 <system_message backrefs="id86" ids="id85" level="3" line="400" source="functional/input/data/standard.txt" type="ERROR">
2051 Unknown target name: "nonexistent".
2052 <system_message backrefs="id88" ids="id87" level="3" line="427" source="functional/input/data/standard.txt" type="ERROR">
2054 Unknown target name: "hyperlink reference without a target".
2055 <system_message backrefs="id90" ids="id89" level="3" line="440" source="functional/input/data/standard.txt" type="ERROR">
2057 Duplicate target name, cannot be used as a unique reference: "duplicate target names".
2058 <system_message level="1" line="163" source="functional/input/data/standard.txt" type="INFO">
2060 Hyperlink target "target" is not referenced.
2061 <system_message level="1" line="405" source="functional/input/data/standard.txt" type="INFO">
2063 Hyperlink target "another-target" is not referenced.
2064 <system_message level="1" line="473" source="functional/input/data/standard.txt" type="INFO">
2066 Hyperlink target "image-target-1" is not referenced.
2067 <system_message level="1" line="474" source="functional/input/data/standard.txt" type="INFO">
2069 Hyperlink target "image-target-2" is not referenced.
2070 <system_message level="1" line="475" source="functional/input/data/standard.txt" type="INFO">
2072 Hyperlink target "image-target-3" is not referenced.
2073 <system_message level="1" line="632" source="functional/input/data/standard.txt" type="INFO">
2075 Hyperlink target "docutils" is not referenced.
2076 <system_message level="1" line="753" source="functional/input/data/standard.txt" type="INFO">
2078 Hyperlink target "hyperlink targets" is not referenced.