| blob | 400a10cdc74a13fbb83a35fb8c7880bc6ec9370a |
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML" "http://docutils.sourceforge.net/docs/ref/docutils.dtd">
3 <!-- Generated by Docutils 0.19.1b.dev -->
4 <document ids="restructuredtext-test-document doctitle" names="restructuredtext\ test\ document doctitle" source="functional/input/standalone_rst_docutils_xml.txt" title="reStructuredText Test Document">
5 <title>reStructuredText Test Document</title>
6 <subtitle ids="examples-of-syntax-constructs subtitle" names="examples\ of\ syntax\ constructs subtitle">Examples of Syntax Constructs</subtitle>
7 <meta content="reStructuredText, test, parser" name="keywords">
8 </meta>
9 <meta content="A test document, containing at least one example of each reStructuredText construct." lang="en" name="description">
10 </meta>
11 <decoration>
12 <header>
13 <paragraph>Document header</paragraph>
14 </header>
15 <footer>
16 <paragraph>Document footer</paragraph>
17 </footer>
18 </decoration>
19 <docinfo>
20 <author>David Goodger</author>
21 <address xml:space="preserve">123 Example Street
22 Example, EX Canada
23 A1B 2C3</address>
24 <contact><reference refuri="mailto:goodger@python.org">goodger@python.org</reference></contact>
25 <authors>
26 <author>Me</author>
27 <author>Myself</author>
28 <author>I</author>
29 </authors>
30 <organization>humankind</organization>
31 <date>Now, or yesterday. Or maybe even <emphasis>before</emphasis> yesterday.</date>
32 <status>This is a "work in progress"</status>
33 <revision>is managed by a version control system.</revision>
34 <version>1</version>
35 <copyright>This document has been placed in the public domain. You
36 may do with it as you wish. You may copy, modify,
37 redistribute, reattribute, sell, buy, rent, lease,
38 destroy, or improve it, quote it at length, excerpt,
39 incorporate, collate, fold, staple, or mutilate it, or do
40 anything else to it that your or anyone else's heart
41 desires.</copyright>
42 <field classes="field-name">
43 <field_name>field name</field_name>
44 <field_body>
45 <paragraph>This is a "generic bibliographic field".</paragraph>
46 </field_body>
47 </field>
48 <field classes="field-name-2">
49 <field_name>field name "2"</field_name>
50 <field_body>
51 <paragraph>Generic bibliographic fields may contain multiple body elements.</paragraph>
52 <paragraph>Like this.</paragraph>
53 </field_body>
54 </field>
55 </docinfo>
56 <topic classes="dedication">
57 <title>Dedication</title>
58 <paragraph>For Docutils users & co-developers.</paragraph>
59 </topic>
60 <topic classes="abstract">
61 <title>Abstract</title>
62 <paragraph>This is a test document, containing at least one example of each
63 reStructuredText construct.</paragraph>
64 </topic>
65 <comment xml:space="preserve">This is a comment. Note how any initial comments are moved by
66 transforms to after the document title, subtitle, and docinfo.</comment>
67 <target refid="doctitle"></target>
68 <comment xml:space="preserve">Above is the document title, and below is the subtitle.
69 They are transformed from section titles after parsing.</comment>
70 <target refid="subtitle"></target>
71 <comment xml:space="preserve">bibliographic fields (which also require a transform):</comment>
72 <raw format="latex" xml:space="preserve">\pagebreak[4] % start ToC on new page</raw>
73 <topic classes="contents" ids="table-of-contents" names="table\ of\ contents">
74 <title>Table of Contents</title>
75 <bullet_list classes="auto-toc">
76 <list_item>
77 <paragraph><reference ids="toc-entry-1" refid="structural-elements"><generated classes="sectnum">1 </generated>Structural Elements</reference></paragraph>
78 <bullet_list classes="auto-toc">
79 <list_item>
80 <paragraph><reference ids="toc-entry-2" refid="section-title"><generated classes="sectnum">1.1 </generated>Section Title</reference></paragraph>
81 </list_item>
82 <list_item>
83 <paragraph><reference ids="toc-entry-3" refid="empty-section"><generated classes="sectnum">1.2 </generated>Empty Section</reference></paragraph>
84 </list_item>
85 <list_item>
86 <paragraph><reference ids="toc-entry-4" refid="transitions"><generated classes="sectnum">1.3 </generated>Transitions</reference></paragraph>
87 </list_item>
88 </bullet_list>
89 </list_item>
90 <list_item>
91 <paragraph><reference ids="toc-entry-5" refid="body-elements"><generated classes="sectnum">2 </generated>Body Elements</reference></paragraph>
92 <bullet_list classes="auto-toc">
93 <list_item>
94 <paragraph><reference ids="toc-entry-6" refid="paragraphs"><generated classes="sectnum">2.1 </generated>Paragraphs</reference></paragraph>
95 <bullet_list classes="auto-toc">
96 <list_item>
97 <paragraph><reference ids="toc-entry-7" refid="inline-markup"><generated classes="sectnum">2.1.1 </generated>Inline Markup</reference></paragraph>
98 </list_item>
99 </bullet_list>
100 </list_item>
101 <list_item>
102 <paragraph><reference ids="toc-entry-8" refid="bullet-lists"><generated classes="sectnum">2.2 </generated>Bullet Lists</reference></paragraph>
103 </list_item>
104 <list_item>
105 <paragraph><reference ids="toc-entry-9" refid="enumerated-lists"><generated classes="sectnum">2.3 </generated>Enumerated Lists</reference></paragraph>
106 </list_item>
107 <list_item>
108 <paragraph><reference ids="toc-entry-10" refid="definition-lists"><generated classes="sectnum">2.4 </generated>Definition Lists</reference></paragraph>
109 </list_item>
110 <list_item>
111 <paragraph><reference ids="toc-entry-11" refid="field-lists"><generated classes="sectnum">2.5 </generated>Field Lists</reference></paragraph>
112 </list_item>
113 <list_item>
114 <paragraph><reference ids="toc-entry-12" refid="option-lists"><generated classes="sectnum">2.6 </generated>Option Lists</reference></paragraph>
115 </list_item>
116 <list_item>
117 <paragraph><reference ids="toc-entry-13" refid="literal-blocks"><generated classes="sectnum">2.7 </generated>Literal Blocks</reference></paragraph>
118 </list_item>
119 <list_item>
120 <paragraph><reference ids="toc-entry-14" refid="line-blocks"><generated classes="sectnum">2.8 </generated>Line Blocks</reference></paragraph>
121 </list_item>
122 <list_item>
123 <paragraph><reference ids="toc-entry-15" refid="block-quotes"><generated classes="sectnum">2.9 </generated>Block Quotes</reference></paragraph>
124 </list_item>
125 <list_item>
126 <paragraph><reference ids="toc-entry-16" refid="doctest-blocks"><generated classes="sectnum">2.10 </generated>Doctest Blocks</reference></paragraph>
127 </list_item>
128 <list_item>
129 <paragraph><reference ids="toc-entry-17" refid="footnotes"><generated classes="sectnum">2.11 </generated>Footnotes</reference></paragraph>
130 </list_item>
131 <list_item>
132 <paragraph><reference ids="toc-entry-18" refid="citations"><generated classes="sectnum">2.12 </generated>Citations</reference></paragraph>
133 </list_item>
134 <list_item>
135 <paragraph><reference ids="toc-entry-19" refid="targets"><generated classes="sectnum">2.13 </generated>Targets</reference></paragraph>
136 <bullet_list classes="auto-toc">
137 <list_item>
138 <paragraph><reference ids="toc-entry-20" refid="duplicate-target-names"><generated classes="sectnum">2.13.1 </generated>Duplicate Target Names</reference></paragraph>
139 </list_item>
140 <list_item>
141 <paragraph><reference ids="toc-entry-21" refid="duplicate-target-names-1"><generated classes="sectnum">2.13.2 </generated>Duplicate Target Names</reference></paragraph>
142 </list_item>
143 </bullet_list>
144 </list_item>
145 <list_item>
146 <paragraph><reference ids="toc-entry-22" refid="directives"><generated classes="sectnum">2.14 </generated>Directives</reference></paragraph>
147 <bullet_list classes="auto-toc">
148 <list_item>
149 <paragraph><reference ids="toc-entry-23" refid="document-parts"><generated classes="sectnum">2.14.1 </generated>Document Parts</reference></paragraph>
150 </list_item>
151 <list_item>
152 <paragraph><reference ids="toc-entry-24" refid="images-and-figures"><generated classes="sectnum">2.14.2 </generated>Images and Figures</reference></paragraph>
153 </list_item>
154 <list_item>
155 <paragraph><reference ids="toc-entry-25" refid="tables"><generated classes="sectnum">2.14.3 </generated>Tables</reference></paragraph>
156 </list_item>
157 <list_item>
158 <paragraph><reference ids="toc-entry-26" refid="admonitions"><generated classes="sectnum">2.14.4 </generated>Admonitions</reference></paragraph>
159 </list_item>
160 <list_item>
161 <paragraph><reference ids="toc-entry-27" refid="topics-sidebars-and-rubrics"><generated classes="sectnum">2.14.5 </generated>Topics, Sidebars, and Rubrics</reference></paragraph>
162 </list_item>
163 <list_item>
164 <paragraph><reference ids="toc-entry-28" refid="target-footnotes"><generated classes="sectnum">2.14.6 </generated>Target Footnotes</reference></paragraph>
165 </list_item>
166 <list_item>
167 <paragraph><reference ids="toc-entry-29" refid="replacement-text"><generated classes="sectnum">2.14.7 </generated>Replacement Text</reference></paragraph>
168 </list_item>
169 <list_item>
170 <paragraph><reference ids="toc-entry-30" refid="compound-paragraph"><generated classes="sectnum">2.14.8 </generated>Compound Paragraph</reference></paragraph>
171 </list_item>
172 <list_item>
173 <paragraph><reference ids="toc-entry-31" refid="parsed-literal-blocks"><generated classes="sectnum">2.14.9 </generated>Parsed Literal Blocks</reference></paragraph>
174 </list_item>
175 <list_item>
176 <paragraph><reference ids="toc-entry-32" refid="code"><generated classes="sectnum">2.14.10 </generated>Code</reference></paragraph>
177 </list_item>
178 <list_item>
179 <paragraph><reference ids="toc-entry-33" refid="meta"><generated classes="sectnum">2.14.11 </generated>Meta</reference></paragraph>
180 </list_item>
181 </bullet_list>
182 </list_item>
183 <list_item>
184 <paragraph><reference ids="toc-entry-34" refid="substitution-definitions"><generated classes="sectnum">2.15 </generated>Substitution Definitions</reference></paragraph>
185 </list_item>
186 <list_item>
187 <paragraph><reference ids="toc-entry-35" refid="comments"><generated classes="sectnum">2.16 </generated>Comments</reference></paragraph>
188 </list_item>
189 <list_item>
190 <paragraph><reference ids="toc-entry-36" refid="raw-text"><generated classes="sectnum">2.17 </generated>Raw text</reference></paragraph>
191 </list_item>
192 <list_item>
193 <paragraph><reference ids="toc-entry-37" refid="container"><generated classes="sectnum">2.18 </generated>Container</reference></paragraph>
194 </list_item>
195 <list_item>
196 <paragraph><reference ids="toc-entry-38" refid="colspanning-tables"><generated classes="sectnum">2.19 </generated>Colspanning tables</reference></paragraph>
197 </list_item>
198 <list_item>
199 <paragraph><reference ids="toc-entry-39" refid="rowspanning-tables"><generated classes="sectnum">2.20 </generated>Rowspanning tables</reference></paragraph>
200 </list_item>
201 <list_item>
202 <paragraph><reference ids="toc-entry-40" refid="complex-tables"><generated classes="sectnum">2.21 </generated>Complex tables</reference></paragraph>
203 </list_item>
204 <list_item>
205 <paragraph><reference ids="toc-entry-41" refid="list-tables"><generated classes="sectnum">2.22 </generated>List Tables</reference></paragraph>
206 </list_item>
207 </bullet_list>
208 </list_item>
209 <list_item>
210 <paragraph><reference ids="toc-entry-42" refid="error-handling"><generated classes="sectnum">3 </generated>Error Handling</reference></paragraph>
211 </list_item>
212 </bullet_list>
213 </topic>
214 <section ids="structural-elements" names="structural\ elements">
215 <title auto="1" refid="toc-entry-1"><generated classes="sectnum">1 </generated>Structural Elements</title>
216 <section ids="section-title" names="section\ title">
217 <title auto="1" refid="toc-entry-2"><generated classes="sectnum">1.1 </generated>Section Title</title>
218 <subtitle ids="section-subtitle" names="section\ subtitle">Section Subtitle</subtitle>
219 <paragraph>Lone subsections are converted to a section subtitle by a transform
220 activated with the <literal>--section-subtitles</literal> command line option or the
221 <literal>sectsubtitle-xform</literal> configuration value.</paragraph>
222 </section>
223 <section ids="empty-section" names="empty\ section">
224 <title auto="1" refid="toc-entry-3"><generated classes="sectnum">1.2 </generated>Empty Section</title>
225 </section>
226 <section ids="transitions" names="transitions">
227 <title auto="1" refid="toc-entry-4"><generated classes="sectnum">1.3 </generated>Transitions</title>
228 <paragraph>Here's a transition:</paragraph>
229 <transition></transition>
230 <paragraph>It divides the section. Transitions may also occur between sections:</paragraph>
231 </section>
232 </section>
233 <transition></transition>
234 <section ids="body-elements" names="body\ elements">
235 <title auto="1" refid="toc-entry-5"><generated classes="sectnum">2 </generated>Body Elements</title>
236 <section ids="paragraphs" names="paragraphs">
237 <title auto="1" refid="toc-entry-6"><generated classes="sectnum">2.1 </generated>Paragraphs</title>
238 <paragraph>A paragraph.</paragraph>
239 <section ids="inline-markup" names="inline\ markup">
240 <title auto="1" refid="toc-entry-7"><generated classes="sectnum">2.1.1 </generated>Inline Markup</title>
241 <paragraph>Paragraphs contain text and may contain inline markup: <emphasis>emphasis</emphasis>,
242 <strong>strong emphasis</strong>, <literal>inline literals</literal>, standalone hyperlinks
243 (<reference refuri="http://www.python.org">http://www.python.org</reference>), external hyperlinks (<reference name="Python" refuri="http://www.python.org/">Python</reference> <footnote_reference auto="1" ids="footnote-reference-10" refid="footnote-6">5</footnote_reference>), internal
244 cross-references (<reference name="example" refid="example">example</reference>), external hyperlinks with embedded URIs
245 (<reference name="Python web site" refuri="http://www.python.org">Python web site</reference>), <reference anonymous="1" name="anonymous hyperlink references" refuri="http://www.python.org/">anonymous hyperlink
246 references</reference> <footnote_reference auto="1" ids="footnote-reference-14" refid="footnote-6">5</footnote_reference> (<reference anonymous="1" name="a second reference" refuri="https://docutils.sourceforge.io/">a second reference</reference> <footnote_reference auto="1" ids="footnote-reference-15" refid="footnote-8">7</footnote_reference>), footnote references (manually
247 numbered <footnote_reference ids="footnote-reference-1" refid="footnote-1">1</footnote_reference>, anonymous auto-numbered <footnote_reference auto="1" ids="footnote-reference-2" refid="footnote-2">3</footnote_reference>, labeled auto-numbered
248 <footnote_reference auto="1" ids="footnote-reference-3" refid="label">2</footnote_reference>, or symbolic <footnote_reference auto="*" ids="footnote-reference-4" refid="footnote-3">*</footnote_reference>), citation references (see <citation_reference ids="citation-reference-1" refid="cit2002">CIT2002</citation_reference>),
249 substitution references (<image alt="EXAMPLE" uri="../../../docs/user/rst/images/biohazard.png"></image> &
250 a <emphasis>trimmed heart</emphasis> <literal>(U+2665):</literal>♥), and <target ids="inline-hyperlink-targets" names="inline\ hyperlink\ targets">inline hyperlink targets</target>
251 (see <reference name="Targets" refid="targets">Targets</reference> below for a reference back to here). Character-level
252 inline markup is also possible (although exceedingly ugly!) in <emphasis>re</emphasis><literal>Structured</literal><emphasis>Text</emphasis>. Problems are indicated by <problematic ids="problematic-1" refid="system-message-1">|problematic|</problematic> text
253 (generated by processing errors; this one is intentional). Here is a
254 reference to the <reference name="doctitle" refid="doctitle">doctitle</reference> and the <reference name="subtitle" refid="subtitle">subtitle</reference>.</paragraph>
255 <target anonymous="1" ids="target-1" refuri="http://www.python.org/"></target>
256 <target anonymous="1" ids="target-2" refuri="https://docutils.sourceforge.io/"></target>
257 <paragraph>The default role for interpreted text is <title_reference>Title Reference</title_reference>. Here are
258 some explicit interpreted text roles: a PEP reference (<reference refuri="https://peps.python.org/pep-0287">PEP 287</reference>); an
259 RFC reference (<reference refuri="https://tools.ietf.org/html/rfc2822.html">RFC 2822</reference>); an abbreviation (<abbreviation>abb.</abbreviation>), an acronym
260 (<acronym>reST</acronym>), code (<literal classes="code">print "hello world"</literal>); a <subscript>subscript</subscript>;
261 a <superscript>superscript</superscript> and explicit roles for <title_reference>Docutils</title_reference>'
262 <emphasis>standard</emphasis> <strong>inline</strong> <literal>markup</literal>.</paragraph>
263 <comment xml:space="preserve">DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!</comment>
264 <paragraph>Let's test wrapping and whitespace significance in inline literals:
265 <literal>This is an example of --inline-literal --text, --including some--
266 strangely--hyphenated-words. Adjust-the-width-of-your-browser-window
267 to see how the text is wrapped. -- ---- -------- Now note the
268 spacing between the words of this sentence (words
269 should be grouped in pairs).</literal></paragraph>
270 <paragraph>If the <literal>--pep-references</literal> option was supplied, there should be a
271 live link to PEP 258 here.</paragraph>
272 </section>
273 </section>
274 <section ids="bullet-lists" names="bullet\ lists">
275 <title auto="1" refid="toc-entry-8"><generated classes="sectnum">2.2 </generated>Bullet Lists</title>
276 <bullet_list bullet="-">
277 <list_item>
278 <paragraph>A bullet list</paragraph>
279 <bullet_list bullet="+">
280 <list_item>
281 <paragraph>Nested bullet list.</paragraph>
282 </list_item>
283 <list_item>
284 <paragraph>Nested item 2.</paragraph>
285 </list_item>
286 </bullet_list>
287 </list_item>
288 <list_item>
289 <paragraph>Item 2.</paragraph>
290 <paragraph>Paragraph 2 of item 2.</paragraph>
291 <bullet_list bullet="*">
292 <list_item>
293 <paragraph>Nested bullet list.</paragraph>
294 </list_item>
295 <list_item>
296 <paragraph>Nested item 2.</paragraph>
297 <bullet_list bullet="-">
298 <list_item>
299 <paragraph>Third level.</paragraph>
300 </list_item>
301 <list_item>
302 <paragraph>Item 2.</paragraph>
303 </list_item>
304 </bullet_list>
305 </list_item>
306 <list_item>
307 <paragraph>Nested item 3.</paragraph>
308 </list_item>
309 <list_item>
310 <paragraph>This nested list should be compacted by the HTML writer.</paragraph>
311 <target ids="target" names="target"></target>
312 <comment xml:space="preserve">Even if this item contains a target and a comment.</comment>
313 </list_item>
314 </bullet_list>
315 </list_item>
316 </bullet_list>
317 </section>
318 <section ids="enumerated-lists" names="enumerated\ lists">
319 <title auto="1" refid="toc-entry-9"><generated classes="sectnum">2.3 </generated>Enumerated Lists</title>
320 <enumerated_list enumtype="arabic" prefix="" suffix=".">
321 <list_item>
322 <paragraph>Arabic numerals.</paragraph>
323 <enumerated_list enumtype="loweralpha" prefix="" suffix=")">
324 <list_item>
325 <paragraph>lower alpha)</paragraph>
326 <enumerated_list enumtype="lowerroman" prefix="(" suffix=")">
327 <list_item>
328 <paragraph>(lower roman)</paragraph>
329 <enumerated_list enumtype="upperalpha" prefix="" suffix=".">
330 <list_item>
331 <paragraph>upper alpha.</paragraph>
332 <enumerated_list enumtype="upperroman" prefix="" suffix=")">
333 <list_item>
334 <paragraph>upper roman)</paragraph>
335 </list_item>
336 </enumerated_list>
337 </list_item>
338 </enumerated_list>
339 </list_item>
340 </enumerated_list>
341 </list_item>
342 </enumerated_list>
343 </list_item>
344 <list_item>
345 <paragraph>Lists that don't start at 1:</paragraph>
346 <enumerated_list enumtype="arabic" prefix="" start="3" suffix=".">
347 <list_item>
348 <paragraph>Three</paragraph>
349 </list_item>
350 <list_item>
351 <paragraph>Four</paragraph>
352 </list_item>
353 </enumerated_list>
354 <system_message level="1" line="8" source="functional/input/data/standard.txt" type="INFO">
355 <paragraph>Enumerated list start value not ordinal-1: "3" (ordinal 3)</paragraph>
356 </system_message>
357 <enumerated_list enumtype="upperalpha" prefix="" start="3" suffix=".">
358 <list_item>
359 <paragraph>C</paragraph>
360 </list_item>
361 <list_item>
362 <paragraph>D</paragraph>
363 </list_item>
364 </enumerated_list>
365 <system_message level="1" line="8" source="functional/input/data/standard.txt" type="INFO">
366 <paragraph>Enumerated list start value not ordinal-1: "C" (ordinal 3)</paragraph>
367 </system_message>
368 <enumerated_list enumtype="lowerroman" prefix="" start="3" suffix=".">
369 <list_item>
370 <paragraph>iii</paragraph>
371 </list_item>
372 <list_item>
373 <paragraph>iv</paragraph>
374 </list_item>
375 </enumerated_list>
376 <system_message level="1" line="8" source="functional/input/data/standard.txt" type="INFO">
377 <paragraph>Enumerated list start value not ordinal-1: "iii" (ordinal 3)</paragraph>
378 </system_message>
379 </list_item>
380 </enumerated_list>
381 </section>
382 <section ids="definition-lists" names="definition\ lists">
383 <title auto="1" refid="toc-entry-10"><generated classes="sectnum">2.4 </generated>Definition Lists</title>
384 <definition_list>
385 <definition_list_item>
386 <term>Term</term>
387 <definition>
388 <paragraph>Definition</paragraph>
389 </definition>
390 </definition_list_item>
391 <definition_list_item>
392 <term>Term</term>
393 <classifier>classifier</classifier>
394 <definition>
395 <paragraph>Definition paragraph 1.</paragraph>
396 <paragraph>Definition paragraph 2.</paragraph>
397 </definition>
398 </definition_list_item>
399 <definition_list_item>
400 <term>Term</term>
401 <definition>
402 <paragraph>Definition</paragraph>
403 </definition>
404 </definition_list_item>
405 <definition_list_item>
406 <term>Term</term>
407 <classifier>classifier one</classifier>
408 <classifier>classifier two</classifier>
409 <definition>
410 <paragraph>Definition</paragraph>
411 </definition>
412 </definition_list_item>
413 </definition_list>
414 </section>
415 <section ids="field-lists" names="field\ lists">
416 <title auto="1" refid="toc-entry-11"><generated classes="sectnum">2.5 </generated>Field Lists</title>
417 <field_list>
418 <field>
419 <field_name>what</field_name>
420 <field_body>
421 <paragraph>Field lists map field names to field bodies, like database
422 records. They are often part of an extension syntax. They are
423 an unambiguous variant of RFC 2822 fields.</paragraph>
424 </field_body>
425 </field>
426 <field>
427 <field_name>how arg1 arg2</field_name>
428 <field_body>
429 <paragraph>The field marker is a colon, the field name, and a colon.</paragraph>
430 <paragraph>The field body may contain one or more body elements, indented
431 relative to the field marker.</paragraph>
432 </field_body>
433 </field>
434 <field>
435 <field_name>credits</field_name>
436 <field_body>
437 <paragraph classes="credits">This paragraph has the <title_reference>credits</title_reference> class set. (This is actually not
438 about credits but just for ensuring that the class attribute
439 doesn't get stripped away.)</paragraph>
440 </field_body>
441 </field>
442 </field_list>
443 </section>
444 <section ids="option-lists" names="option\ lists">
445 <title auto="1" refid="toc-entry-12"><generated classes="sectnum">2.6 </generated>Option Lists</title>
446 <paragraph>For listing command-line options:</paragraph>
447 <option_list>
448 <option_list_item>
449 <option_group>
450 <option>
451 <option_string>-a</option_string>
452 </option>
453 </option_group>
454 <description>
455 <paragraph>command-line option "a"</paragraph>
456 </description>
457 </option_list_item>
458 <option_list_item>
459 <option_group>
460 <option>
461 <option_string>-b</option_string>
462 <option_argument delimiter=" ">file</option_argument>
463 </option>
464 </option_group>
465 <description>
466 <paragraph>options can have arguments
467 and long descriptions</paragraph>
468 </description>
469 </option_list_item>
470 <option_list_item>
471 <option_group>
472 <option>
473 <option_string>--long</option_string>
474 </option>
475 </option_group>
476 <description>
477 <paragraph>options can be long also</paragraph>
478 </description>
479 </option_list_item>
480 <option_list_item>
481 <option_group>
482 <option>
483 <option_string>--input</option_string>
484 <option_argument delimiter="=">file</option_argument>
485 </option>
486 </option_group>
487 <description>
488 <paragraph>long options can also have
489 arguments</paragraph>
490 </description>
491 </option_list_item>
492 <option_list_item>
493 <option_group>
494 <option>
495 <option_string>--very-long-option</option_string>
496 </option>
497 </option_group>
498 <description>
499 <paragraph>The description can also start on the next line.</paragraph>
500 <paragraph>The description may contain multiple body elements,
501 regardless of where it starts.</paragraph>
502 </description>
503 </option_list_item>
504 <option_list_item>
505 <option_group>
506 <option>
507 <option_string>-x</option_string>
508 </option>
509 <option>
510 <option_string>-y</option_string>
511 </option>
512 <option>
513 <option_string>-z</option_string>
514 </option>
515 </option_group>
516 <description>
517 <paragraph>Multiple options are an "option group".</paragraph>
518 </description>
519 </option_list_item>
520 <option_list_item>
521 <option_group>
522 <option>
523 <option_string>-v</option_string>
524 </option>
525 <option>
526 <option_string>--verbose</option_string>
527 </option>
528 </option_group>
529 <description>
530 <paragraph>Commonly-seen: short & long options.</paragraph>
531 </description>
532 </option_list_item>
533 <option_list_item>
534 <option_group>
535 <option>
536 <option_string>-1</option_string>
537 <option_argument delimiter=" ">file</option_argument>
538 </option>
539 <option>
540 <option_string>--one</option_string>
541 <option_argument delimiter="=">file</option_argument>
542 </option>
543 <option>
544 <option_string>--two</option_string>
545 <option_argument delimiter=" ">file</option_argument>
546 </option>
547 </option_group>
548 <description>
549 <paragraph>Multiple options with arguments.</paragraph>
550 </description>
551 </option_list_item>
552 <option_list_item>
553 <option_group>
554 <option>
555 <option_string>/V</option_string>
556 </option>
557 </option_group>
558 <description>
559 <paragraph>DOS/VMS-style options too</paragraph>
560 </description>
561 </option_list_item>
562 </option_list>
563 <paragraph>There must be at least two spaces between the option and the
564 description.</paragraph>
565 </section>
566 <section ids="literal-blocks" names="literal\ blocks">
567 <title auto="1" refid="toc-entry-13"><generated classes="sectnum">2.7 </generated>Literal Blocks</title>
568 <paragraph>Literal blocks are indicated with a double-colon ("::") at the end of
569 the preceding paragraph (over there <literal>--></literal>). They can be indented:</paragraph>
570 <literal_block xml:space="preserve">if literal_block:
571 text = 'is left as-is'
572 spaces_and_linebreaks = 'are preserved'
573 markup_processing = None</literal_block>
574 <paragraph>Or they can be quoted without indentation:</paragraph>
575 <literal_block xml:space="preserve">>> Great idea!
576 >
577 > Why didn't I think of that?</literal_block>
578 </section>
579 <section ids="line-blocks" names="line\ blocks">
580 <title auto="1" refid="toc-entry-14"><generated classes="sectnum">2.8 </generated>Line Blocks</title>
581 <paragraph>This section tests line blocks. Line blocks are body elements which
582 consist of lines and other line blocks. Nested line blocks cause
583 indentation.</paragraph>
584 <line_block>
585 <line>This is a line block. It ends with a blank line.</line>
586 <line_block>
587 <line>New lines begin with a vertical bar ("|").</line>
588 <line>Line breaks and initial indent are significant, and preserved.</line>
589 <line_block>
590 <line>Continuation lines are also possible. A long line that is intended
591 to wrap should begin with a space in place of the vertical bar.</line>
592 </line_block>
593 <line>The left edge of a continuation line need not be aligned with
594 the left edge of the text above it.</line>
595 </line_block>
596 </line_block>
597 <line_block>
598 <line>This is a second line block.</line>
599 <line></line>
600 <line>Blank lines are permitted internally, but they must begin with a "|".</line>
601 </line_block>
602 <paragraph>Another line block, surrounded by paragraphs:</paragraph>
603 <line_block>
604 <line>And it's no good waiting by the window</line>
605 <line>It's no good waiting for the sun</line>
606 <line>Please believe me, the things you dream of</line>
607 <line>They don't fall in the lap of no-one</line>
608 </line_block>
609 <paragraph>Take it away, Eric the Orchestra Leader!</paragraph>
610 <block_quote>
611 <line_block>
612 <line>A one, two, a one two three four</line>
613 <line></line>
614 <line>Half a bee, philosophically,</line>
615 <line_block>
616 <line>must, <emphasis>ipso facto</emphasis>, half not be.</line>
617 </line_block>
618 <line>But half the bee has got to be,</line>
619 <line_block>
620 <line><emphasis>vis a vis</emphasis> its entity. D'you see?</line>
621 <line></line>
622 </line_block>
623 <line>But can a bee be said to be</line>
624 <line_block>
625 <line>or not to be an entire bee,</line>
626 <line_block>
627 <line>when half the bee is not a bee,</line>
628 <line_block>
629 <line>due to some ancient injury?</line>
630 <line></line>
631 </line_block>
632 </line_block>
633 </line_block>
634 <line>Singing...</line>
635 </line_block>
636 </block_quote>
637 <paragraph>A line block, like the following poem by Christian Morgenstern, can
638 also be centre-aligned:</paragraph>
639 <line_block classes="language-de align-center">
640 <line><strong>Die Trichter</strong></line>
641 <line></line>
642 <line>Zwei Trichter wandeln durch die Nacht.</line>
643 <line>Durch ihres Rumpfs verengten Schacht</line>
644 <line>fließt weißes Mondlicht</line>
645 <line>still und heiter</line>
646 <line>auf ihren</line>
647 <line>Waldweg</line>
648 <line>u. s.</line>
649 <line>w.</line>
650 <line></line>
651 </line_block>
652 </section>
653 <section ids="block-quotes" names="block\ quotes">
654 <title auto="1" refid="toc-entry-15"><generated classes="sectnum">2.9 </generated>Block Quotes</title>
655 <paragraph>Block quotes consist of indented body elements:</paragraph>
656 <block_quote>
657 <paragraph>My theory by A. Elk. Brackets Miss, brackets. This theory goes
658 as follows and begins now. All brontosauruses are thin at one
659 end, much much thicker in the middle and then thin again at the
660 far end. That is my theory, it is mine, and belongs to me and I
661 own it, and what it is too.</paragraph>
662 <attribution>Anne Elk (Miss)</attribution>
663 </block_quote>
664 <paragraph>The language of a quote (like any other object) can be specified by
665 a class attribute:</paragraph>
666 <comment xml:space="preserve"></comment>
667 <block_quote classes="language-fr">
668 <paragraph>ReStructuredText est un langage de balisage léger utilisé
669 notamment dans la documentation du langage Python.</paragraph>
670 </block_quote>
671 </section>
672 <section ids="doctest-blocks" names="doctest\ blocks">
673 <title auto="1" refid="toc-entry-16"><generated classes="sectnum">2.10 </generated>Doctest Blocks</title>
674 <doctest_block xml:space="preserve">>>> print 'Python-specific usage examples; begun with ">>>"'
675 Python-specific usage examples; begun with ">>>"
676 >>> print '(cut and pasted from interactive Python sessions)'
677 (cut and pasted from interactive Python sessions)</doctest_block>
678 </section>
679 <section ids="footnotes" names="footnotes">
680 <title auto="1" refid="toc-entry-17"><generated classes="sectnum">2.11 </generated>Footnotes</title>
681 <footnote backrefs="footnote-reference-1 footnote-reference-5 footnote-reference-9" ids="footnote-1" names="1">
682 <label>1</label>
683 <paragraph>A footnote contains body elements, consistently indented by at
684 least 3 spaces.</paragraph>
685 <paragraph>This is the footnote's second paragraph.</paragraph>
686 </footnote>
687 <footnote auto="1" backrefs="footnote-reference-3 footnote-reference-6" ids="label" names="label">
688 <label>2</label>
689 <paragraph>Footnotes may be numbered, either manually (as in <footnote_reference ids="footnote-reference-5" refid="footnote-1">1</footnote_reference>) or
690 automatically using a "#"-prefixed label. This footnote has a
691 label so it can be referred to from multiple places, both as a
692 footnote reference (<footnote_reference auto="1" ids="footnote-reference-6" refid="label">2</footnote_reference>) and as a <reference anonymous="1" name="hyperlink reference" refid="label">hyperlink reference</reference>.</paragraph>
693 <target anonymous="1" ids="target-3" refid="label"></target>
694 </footnote>
695 <footnote auto="1" backrefs="footnote-reference-2" ids="footnote-2" names="3">
696 <label>3</label>
697 <paragraph>This footnote is numbered automatically and anonymously using a
698 label of "#" only.</paragraph>
699 <paragraph>This is the second paragraph.</paragraph>
700 <paragraph>And this is the third paragraph.</paragraph>
701 </footnote>
702 <footnote auto="*" backrefs="footnote-reference-4" ids="footnote-3">
703 <label>*</label>
704 <paragraph>Footnotes may also use symbols, specified with a "*" label.
705 Here's a reference to the next footnote: <footnote_reference auto="*" ids="footnote-reference-7" refid="footnote-4">†</footnote_reference>.</paragraph>
706 </footnote>
707 <footnote auto="*" backrefs="footnote-reference-7" ids="footnote-4">
708 <label>†</label>
709 <paragraph>This footnote shows the next symbol in the sequence.</paragraph>
710 </footnote>
711 <footnote ids="footnote-5" names="4">
712 <label>4</label>
713 <paragraph>Here's an unreferenced footnote, with a reference to a
714 nonexistent footnote: <problematic ids="footnote-reference-8" refid="system-message-2">[5]_</problematic>.</paragraph>
715 </footnote>
716 </section>
717 <section ids="citations" names="citations">
718 <title auto="1" refid="toc-entry-18"><generated classes="sectnum">2.12 </generated>Citations</title>
719 <citation backrefs="citation-reference-1 citation-reference-2" ids="cit2002" names="cit2002">
720 <label>CIT2002</label>
721 <paragraph>Citations are text-labeled footnotes. They may be
722 rendered separately and differently from footnotes.</paragraph>
723 </citation>
724 <paragraph>Here's a reference to the above, <citation_reference ids="citation-reference-2" refid="cit2002">CIT2002</citation_reference>, and a <problematic ids="citation-reference-3" refid="system-message-3">[nonexistent]_</problematic>
725 citation.</paragraph>
726 <target refid="another-target"></target>
727 </section>
728 <section ids="targets another-target" names="targets another\ target">
729 <title auto="1" refid="toc-entry-19"><generated classes="sectnum">2.13 </generated>Targets</title>
730 <target refid="example"></target>
731 <paragraph ids="example" names="example">This paragraph is pointed to by the explicit "example" target. A
732 reference can be found under <reference name="Inline Markup" refid="inline-markup">Inline Markup</reference>, above. <reference name="Inline hyperlink targets" refid="inline-hyperlink-targets">Inline
733 hyperlink targets</reference> are also possible.</paragraph>
734 <paragraph>Section headers are implicit targets, referred to by name. See
735 <reference name="Targets" refid="targets">Targets</reference>, which is a subsection of <reference name="Body Elements" refid="body-elements">Body Elements</reference>.</paragraph>
736 <paragraph>Explicit external targets are interpolated into references such as
737 "<reference name="Python" refuri="http://www.python.org/">Python</reference> <footnote_reference auto="1" ids="footnote-reference-11" refid="footnote-6">5</footnote_reference>".</paragraph>
738 <target ids="python" names="python" refuri="http://www.python.org/"></target>
739 <paragraph>Targets may be indirect and anonymous. Thus <reference anonymous="1" name="this phrase" refid="targets">this phrase</reference> may also
740 refer to the <reference name="Targets" refid="targets">Targets</reference> section.</paragraph>
741 <target anonymous="1" ids="target-4" refid="targets"></target>
742 <paragraph>Here's a <problematic ids="problematic-2" refid="system-message-4">`hyperlink reference without a target`_</problematic>, which generates an
743 error.</paragraph>
744 <section dupnames="duplicate\ target\ names" ids="duplicate-target-names">
745 <title auto="1" refid="toc-entry-20"><generated classes="sectnum">2.13.1 </generated>Duplicate Target Names</title>
746 <paragraph>Duplicate names in section headers or other implicit targets will
747 generate "info" (level-1) system messages. Duplicate names in
748 explicit targets will generate "warning" (level-2) system messages.</paragraph>
749 </section>
750 <section dupnames="duplicate\ target\ names" ids="duplicate-target-names-1">
751 <title auto="1" refid="toc-entry-21"><generated classes="sectnum">2.13.2 </generated>Duplicate Target Names</title>
752 <system_message backrefs="duplicate-target-names-1" level="1" line="434" source="functional/input/data/standard.txt" type="INFO">
753 <paragraph>Duplicate implicit target name: "duplicate target names".</paragraph>
754 </system_message>
755 <paragraph>Since there are two "Duplicate Target Names" section headers, we
756 cannot uniquely refer to either of them by name. If we try to (like
757 this: <problematic ids="problematic-3" refid="system-message-5">`Duplicate Target Names`_</problematic>), an error is generated.</paragraph>
758 </section>
759 </section>
760 <section ids="directives" names="directives">
761 <title auto="1" refid="toc-entry-22"><generated classes="sectnum">2.14 </generated>Directives</title>
762 <topic classes="contents local" ids="contents" names="contents">
763 <bullet_list classes="auto-toc">
764 <list_item>
765 <paragraph><reference ids="toc-entry-43" refid="document-parts"><generated classes="sectnum">2.14.1 </generated>Document Parts</reference></paragraph>
766 </list_item>
767 <list_item>
768 <paragraph><reference ids="toc-entry-44" refid="images-and-figures"><generated classes="sectnum">2.14.2 </generated>Images and Figures</reference></paragraph>
769 </list_item>
770 <list_item>
771 <paragraph><reference ids="toc-entry-45" refid="tables"><generated classes="sectnum">2.14.3 </generated>Tables</reference></paragraph>
772 </list_item>
773 <list_item>
774 <paragraph><reference ids="toc-entry-46" refid="admonitions"><generated classes="sectnum">2.14.4 </generated>Admonitions</reference></paragraph>
775 </list_item>
776 <list_item>
777 <paragraph><reference ids="toc-entry-47" refid="topics-sidebars-and-rubrics"><generated classes="sectnum">2.14.5 </generated>Topics, Sidebars, and Rubrics</reference></paragraph>
778 </list_item>
779 <list_item>
780 <paragraph><reference ids="toc-entry-48" refid="target-footnotes"><generated classes="sectnum">2.14.6 </generated>Target Footnotes</reference></paragraph>
781 </list_item>
782 <list_item>
783 <paragraph><reference ids="toc-entry-49" refid="replacement-text"><generated classes="sectnum">2.14.7 </generated>Replacement Text</reference></paragraph>
784 </list_item>
785 <list_item>
786 <paragraph><reference ids="toc-entry-50" refid="compound-paragraph"><generated classes="sectnum">2.14.8 </generated>Compound Paragraph</reference></paragraph>
787 </list_item>
788 <list_item>
789 <paragraph><reference ids="toc-entry-51" refid="parsed-literal-blocks"><generated classes="sectnum">2.14.9 </generated>Parsed Literal Blocks</reference></paragraph>
790 </list_item>
791 <list_item>
792 <paragraph><reference ids="toc-entry-52" refid="code"><generated classes="sectnum">2.14.10 </generated>Code</reference></paragraph>
793 </list_item>
794 <list_item>
795 <paragraph><reference ids="toc-entry-53" refid="meta"><generated classes="sectnum">2.14.11 </generated>Meta</reference></paragraph>
796 </list_item>
797 </bullet_list>
798 </topic>
799 <paragraph>These are just a sample of the many reStructuredText Directives. For
800 others, please see <reference anonymous="1" name="reStructuredText Directives" refuri="https://docutils.sourceforge.io/docs/ref/rst/directives.html">reStructuredText Directives</reference> <footnote_reference auto="1" ids="footnote-reference-16" refid="footnote-9">8</footnote_reference>.</paragraph>
801 <target anonymous="1" ids="target-5" refuri="https://docutils.sourceforge.io/docs/ref/rst/directives.html"></target>
802 <section ids="document-parts" names="document\ parts">
803 <title auto="1" refid="toc-entry-43"><generated classes="sectnum">2.14.1 </generated>Document Parts</title>
804 <paragraph>An example of the "contents" directive can be seen above this section
805 (a local, untitled table of <reference name="contents" refid="contents">contents</reference>) and at the beginning of the
806 document (a document-wide <reference name="table of contents" refid="table-of-contents">table of contents</reference>).</paragraph>
807 </section>
808 <section ids="images-and-figures" names="images\ and\ figures">
809 <title auto="1" refid="toc-entry-44"><generated classes="sectnum">2.14.2 </generated>Images and Figures</title>
810 <paragraph>An image directive (also clickable -- a hyperlink reference):</paragraph>
811 <reference name="directives" refid="directives"><image classes="class1 class2" uri="../../../docs/user/rst/images/title.png" width="70%"></image></reference>
812 <paragraph>Image with multiple IDs:</paragraph>
813 <target refid="image-target-1"></target>
814 <target refid="image-target-2"></target>
815 <target refid="image-target-3"></target>
816 <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/biohazard.png"></image>
817 <paragraph>A centered image:</paragraph>
818 <image align="center" uri="../../../docs/user/rst/images/biohazard.png"></image>
819 <paragraph>A left-aligned image:</paragraph>
820 <image align="left" uri="../../../docs/user/rst/images/biohazard.png"></image>
821 <paragraph>This paragraph might flow around the image.
822 The specific behavior depends upon the style sheet and
823 the browser or rendering software used.</paragraph>
824 <paragraph>A right-aligned image:</paragraph>
825 <image align="right" uri="../../../docs/user/rst/images/biohazard.png"></image>
826 <paragraph>This paragraph might flow around the image.
827 The specific behavior depends upon the style sheet and
828 the browser or rendering software used.</paragraph>
829 <paragraph>For inline images see <reference name="Substitution Definitions" refid="substitution-definitions">Substitution Definitions</reference>.</paragraph>
830 <paragraph>Image size:</paragraph>
831 <paragraph>An image 2 em wide:</paragraph>
832 <image uri="../../../docs/user/rst/images/biohazard.png" width="2em"></image>
833 <paragraph>An image 2 cm wide and 15 pixel high:</paragraph>
834 <image height="15px" uri="../../../docs/user/rst/images/biohazard.png" width="2cm"></image>
835 <paragraph>Relative units allow adaption of the image to the screen or paper size.
836 An image occupying 50% of the line width:</paragraph>
837 <image uri="../../../docs/user/rst/images/title.png" width="50%"></image>
838 <paragraph>A <emphasis>figure</emphasis> is an image with a caption and/or a legend. With page-based output
839 media, figures might float to a different position if this helps the page
840 layout.</paragraph>
841 <figure classes="figclass1 figclass2">
842 <image alt="reStructuredText, the markup syntax" classes="class1 class2" uri="../../../docs/user/rst/images/title.png" width="258"></image>
843 <caption>Plaintext markup syntax and parser system.</caption>
844 <legend>
845 <table>
846 <tgroup cols="2">
847 <colspec colwidth="12"></colspec>
848 <colspec colwidth="47"></colspec>
849 <tbody>
850 <row>
851 <entry>
852 <paragraph>re</paragraph>
853 </entry>
854 <entry>
855 <paragraph>Revised, revisited, based on 're' module.</paragraph>
856 </entry>
857 </row>
858 <row>
859 <entry>
860 <paragraph>Structured</paragraph>
861 </entry>
862 <entry>
863 <paragraph>Structure-enhanced text, structuredtext.</paragraph>
864 </entry>
865 </row>
866 <row>
867 <entry>
868 <paragraph>Text</paragraph>
869 </entry>
870 <entry>
871 <paragraph>Well it is, isn't it?</paragraph>
872 </entry>
873 </row>
874 </tbody>
875 </tgroup>
876 </table>
877 <paragraph>This paragraph is also part of the legend.</paragraph>
878 </legend>
879 </figure>
880 <paragraph>A left-aligned figure, 70% wide:</paragraph>
881 <figure align="left" classes="figclass1 figclass2" width="70%">
882 <image alt="reStructuredText, the markup syntax" classes="class1 class2" uri="../../../docs/user/rst/images/biohazard.png" width="40px"></image>
883 <caption>This is the caption.</caption>
884 <legend>
885 <paragraph>This is the legend.</paragraph>
886 <paragraph>The legend may consist of several paragraphs.</paragraph>
887 </legend>
888 </figure>
889 <paragraph>This paragraph might flow around the figure.</paragraph>
890 <paragraph>The specific behavior depends upon the style sheet and the browser or
891 rendering software used.</paragraph>
892 <paragraph>A centered figure:</paragraph>
893 <figure align="center">
894 <image uri="../../../docs/user/rst/images/biohazard.png" width="40px"></image>
895 <caption>This is the caption.</caption>
896 <legend>
897 <paragraph>This is the legend.</paragraph>
898 <paragraph>The legend may consist of several paragraphs.</paragraph>
899 </legend>
900 </figure>
901 <paragraph>This paragraph might flow around the figure.</paragraph>
902 <paragraph>The specific behavior depends upon the style sheet and the browser or
903 rendering software used.</paragraph>
904 <paragraph>A right-aligned figure:</paragraph>
905 <figure align="right">
906 <image uri="../../../docs/user/rst/images/biohazard.png" width="40px"></image>
907 <caption>This is the caption.</caption>
908 <legend>
909 <paragraph>This is the legend.</paragraph>
910 <paragraph>The legend may consist of several paragraphs.</paragraph>
911 </legend>
912 </figure>
913 <paragraph>This paragraph might flow around the figure. The specific behavior depends
914 upon the style sheet and the browser or rendering software used.</paragraph>
915 </section>
916 <section ids="tables" names="tables">
917 <title auto="1" refid="toc-entry-45"><generated classes="sectnum">2.14.3 </generated>Tables</title>
918 <paragraph>Tables may be given titles and additional arguments with the <emphasis>table</emphasis>
919 directive:</paragraph>
920 <table align="left">
921 <title>left-aligned table</title>
922 <tgroup cols="2">
923 <colspec colwidth="5"></colspec>
924 <colspec colwidth="5"></colspec>
925 <thead>
926 <row>
927 <entry>
928 <paragraph>A</paragraph>
929 </entry>
930 <entry>
931 <paragraph>not A</paragraph>
932 </entry>
933 </row>
934 </thead>
935 <tbody>
936 <row>
937 <entry>
938 <paragraph>False</paragraph>
939 </entry>
940 <entry>
941 <paragraph>True</paragraph>
942 </entry>
943 </row>
944 <row>
945 <entry>
946 <paragraph>True</paragraph>
947 </entry>
948 <entry>
949 <paragraph>False</paragraph>
950 </entry>
951 </row>
952 </tbody>
953 </tgroup>
954 </table>
955 <table align="center">
956 <title>center-aligned table</title>
957 <tgroup cols="2">
958 <colspec colwidth="5"></colspec>
959 <colspec colwidth="5"></colspec>
960 <thead>
961 <row>
962 <entry>
963 <paragraph>A</paragraph>
964 </entry>
965 <entry>
966 <paragraph>not A</paragraph>
967 </entry>
968 </row>
969 </thead>
970 <tbody>
971 <row>
972 <entry>
973 <paragraph>False</paragraph>
974 </entry>
975 <entry>
976 <paragraph>True</paragraph>
977 </entry>
978 </row>
979 <row>
980 <entry>
981 <paragraph>True</paragraph>
982 </entry>
983 <entry>
984 <paragraph>False</paragraph>
985 </entry>
986 </row>
987 </tbody>
988 </tgroup>
989 </table>
990 <table align="right">
991 <title>right-aligned table</title>
992 <tgroup cols="2">
993 <colspec colwidth="5"></colspec>
994 <colspec colwidth="5"></colspec>
995 <thead>
996 <row>
997 <entry>
998 <paragraph>A</paragraph>
999 </entry>
1000 <entry>
1001 <paragraph>not A</paragraph>
1002 </entry>
1003 </row>
1004 </thead>
1005 <tbody>
1006 <row>
1007 <entry>
1008 <paragraph>False</paragraph>
1009 </entry>
1010 <entry>
1011 <paragraph>True</paragraph>
1012 </entry>
1013 </row>
1014 <row>
1015 <entry>
1016 <paragraph>True</paragraph>
1017 </entry>
1018 <entry>
1019 <paragraph>False</paragraph>
1020 </entry>
1021 </row>
1022 </tbody>
1023 </tgroup>
1024 </table>
1025 <paragraph>With the "widths" argument "auto" (or "class" value "colwidths-auto"),
1026 column widths are determined by the backend (if supported by the
1027 writer/backend).</paragraph>
1028 <target refid="target1"></target>
1029 <target refid="target2"></target>
1030 <table classes="colwidths-auto" ids="target2 target1" names="target2 target1">
1031 <tgroup cols="3">
1032 <colspec colwidth="7"></colspec>
1033 <colspec colwidth="7"></colspec>
1034 <colspec colwidth="10"></colspec>
1035 <thead>
1036 <row>
1037 <entry>
1038 <paragraph>A</paragraph>
1039 </entry>
1040 <entry>
1041 <paragraph>B</paragraph>
1042 </entry>
1043 <entry>
1044 <paragraph>A or B</paragraph>
1045 </entry>
1046 </row>
1047 </thead>
1048 <tbody>
1049 <row>
1050 <entry>
1051 <paragraph>False</paragraph>
1052 </entry>
1053 <entry>
1054 <paragraph>False</paragraph>
1055 </entry>
1056 <entry>
1057 <paragraph>False</paragraph>
1058 </entry>
1059 </row>
1060 <row>
1061 <entry>
1062 <paragraph>True</paragraph>
1063 </entry>
1064 <entry>
1065 <paragraph>False</paragraph>
1066 </entry>
1067 <entry>
1068 <paragraph>True</paragraph>
1069 </entry>
1070 </row>
1071 <row>
1072 <entry>
1073 <paragraph>False</paragraph>
1074 </entry>
1075 <entry>
1076 <paragraph>True</paragraph>
1077 </entry>
1078 <entry>
1079 <paragraph>True</paragraph>
1080 </entry>
1081 </row>
1082 <row>
1083 <entry>
1084 <paragraph>True</paragraph>
1085 </entry>
1086 <entry>
1087 <paragraph>True</paragraph>
1088 </entry>
1089 <entry>
1090 <paragraph>True</paragraph>
1091 </entry>
1092 </row>
1093 </tbody>
1094 </tgroup>
1095 </table>
1096 </section>
1097 <section ids="admonitions" names="admonitions">
1098 <title auto="1" refid="toc-entry-46"><generated classes="sectnum">2.14.4 </generated>Admonitions</title>
1099 <attention>
1100 <paragraph>Directives at large.</paragraph>
1101 </attention>
1102 <caution>
1103 <paragraph>Don't take any wooden nickels.</paragraph>
1104 </caution>
1105 <danger>
1106 <paragraph>Mad scientist at work!</paragraph>
1107 </danger>
1108 <error>
1109 <paragraph>Does not compute.</paragraph>
1110 </error>
1111 <hint>
1112 <paragraph>It's bigger than a bread box.</paragraph>
1113 </hint>
1114 <important>
1115 <bullet_list bullet="-">
1116 <list_item>
1117 <paragraph>Wash behind your ears.</paragraph>
1118 </list_item>
1119 <list_item>
1120 <paragraph>Clean up your room.</paragraph>
1121 </list_item>
1122 <list_item>
1123 <paragraph>Call your mother.</paragraph>
1124 </list_item>
1125 <list_item>
1126 <paragraph>Back up your data.</paragraph>
1127 </list_item>
1128 </bullet_list>
1129 </important>
1130 <note>
1131 <paragraph>This is a note.</paragraph>
1132 </note>
1133 <tip>
1134 <paragraph>15% if the service is good.</paragraph>
1135 </tip>
1136 <warning>
1137 <paragraph>Strong prose may provoke extreme mental exertion.
1138 Reader discretion is strongly advised.</paragraph>
1139 </warning>
1140 <admonition classes="admonition-and-by-the-way">
1141 <title>And, by the way...</title>
1142 <paragraph>You can make up your own admonition too.</paragraph>
1143 <target ids="docutils" names="docutils" refuri="https://docutils.sourceforge.io/"></target>
1144 </admonition>
1145 </section>
1146 <section ids="topics-sidebars-and-rubrics" names="topics,\ sidebars,\ and\ rubrics">
1147 <title auto="1" refid="toc-entry-47"><generated classes="sectnum">2.14.5 </generated>Topics, Sidebars, and Rubrics</title>
1148 <paragraph><emphasis>Sidebars</emphasis> are like miniature, parallel documents.</paragraph>
1149 <sidebar>
1150 <title>Optional Sidebar Title</title>
1151 <subtitle>Optional Subtitle</subtitle>
1152 <paragraph>This is a sidebar. It is for text outside the flow of the main
1153 text.</paragraph>
1154 <rubric>This is a rubric inside a sidebar</rubric>
1155 <paragraph>Sidebars often appear beside the main text with a border and a different
1156 background or font color.</paragraph>
1157 </sidebar>
1158 <paragraph>A <emphasis>topic</emphasis> is like a block quote with a title, or a self-contained section
1159 with no subsections.</paragraph>
1160 <topic>
1161 <title>Topic Title</title>
1162 <paragraph>This is a topic.</paragraph>
1163 </topic>
1164 <paragraph>A <emphasis>rubric</emphasis> is like an informal heading that doesn't correspond to the
1165 document's structure. It is typically highlighted in red (hence the name).</paragraph>
1166 <rubric>This is a rubric</rubric>
1167 <paragraph>Topics and rubrics can be used at places where a <reference name="section title" refid="section-title">section title</reference> is not
1168 allowed (e.g. inside a directive).</paragraph>
1169 </section>
1170 <section ids="target-footnotes" names="target\ footnotes">
1171 <title auto="1" refid="toc-entry-48"><generated classes="sectnum">2.14.6 </generated>Target Footnotes</title>
1172 <footnote auto="1" backrefs="footnote-reference-10 footnote-reference-11 footnote-reference-12 footnote-reference-14" ids="footnote-6" names="TARGET_NOTE:\ footnote-6">
1173 <label>5</label>
1174 <paragraph><reference refuri="http://www.python.org/">http://www.python.org/</reference></paragraph>
1175 </footnote>
1176 <footnote auto="1" backrefs="footnote-reference-13" ids="footnote-7" names="TARGET_NOTE:\ footnote-7">
1177 <label>6</label>
1178 <paragraph><reference refuri="http://pygments.org/">http://pygments.org/</reference></paragraph>
1179 </footnote>
1180 <footnote auto="1" backrefs="footnote-reference-15" ids="footnote-8" names="TARGET_NOTE:\ footnote-8">
1181 <label>7</label>
1182 <paragraph><reference refuri="https://docutils.sourceforge.io/">https://docutils.sourceforge.io/</reference></paragraph>
1183 </footnote>
1184 <footnote auto="1" backrefs="footnote-reference-16" ids="footnote-9" names="TARGET_NOTE:\ footnote-9">
1185 <label>8</label>
1186 <paragraph><reference refuri="https://docutils.sourceforge.io/docs/ref/rst/directives.html">https://docutils.sourceforge.io/docs/ref/rst/directives.html</reference></paragraph>
1187 </footnote>
1188 <footnote auto="1" backrefs="footnote-reference-17" ids="footnote-10" names="TARGET_NOTE:\ footnote-10">
1189 <label>9</label>
1190 <paragraph><reference refuri="https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata">https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata</reference></paragraph>
1191 </footnote>
1192 </section>
1193 <section ids="replacement-text" names="replacement\ text">
1194 <title auto="1" refid="toc-entry-49"><generated classes="sectnum">2.14.7 </generated>Replacement Text</title>
1195 <paragraph>I recommend you try <reference refuri="http://www.python.org/">Python, <emphasis>the</emphasis> best language around</reference> <footnote_reference auto="1" ids="footnote-reference-12" refid="footnote-6">5</footnote_reference>.</paragraph>
1196 <substitution_definition names="Python">Python, <emphasis>the</emphasis> best language around</substitution_definition>
1197 </section>
1198 <section ids="compound-paragraph" names="compound\ paragraph">
1199 <title auto="1" refid="toc-entry-50"><generated classes="sectnum">2.14.8 </generated>Compound Paragraph</title>
1200 <paragraph>The <emphasis>compound</emphasis> directive is used to create a "compound paragraph", which
1201 is a single logical paragraph containing multiple physical body
1202 elements. For example:</paragraph>
1203 <compound>
1204 <paragraph>The 'rm' command is very dangerous. If you are logged
1205 in as root and enter</paragraph>
1206 <literal_block xml:space="preserve">cd /
1207 rm -rf *</literal_block>
1208 <paragraph>you will erase the entire contents of your file system.</paragraph>
1209 </compound>
1210 <paragraph>Test the handling and display of compound paragraphs:</paragraph>
1211 <compound classes="some-class">
1212 <paragraph>Compound 2, paragraph 1,</paragraph>
1213 <paragraph>compound 2, paragraph 2,</paragraph>
1214 <bullet_list bullet="*">
1215 <list_item>
1216 <paragraph>list item 1,</paragraph>
1217 </list_item>
1218 <list_item>
1219 <paragraph>list item 2,</paragraph>
1220 </list_item>
1221 </bullet_list>
1222 <paragraph>compound 2, paragraph 3.</paragraph>
1223 </compound>
1224 <compound>
1225 <paragraph>Compound 3, only consisting of one paragraph.</paragraph>
1226 </compound>
1227 <compound>
1228 <literal_block xml:space="preserve">Compound 4.
1229 This one starts with a literal block.</literal_block>
1230 <paragraph>Compound 4, paragraph following the literal block.</paragraph>
1231 </compound>
1232 <paragraph>Now something <emphasis>really</emphasis> perverted -- a nested compound block. This is
1233 just to test that it works at all; the results don't have to be
1234 meaningful.</paragraph>
1235 <compound>
1236 <paragraph>Compound 5, block 1 (a paragraph).</paragraph>
1237 <compound>
1238 <paragraph>Compound 6 is block 2 in compound 5.</paragraph>
1239 <paragraph>Compound 6, another paragraph.</paragraph>
1240 </compound>
1241 <paragraph>Compound 5, block 3 (a paragraph).</paragraph>
1242 </compound>
1243 <compound>
1244 <paragraph>Compound 7, tests the inclusion of various block-level
1245 elements in one logical paragraph. First a table,</paragraph>
1246 <table>
1247 <tgroup cols="3">
1248 <colspec colwidth="20"></colspec>
1249 <colspec colwidth="20"></colspec>
1250 <colspec colwidth="20"></colspec>
1251 <tbody>
1252 <row>
1253 <entry>
1254 <paragraph>Left cell, first
1255 paragraph.</paragraph>
1256 <paragraph>Left cell, second
1257 paragraph.</paragraph>
1258 </entry>
1259 <entry>
1260 <paragraph>Middle cell,
1261 consisting of
1262 exactly one
1263 paragraph.</paragraph>
1264 </entry>
1265 <entry>
1266 <paragraph>Right cell.</paragraph>
1267 <paragraph>Paragraph 2.</paragraph>
1268 <paragraph>Paragraph 3.</paragraph>
1269 </entry>
1270 </row>
1271 </tbody>
1272 </tgroup>
1273 </table>
1274 <paragraph>followed by a paragraph. This physical paragraph is
1275 actually a continuation of the paragraph before the table. It is followed
1276 by</paragraph>
1277 <block_quote>
1278 <paragraph>a quote and</paragraph>
1279 </block_quote>
1280 <enumerated_list enumtype="arabic" prefix="" suffix=".">
1281 <list_item>
1282 <paragraph>an enumerated list,</paragraph>
1283 </list_item>
1284 </enumerated_list>
1285 <paragraph>a paragraph,</paragraph>
1286 <option_list>
1287 <option_list_item>
1288 <option_group>
1289 <option>
1290 <option_string>--an</option_string>
1291 </option>
1292 </option_group>
1293 <description>
1294 <paragraph>option list,</paragraph>
1295 </description>
1296 </option_list_item>
1297 </option_list>
1298 <paragraph>a paragraph,</paragraph>
1299 <field_list>
1300 <field>
1301 <field_name>a field</field_name>
1302 <field_body>
1303 <paragraph>list,</paragraph>
1304 </field_body>
1305 </field>
1306 </field_list>
1307 <paragraph>a paragraph,</paragraph>
1308 <definition_list>
1309 <definition_list_item>
1310 <term>a definition</term>
1311 <definition>
1312 <paragraph>list,</paragraph>
1313 </definition>
1314 </definition_list_item>
1315 </definition_list>
1316 <paragraph>a paragraph, an image:</paragraph>
1317 <image uri="../../../docs/user/rst/images/biohazard.png"></image>
1318 <paragraph>a paragraph,</paragraph>
1319 <line_block>
1320 <line>a line</line>
1321 <line>block,</line>
1322 </line_block>
1323 <paragraph>a paragraph followed by a comment,</paragraph>
1324 <comment xml:space="preserve">this is a comment</comment>
1325 <paragraph>a paragraph, a</paragraph>
1326 <note>
1327 <paragraph>with content</paragraph>
1328 </note>
1329 <paragraph>and the final paragraph of the compound 7.</paragraph>
1330 </compound>
1331 </section>
1332 <section ids="parsed-literal-blocks" names="parsed\ literal\ blocks">
1333 <title auto="1" refid="toc-entry-51"><generated classes="sectnum">2.14.9 </generated>Parsed Literal Blocks</title>
1334 <literal_block xml:space="preserve">This is a parsed literal block.
1335 This line is indented. The next line is blank.
1337 Inline markup is supported, e.g. <emphasis>emphasis</emphasis>, <strong>strong</strong>, <literal>literal
1338 text</literal>, <subscript>sub-</subscript> and <superscript>super</superscript>scripts,
1339 inline formulas: <math>A = 2 \pi r^2</math>,
1340 footnotes <footnote_reference ids="footnote-reference-9" refid="footnote-1">1</footnote_reference>, <target ids="hyperlink-targets" names="hyperlink\ targets">hyperlink targets</target>, and <reference name="references" refuri="http://www.python.org/">references</reference><target ids="references" names="references" refuri="http://www.python.org/"></target>.</literal_block>
1341 </section>
1342 <section ids="code" names="code">
1343 <title auto="1" refid="toc-entry-52"><generated classes="sectnum">2.14.10 </generated>Code</title>
1344 <paragraph>Blocks of source code can be set with the <title_reference>code</title_reference> directive. If the code
1345 language is specified, the content is parsed and tagged by the <reference name="Pygments" refuri="http://pygments.org/">Pygments</reference> <footnote_reference auto="1" ids="footnote-reference-13" refid="footnote-7">6</footnote_reference>
1346 syntax highlighter and can be formatted with a style sheet. (Code parsing
1347 is turned off using the <literal>syntax-highlight</literal> config setting in the test
1348 conversions in order to get identical results with/without installed
1349 Pygments highlighter.)</paragraph>
1350 <literal_block classes="code python" xml:space="preserve">print 'This is Python code.'</literal_block>
1351 <paragraph>The <literal>:number-lines:</literal> option (with optional start value) generates line
1352 numbers:</paragraph>
1353 <literal_block classes="code python" xml:space="preserve"><inline classes="ln"> 8 </inline># print integers from 0 to 9:
1354 <inline classes="ln"> 9 </inline>for i in range(10):
1355 <inline classes="ln">10 </inline> print i</literal_block>
1356 <paragraph>For inline code snippets, there is the <title_reference>code</title_reference> role, which can be used
1357 directly (the code will not be parsed/tagged, as the language is not known)
1358 or as base for special code roles, e.g. the LaTeX code in the next
1359 paragraph.</paragraph>
1360 <paragraph>Docutils uses LaTeX syntax for math directives and roles:
1361 <literal classes="code tex">\alpha = f(x)</literal> prints <math>\alpha = f(x)</math>.</paragraph>
1362 <paragraph>The <literal>:code:</literal> option of the <title_reference>include</title_reference> directive sets the included content
1363 as a code block, here the rst file <literal>header_footer.txt</literal> with line numbers:</paragraph>
1364 <literal_block classes="code rst" source="functional/input/data/header_footer.txt" xml:space="preserve"><inline classes="ln">1 </inline>.. header:: Document header
1365 <inline classes="ln">2 </inline>.. footer:: Document footer</literal_block>
1366 <target ids="pygments" names="pygments" refuri="http://pygments.org/"></target>
1367 </section>
1368 <section ids="meta" names="meta">
1369 <title auto="1" refid="toc-entry-53"><generated classes="sectnum">2.14.11 </generated>Meta</title>
1370 <paragraph>The <reference anonymous="1" name="“meta” directive" refuri="https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata">“meta” directive</reference> <footnote_reference auto="1" ids="footnote-reference-17" refid="footnote-10">9</footnote_reference> is used to specify metadata to be stored in,
1371 e.g., HTML META tags or ODT file properties.</paragraph>
1372 <target anonymous="1" ids="target-6" refuri="https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata"></target>
1373 </section>
1374 </section>
1375 <section ids="substitution-definitions" names="substitution\ definitions">
1376 <title auto="1" refid="toc-entry-34"><generated classes="sectnum">2.15 </generated>Substitution Definitions</title>
1377 <paragraph>An inline image (<image alt="EXAMPLE" uri="../../../docs/user/rst/images/biohazard.png"></image>) example:</paragraph>
1378 <substitution_definition names="EXAMPLE"><image alt="EXAMPLE" uri="../../../docs/user/rst/images/biohazard.png"></image></substitution_definition>
1379 <paragraph>A Unicode example:</paragraph>
1380 <substitution_definition ltrim="1" names="heart" rtrim="1">♥</substitution_definition>
1381 <paragraph>(Substitution definitions are not visible in the HTML source.)</paragraph>
1382 </section>
1383 <section ids="comments" names="comments">
1384 <title auto="1" refid="toc-entry-35"><generated classes="sectnum">2.16 </generated>Comments</title>
1385 <paragraph>Here's one:</paragraph>
1386 <comment xml:space="preserve">Comments begin with two dots and a space. Anything may
1387 follow, except for the syntax of footnotes, hyperlink
1388 targets, directives, or substitution definitions.
1390 Double-dashes -- "--" -- must be escaped somehow in HTML output.
1392 Comments may contain non-ASCII characters: ä ö ü æ ø å</comment>
1393 <paragraph>(View the HTML source to see the comment.)</paragraph>
1394 </section>
1395 <section ids="raw-text" names="raw\ text">
1396 <title auto="1" refid="toc-entry-36"><generated classes="sectnum">2.17 </generated>Raw text</title>
1397 <paragraph>This does not necessarily look nice, because there may be missing white space.</paragraph>
1398 <paragraph>It's just there to freeze the behavior.</paragraph>
1399 <raw format="html latex" xml:space="preserve">A test.</raw>
1400 <raw format="html latex" xml:space="preserve">Second test.</raw>
1401 <raw classes="myclass" format="html latex" xml:space="preserve">Another test with myclass set.</raw>
1402 <paragraph>This is the <raw classes="myrawroleclass" format="html latex" xml:space="preserve">fourth test</raw> with myrawroleclass set.</paragraph>
1403 <raw format="html" xml:space="preserve">Fifth test in HTML.<br />Line two.</raw>
1404 <raw format="latex" xml:space="preserve">Fifth test in LaTeX.\\Line two.</raw>
1405 </section>
1406 <section ids="container" names="container">
1407 <title auto="1" refid="toc-entry-37"><generated classes="sectnum">2.18 </generated>Container</title>
1408 <container classes="custom">
1409 <paragraph>paragraph 1</paragraph>
1410 <paragraph>paragraph 2</paragraph>
1411 </container>
1412 </section>
1413 <section ids="colspanning-tables" names="colspanning\ tables">
1414 <title auto="1" refid="toc-entry-38"><generated classes="sectnum">2.19 </generated>Colspanning tables</title>
1415 <paragraph>This table has a cell spanning two columns:</paragraph>
1416 <table>
1417 <tgroup cols="3">
1418 <colspec colwidth="5"></colspec>
1419 <colspec colwidth="5"></colspec>
1420 <colspec colwidth="6"></colspec>
1421 <thead>
1422 <row>
1423 <entry morecols="1">
1424 <paragraph>Inputs</paragraph>
1425 </entry>
1426 <entry>
1427 <paragraph>Output</paragraph>
1428 </entry>
1429 </row>
1430 <row>
1431 <entry>
1432 <paragraph>A</paragraph>
1433 </entry>
1434 <entry>
1435 <paragraph>B</paragraph>
1436 </entry>
1437 <entry>
1438 <paragraph>A or B</paragraph>
1439 </entry>
1440 </row>
1441 </thead>
1442 <tbody>
1443 <row>
1444 <entry>
1445 <paragraph>False</paragraph>
1446 </entry>
1447 <entry>
1448 <paragraph>False</paragraph>
1449 </entry>
1450 <entry>
1451 <paragraph>False</paragraph>
1452 </entry>
1453 </row>
1454 <row>
1455 <entry>
1456 <paragraph>True</paragraph>
1457 </entry>
1458 <entry>
1459 <paragraph>False</paragraph>
1460 </entry>
1461 <entry>
1462 <paragraph>True</paragraph>
1463 </entry>
1464 </row>
1465 <row>
1466 <entry>
1467 <paragraph>False</paragraph>
1468 </entry>
1469 <entry>
1470 <paragraph>True</paragraph>
1471 </entry>
1472 <entry>
1473 <paragraph>True</paragraph>
1474 </entry>
1475 </row>
1476 <row>
1477 <entry>
1478 <paragraph>True</paragraph>
1479 </entry>
1480 <entry>
1481 <paragraph>True</paragraph>
1482 </entry>
1483 <entry>
1484 <paragraph>True</paragraph>
1485 </entry>
1486 </row>
1487 </tbody>
1488 </tgroup>
1489 </table>
1490 </section>
1491 <section ids="rowspanning-tables" names="rowspanning\ tables">
1492 <title auto="1" refid="toc-entry-39"><generated classes="sectnum">2.20 </generated>Rowspanning tables</title>
1493 <paragraph>Here's a table with cells spanning several rows:</paragraph>
1494 <table>
1495 <tgroup cols="3">
1496 <colspec colwidth="24"></colspec>
1497 <colspec colwidth="12"></colspec>
1498 <colspec colwidth="18"></colspec>
1499 <thead>
1500 <row>
1501 <entry>
1502 <paragraph>Header row, column 1
1503 (header rows optional)</paragraph>
1504 </entry>
1505 <entry>
1506 <paragraph>Header 2</paragraph>
1507 </entry>
1508 <entry>
1509 <paragraph>Header 3</paragraph>
1510 </entry>
1511 </row>
1512 </thead>
1513 <tbody>
1514 <row>
1515 <entry>
1516 <paragraph>body row 1, column 1</paragraph>
1517 </entry>
1518 <entry>
1519 <paragraph>column 2</paragraph>
1520 </entry>
1521 <entry>
1522 <paragraph>column 3</paragraph>
1523 </entry>
1524 </row>
1525 <row>
1526 <entry>
1527 <paragraph>body row 2</paragraph>
1528 </entry>
1529 <entry morerows="1">
1530 <paragraph>Cells may
1531 span rows.</paragraph>
1532 </entry>
1533 <entry morerows="1">
1534 <paragraph>Another
1535 rowspanning
1536 cell.</paragraph>
1537 </entry>
1538 </row>
1539 <row>
1540 <entry>
1541 <paragraph>body row 3</paragraph>
1542 </entry>
1543 </row>
1544 </tbody>
1545 </tgroup>
1546 </table>
1547 </section>
1548 <section ids="complex-tables" names="complex\ tables">
1549 <title auto="1" refid="toc-entry-40"><generated classes="sectnum">2.21 </generated>Complex tables</title>
1550 <paragraph>Here's a complex table, which should test all features.</paragraph>
1551 <table>
1552 <tgroup cols="4">
1553 <colspec colwidth="24"></colspec>
1554 <colspec colwidth="12"></colspec>
1555 <colspec colwidth="10"></colspec>
1556 <colspec colwidth="10"></colspec>
1557 <thead>
1558 <row>
1559 <entry>
1560 <paragraph>Header row, column 1
1561 (header rows optional)</paragraph>
1562 </entry>
1563 <entry>
1564 <paragraph>Header 2</paragraph>
1565 </entry>
1566 <entry>
1567 <paragraph>Header 3</paragraph>
1568 </entry>
1569 <entry>
1570 <paragraph>Header 4</paragraph>
1571 </entry>
1572 </row>
1573 </thead>
1574 <tbody>
1575 <row>
1576 <entry>
1577 <paragraph>body row 1, column 1</paragraph>
1578 </entry>
1579 <entry>
1580 <paragraph>column 2</paragraph>
1581 </entry>
1582 <entry>
1583 <paragraph>column 3</paragraph>
1584 </entry>
1585 <entry>
1586 <paragraph>column 4</paragraph>
1587 </entry>
1588 </row>
1589 <row>
1590 <entry>
1591 <paragraph>body row 2</paragraph>
1592 </entry>
1593 <entry morecols="2">
1594 <paragraph>Cells may span columns.</paragraph>
1595 </entry>
1596 </row>
1597 <row>
1598 <entry>
1599 <paragraph>body row 3</paragraph>
1600 </entry>
1601 <entry morerows="1">
1602 <paragraph>Cells may
1603 span rows.</paragraph>
1604 <paragraph>Paragraph.</paragraph>
1605 </entry>
1606 <entry morecols="1" morerows="1">
1607 <bullet_list bullet="-">
1608 <list_item>
1609 <paragraph>Table cells</paragraph>
1610 </list_item>
1611 <list_item>
1612 <paragraph>contain</paragraph>
1613 </list_item>
1614 <list_item>
1615 <paragraph>body elements.</paragraph>
1616 </list_item>
1617 </bullet_list>
1618 </entry>
1619 </row>
1620 <row>
1621 <entry>
1622 <paragraph>body row 4</paragraph>
1623 </entry>
1624 </row>
1625 <row>
1626 <entry>
1627 <paragraph>body row 5</paragraph>
1628 </entry>
1629 <entry morecols="1">
1630 <paragraph>Cells may also be
1631 empty: <literal>--></literal></paragraph>
1632 </entry>
1633 <entry>
1634 </entry>
1635 </row>
1636 </tbody>
1637 </tgroup>
1638 </table>
1639 </section>
1640 <section ids="list-tables" names="list\ tables">
1641 <title auto="1" refid="toc-entry-41"><generated classes="sectnum">2.22 </generated>List Tables</title>
1642 <paragraph>Here's a list table exercising all features:</paragraph>
1643 <table classes="colwidths-given test" width="95%">
1644 <title>list table with integral header</title>
1645 <tgroup cols="3">
1646 <colspec colwidth="10" stub="1"></colspec>
1647 <colspec colwidth="8"></colspec>
1648 <colspec colwidth="20"></colspec>
1649 <thead>
1650 <row>
1651 <entry>
1652 <paragraph>Treat</paragraph>
1653 </entry>
1654 <entry>
1655 <paragraph>Quantity</paragraph>
1656 </entry>
1657 <entry>
1658 <paragraph>Description</paragraph>
1659 </entry>
1660 </row>
1661 </thead>
1662 <tbody>
1663 <row>
1664 <entry>
1665 <paragraph>Albatross</paragraph>
1666 </entry>
1667 <entry>
1668 <paragraph>2.99</paragraph>
1669 </entry>
1670 <entry>
1671 <paragraph>On a stick!</paragraph>
1672 </entry>
1673 </row>
1674 <row>
1675 <entry>
1676 <paragraph>Crunchy Frog</paragraph>
1677 </entry>
1678 <entry>
1679 <paragraph>1.49</paragraph>
1680 </entry>
1681 <entry>
1682 <paragraph>If we took the bones out, it wouldn't be
1683 crunchy, now would it?</paragraph>
1684 </entry>
1685 </row>
1686 <row>
1687 <entry>
1688 <paragraph>Gannet Ripple</paragraph>
1689 </entry>
1690 <entry>
1691 <paragraph>1.99</paragraph>
1692 </entry>
1693 <entry>
1694 <paragraph>On a stick!</paragraph>
1695 </entry>
1696 </row>
1697 </tbody>
1698 </tgroup>
1699 </table>
1700 <table align="center" classes="colwidths-auto">
1701 <title>center aligned list table</title>
1702 <tgroup cols="2">
1703 <colspec colwidth="50"></colspec>
1704 <colspec colwidth="50"></colspec>
1705 <tbody>
1706 <row>
1707 <entry>
1708 <paragraph>Albatross</paragraph>
1709 </entry>
1710 <entry>
1711 <paragraph>2.99</paragraph>
1712 </entry>
1713 </row>
1714 <row>
1715 <entry>
1716 <paragraph>Crunchy Frog</paragraph>
1717 </entry>
1718 <entry>
1719 <paragraph>1.49</paragraph>
1720 </entry>
1721 </row>
1722 <row>
1723 <entry>
1724 <paragraph>Gannet Ripple</paragraph>
1725 </entry>
1726 <entry>
1727 <paragraph>1.99</paragraph>
1728 </entry>
1729 </row>
1730 </tbody>
1731 </tgroup>
1732 </table>
1733 </section>
1734 </section>
1735 <section ids="error-handling" names="error\ handling">
1736 <title auto="1" refid="toc-entry-42"><generated classes="sectnum">3 </generated>Error Handling</title>
1737 <paragraph>Any errors caught during processing will generate system messages.</paragraph>
1738 <paragraph>There should be five messages in the following, auto-generated
1739 section, "Docutils System Messages":</paragraph>
1740 <comment xml:space="preserve">section should be added by Docutils automatically</comment>
1741 </section>
1742 <section classes="system-messages">
1743 <title>Docutils System Messages</title>
1744 <system_message backrefs="problematic-1" ids="system-message-1" level="3" line="99" source="functional/input/data/standard.txt" type="ERROR">
1745 <paragraph>Undefined substitution referenced: "problematic".</paragraph>
1746 </system_message>
1747 <system_message backrefs="footnote-reference-8" ids="system-message-2" level="3" line="387" source="functional/input/data/standard.txt" type="ERROR">
1748 <paragraph>Unknown target name: "5".</paragraph>
1749 </system_message>
1750 <system_message backrefs="citation-reference-3" ids="system-message-3" level="3" line="396" source="functional/input/data/standard.txt" type="ERROR">
1751 <paragraph>Unknown target name: "nonexistent".</paragraph>
1752 </system_message>
1753 <system_message backrefs="problematic-2" ids="system-message-4" level="3" line="423" source="functional/input/data/standard.txt" type="ERROR">
1754 <paragraph>Unknown target name: "hyperlink reference without a target".</paragraph>
1755 </system_message>
1756 <system_message backrefs="problematic-3" ids="system-message-5" level="3" line="436" source="functional/input/data/standard.txt" type="ERROR">
1757 <paragraph>Duplicate target name, cannot be used as a unique reference: "duplicate target names".</paragraph>
1758 </system_message>
1759 <system_message level="1" line="159" source="functional/input/data/standard.txt" type="INFO">
1760 <paragraph>Hyperlink target "target" is not referenced.</paragraph>
1761 </system_message>
1762 <system_message level="1" line="401" source="functional/input/data/standard.txt" type="INFO">
1763 <paragraph>Hyperlink target "another-target" is not referenced.</paragraph>
1764 </system_message>
1765 <system_message level="1" line="471" source="functional/input/data/standard.txt" type="INFO">
1766 <paragraph>Hyperlink target "image-target-1" is not referenced.</paragraph>
1767 </system_message>
1768 <system_message level="1" line="472" source="functional/input/data/standard.txt" type="INFO">
1769 <paragraph>Hyperlink target "image-target-2" is not referenced.</paragraph>
1770 </system_message>
1771 <system_message level="1" line="473" source="functional/input/data/standard.txt" type="INFO">
1772 <paragraph>Hyperlink target "image-target-3" is not referenced.</paragraph>
1773 </system_message>
1774 <system_message level="1" line="636" source="functional/input/data/standard.txt" type="INFO">
1775 <paragraph>Hyperlink target "target1" is not referenced.</paragraph>
1776 </system_message>
1777 <system_message level="1" line="637" source="functional/input/data/standard.txt" type="INFO">
1778 <paragraph>Hyperlink target "target2" is not referenced.</paragraph>
1779 </system_message>
1780 <system_message level="1" line="682" source="functional/input/data/standard.txt" type="INFO">
1781 <paragraph>Hyperlink target "docutils" is not referenced.</paragraph>
1782 </system_message>
1783 <system_message level="1" line="848" source="functional/input/data/standard.txt" type="INFO">
1784 <paragraph>Hyperlink target "hyperlink targets" is not referenced.</paragraph>
1785 </system_message>
1786 </section>
1787 </document>