sandbox/xml2rst/tests/synthetic/expected/standard_0_3_7.rst

   1 .. section-numbering::
   2
   3 ==============================
   4 reStructuredText Test Document
   5 ==============================
   6
   7 -----------------------------
   8 Examples of Syntax Constructs
   9 -----------------------------
  10
  11 :author: David Goodger
  12 :address: 123 Example Street
  13           Example, EX  Canada
  14           A1B 2C3
  15 :contact: goodger@users.sourceforge.net
  16 :authors: Me; Myself; I
  17 :organization: humankind
  18 :date: Now, or yesterday.  Or maybe even *before* yesterday.
  19 :status: This is a "work in progress"
  20 :revision: is managed by a version control system.
  21 :version: 1
  22 :copyright: This document has been placed in the public domain. You
  23             may do with it as you wish. You may copy, modify,
  24             redistribute, reattribute, sell, buy, rent, lease,
  25             destroy, or improve it, quote it at length, excerpt,
  26             incorporate, collate, fold, staple, or mutilate it, or do
  27             anything else to it that your or anyone else's heart
  28             desires.
  29 :field name: This is a "generic bibliographic field".
  30
  31 :field name "2": Generic bibliographic fields may contain multiple body elements.
  32
  33     Like this.
  34
  35
  36
  37 :Dedication:
  38
  39    For Docutils users & co-developers.
  40
  41 :Abstract:
  42
  43    This is a test document, containing at least one example of each
  44    reStructuredText construct.
  45
  46 .. This is a comment. Note how any initial comments are moved by
  47    transforms to after the document title, subtitle, and docinfo.
  48
  49 .. _doctitle:
  50
  51 .. Above is the document title, and below is the subtitle.
  52    They are transformed from section titles after parsing.
  53
  54 .. _subtitle:
  55
  56 .. bibliographic fields (which also require a transform):
  57
  58 .. contents:: Table of Contents
  59
  60
  61 Structural Elements
  62 ===================
  63
  64 Section Title
  65 -------------
  66
  67 That's it, the text just above this line.
  68
  69 Empty Section
  70 -------------
  71
  72 Transitions
  73 -----------
  74
  75 Here's a transition:
  76
  77 -----
  78
  79 It divides the section.  Transitions may also occur between sections:
  80
  81 -----
  82
  83
  84 Body Elements
  85 =============
  86
  87 Paragraphs
  88 ----------
  89
  90 A paragraph.
  91
  92 Inline Markup
  93 ~~~~~~~~~~~~~
  94
  95 Paragraphs contain text and may contain inline markup: *emphasis*,
  96 **strong emphasis**, ``inline literals``, standalone hyperlinks
  97 (http://www.python.org), external hyperlinks (Python_ ), internal
  98 cross-references (example_), external hyperlinks with embedded URIs
  99 (`Python web site <http://www.python.org>`__), footnote references
 100 (manually numbered [1]_, anonymous auto-numbered [#]_, labeled
 101 auto-numbered [#label]_, or symbolic [*]_), citation references
 102 ([CIT2002]_), substitution references (|EXAMPLE|), and _`inline
 103 hyperlink targets` (see Targets_ below for a reference back to here).
 104 Character-level inline markup is also possible (although exceedingly
 105 ugly!) in *re*\ ``Structured``\ *Text*.  Problems are indicated by
 106 |problematic| text (generated by processing errors; this one is
 107 intentional).  Here is a reference to the doctitle_ and the subtitle_.
 108
 109 The default role for interpreted text is `Title Reference`.  Here are
 110 some explicit interpreted text roles: a PEP reference (:PEP:`287`); an
 111 RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`;
 112 and explicit roles for *standard* **inline**
 113 ``markup``.
 114
 115 .. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
 116
 117 Let's test wrapping and whitespace significance in inline literals:
 118 ``This is an example of --inline-literal --text, --including some--
 119 strangely--hyphenated-words.  Adjust-the-width-of-your-browser-window
 120 to see how the text is wrapped.  -- ---- --------  Now note    the
 121 spacing    between the    words of    this sentence    (words
 122 should    be grouped    in pairs).``
 123
 124 If the ``--pep-references`` option was supplied, there should be a
 125 live link to PEP 258 here.
 126
 127 Bullet Lists
 128 ------------
 129
 130 - A bullet list
 131
 132   + Nested bullet list.
 133
 134   + Nested item 2.
 135
 136 - Item 2.
 137
 138   Paragraph 2 of item 2.
 139
 140   * Nested bullet list.
 141
 142   * Nested item 2.
 143
 144     - Third level.
 145
 146     - Item 2.
 147
 148   * Nested item 3.
 149
 150   * This nested list should be compacted by the HTML writer.
 151
 152     .. _target:
 153
 154     .. Even if this item contains a target and a comment.
 155
 156 Enumerated Lists
 157 ----------------
 158
 159 1. Arabic numerals.
 160
 161    a) lower alpha)
 162
 163       (i) (lower roman)
 164
 165           A. upper alpha.
 166
 167              I) upper roman)
 168
 169 2. Lists that don't start at 1:
 170
 171    3. Three
 172
 173    4. Four
 174
 175    C. C
 176
 177    D. D
 178
 179    i. iii
 180
 181    i. iv
 182
 183 Definition Lists
 184 ----------------
 185
 186 Term
 187     Definition
 188
 189 Term : classifier
 190     Definition paragraph 1.
 191
 192     Definition paragraph 2.
 193
 194 Term
 195     Definition
 196
 197 Term : classifier one : classifier two
 198     Definition
 199
 200 Field Lists
 201 -----------
 202
 203 :what: Field lists map field names to field bodies, like database
 204     records.  They are often part of an extension syntax.  They are
 205     an unambiguous variant of RFC 2822 fields.
 206
 207 :how arg1 arg2: The field marker is a colon, the field name, and a colon.
 208
 209     The field body may contain one or more body elements, indented
 210     relative to the field marker.
 211
 212 :credits:
 213     .. class:: credits
 214
 215     This paragraph has the `credits` class set.  (This is actually not
 216     about credits but just for ensuring that the class attribute
 217     doesn't get stripped away.)
 218
 219 Option Lists
 220 ------------
 221
 222 For listing command-line options:
 223
 224 -a
 225     command-line option "a"
 226
 227 -b file
 228     options can have arguments
 229     and long descriptions
 230
 231 --long
 232     options can be long also
 233
 234 --input=file
 235     long options can also have
 236     arguments
 237
 238 --very-long-option
 239     The description can also start on the next line.
 240
 241     The description may contain multiple body elements,
 242     regardless of where it starts.
 243
 244 -x, -y, -z
 245     Multiple options are an "option group".
 246
 247 -v, --verbose
 248     Commonly-seen: short & long options.
 249
 250 -1 file, --one=file, --two file
 251     Multiple options with arguments.
 252
 253 /V
 254     DOS/VMS-style options too
 255
 256
 257 There must be at least two spaces between the option and the
 258 description.
 259
 260 Literal Blocks
 261 --------------
 262
 263 Literal blocks are indicated with a double-colon ("::") at the end of
 264 the preceding paragraph (over there ``-->``).  They can be indented:
 265
 266 ::
 267
 268     if literal_block:
 269         text = 'is left as-is'
 270         spaces_and_linebreaks = 'are preserved'
 271         markup_processing = None
 272
 273 Or they can be quoted without indentation:
 274
 275 ::
 276
 277 >> Great idea!
 278 >
 279 > Why didn't I think of that?
 280
 281 Line Blocks
 282 -----------
 283
 284 This section tests line blocks.  Line blocks are body elements which
 285 consist of lines and other line blocks.  Nested line blocks cause
 286 indentation.
 287
 288 | This is a line block.  It ends with a blank line.
 289 |     New lines begin with a vertical bar ("|").
 290 |     Line breaks and initial indent are significant, and preserved.
 291 |         Continuation lines are also possible.  A long line that is intended
 292   to wrap should begin with a space in place of the vertical bar.
 293 |     The left edge of a continuation line need not be aligned with
 294   the left edge of the text above it.
 295
 296 | This is a second line block.
 297 |
 298 | Blank lines are permitted internally, but they must begin with a "|".
 299
 300 Another line block, surrounded by paragraphs:
 301
 302 | And it's no good waiting by the window
 303 | It's no good waiting for the sun
 304 | Please believe me, the things you dream of
 305 | They don't fall in the lap of no-one
 306
 307 Take it away, Eric the Orchestra Leader!
 308
 309     | A one, two, a one two three four
 310     |
 311     | Half a bee, philosophically,
 312     |     must, *ipso facto*, half not be.
 313     | But half the bee has got to be,
 314     |     *vis a vis* its entity.  D'you see?
 315     |
 316     | But can a bee be said to be
 317     |     or not to be an entire bee,
 318     |         when half the bee is not a bee,
 319     |             due to some ancient injury?
 320     |
 321     | Singing...
 322
 323 Block Quotes
 324 ------------
 325
 326 Block quotes consist of indented body elements:
 327
 328     My theory by A. Elk.  Brackets Miss, brackets.  This theory goes
 329     as follows and begins now.  All brontosauruses are thin at one
 330     end, much much thicker in the middle and then thin again at the
 331     far end.  That is my theory, it is mine, and belongs to me and I
 332     own it, and what it is too.
 333
 334     -- Anne Elk (Miss)
 335
 336 Doctest Blocks
 337 --------------
 338
 339
 340 >>> print 'Python-specific usage examples; begun with ">>>"'
 341 Python-specific usage examples; begun with ">>>"
 342 >>> print '(cut and pasted from interactive Python sessions)'
 343 (cut and pasted from interactive Python sessions)
 344
 345 Footnotes
 346 ---------
 347
 348 .. [1] A footnote contains body elements, consistently indented by at
 349    least 3 spaces.
 350
 351    This is the footnote's second paragraph.
 352
 353 .. [#label] Footnotes may be numbered, either manually (as in [1]_) or
 354    automatically using a "#"-prefixed label.  This footnote has a
 355    label so it can be referred to from multiple places, both as a
 356    footnote reference ([#label]_) and as a hyperlink reference
 357    (label_).
 358
 359 .. [#] This footnote is numbered automatically and anonymously using a
 360    label of "#" only.
 361
 362    This is the second paragraph.
 363
 364    And this is the third paragraph.
 365
 366 .. [*] Footnotes may also use symbols, specified with a "*" label.
 367    Here's a reference to the next footnote: [*]_.
 368
 369 .. [*] This footnote shows the next symbol in the sequence.
 370
 371 .. [4] Here's an unreferenced footnote, with a reference to a
 372    nonexistent footnote: [5]_.
 373
 374 Citations
 375 ---------
 376
 377 .. [CIT2002] Citations are text-labeled footnotes. They may be
 378    rendered separately and differently from footnotes.
 379
 380 Here's a reference to the above, [CIT2002]_, and a [nonexistent]_
 381 citation.
 382
 383 Targets
 384 -------
 385
 386
 387 .. _example:
 388
 389 This paragraph is pointed to by the explicit "example" target. A
 390 reference can be found under `Inline Markup`_, above. `Inline
 391 hyperlink targets`_ are also possible.
 392
 393 Section headers are implicit targets, referred to by name. See
 394 Targets_, which is a subsection of `Body Elements`_.
 395
 396 Explicit external targets are interpolated into references such as
 397 "Python_ ".
 398
 399 .. _python: http://www.python.org/
 400
 401 Targets may be indirect and anonymous.  Thus `this phrase`__ may also
 402 refer to the Targets_ section.
 403
 404 __ targets_
 405
 406 Here's a `hyperlink reference without a target`_, which generates an
 407 error.
 408
 409 And another phrase__  pointing to an anonymous hyperlink.
 410
 411 __ http://www.example.com/
 412
 413 Duplicate Target Names
 414 ~~~~~~~~~~~~~~~~~~~~~~
 415
 416 Duplicate names in section headers or other implicit targets will
 417 generate "info" (level-1) system messages.  Duplicate names in
 418 explicit targets will generate "warning" (level-2) system messages.
 419
 420 Duplicate Target Names
 421 ~~~~~~~~~~~~~~~~~~~~~~
 422
 423 Since there are two "Duplicate Target Names" section headers, we
 424 cannot uniquely refer to either of them by name.  If we try to (like
 425 this: `Duplicate Target Names`_), an error is generated.
 426
 427 Directives
 428 ----------
 429
 430 .. contents::
 431    :local:
 432
 433 These are just a sample of the many reStructuredText Directives.  For
 434 others, please see
 435 http://docutils.sourceforge.net/docs/ref/rst/directives.html.
 436
 437 Document Parts
 438 ~~~~~~~~~~~~~~
 439
 440 An example of the "contents" directive can be seen above this section
 441 (a local, untitled table of contents_) and at the beginning of the
 442 document (a document-wide `table of contents`_).
 443
 444 Images
 445 ~~~~~~
 446
 447 An image directive (also clickable -- a hyperlink reference):
 448
 449 .. image:: ../../../docs/user/rst/images/title.png
 450    :target: directives_
 451
 452
 453 .. image:: ../../../docs/user/rst/images/title.png
 454    :target: http://www.merten-home.de/
 455
 456 A figure directive:
 457
 458 .. figure:: ../../../docs/user/rst/images/title.png
 459    :alt: reStructuredText, the markup syntax
 460
 461    A figure is an image with a caption and/or a legend:
 462
 463    +------------+-----------------------------------------------+
 464    | re         | Revised, revisited, based on 're' module.     |
 465    +------------+-----------------------------------------------+
 466    | Structured | Structure-enhanced text, structuredtext.      |
 467    +------------+-----------------------------------------------+
 468    | Text       | Well it is, isn't it?                         |
 469    +------------+-----------------------------------------------+
 470
 471    This paragraph is also part of the legend.
 472
 473 Admonitions
 474 ~~~~~~~~~~~
 475
 476 .. attention:: Directives at large.
 477
 478 .. caution:: Don't take any wooden nickels.
 479
 480 .. danger:: Mad scientist at work!
 481
 482 .. error:: Does not compute.
 483
 484 .. hint:: It's bigger than a bread box.
 485
 486 .. important::
 487    - Wash behind your ears.
 488
 489    - Clean up your room.
 490
 491    - Call your mother.
 492
 493    - Back up your data.
 494
 495 .. note:: This is a note.
 496
 497 .. tip:: 15% if the service is good.
 498
 499 .. warning:: Strong prose may provoke extreme mental exertion.
 500    Reader discretion is strongly advised.
 501
 502 .. admonition:: And, by the way...
 503
 504    You can make up your own admonition too.
 505
 506 Topics, Sidebars, and Rubrics
 507 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 508
 509 .. sidebar:: Sidebar Title
 510    :subtitle: Optional Subtitle
 511
 512    This is a sidebar.  It is for text outside the flow of the main
 513    text.
 514
 515    .. rubric:: This is a rubric inside a sidebar
 516
 517    Sidebars often appears beside the main text with a border and
 518    background color.
 519
 520 .. topic:: Topic Title
 521
 522    This is a topic.
 523
 524 .. rubric:: This is a rubric
 525
 526 Target Footnotes
 527 ~~~~~~~~~~~~~~~~
 528
 529 .. target-notes::
 530
 531 Replacement Text
 532 ~~~~~~~~~~~~~~~~
 533
 534 I recommend you try Python, *the* best language around .
 535
 536 .. |Python| replace:: Python, *the* best language around
 537
 538 Compound Paragraph
 539 ~~~~~~~~~~~~~~~~~~
 540
 541 .. compound::
 542    :class: some-class
 543
 544    Compound 1, paragraph 1.
 545
 546    Compound 1, paragraph 2.
 547
 548    * Compound 1, list item one.
 549
 550    * Compound 1, list item two.
 551
 552 Another compound statement:
 553
 554 .. compound::
 555
 556    Compound 2, a literal block:
 557
 558    ::
 559
 560        Compound 2, literal.
 561
 562    Compound 2, this is a test.
 563
 564 .. compound::
 565
 566    Compound 3, only consisting of one paragraph.
 567
 568 .. compound::
 569
 570    ::
 571
 572        Compound 4.
 573        This one starts with a literal block.
 574
 575    Compound 4, a paragraph.
 576
 577 Now something *really* perverted -- a nested compound block.  In
 578 LaTeX, the following paragraphs should all be first-line indented:
 579
 580 .. compound::
 581
 582    Compound 5, block 1 (a paragraph).
 583
 584    .. compound::
 585
 586       Compound 6, block 2 in compound 5.
 587
 588       Compound 6, another paragraph.
 589
 590    Compound 5, block 3 (a paragraph).
 591
 592 .. compound::
 593
 594    Compound 7, with a table inside:
 595
 596    +--------------------+--------------------+--------------------+
 597    | Left cell, first   | Middle cell,       | Right cell.        |
 598    | paragraph.         | consisting of      |                    |
 599    |                    | exactly one        | Paragraph 2.       |
 600    | Left cell, second  | paragraph.         |                    |
 601    | paragraph.         |                    | Paragraph 3.       |
 602    +--------------------+--------------------+--------------------+
 603
 604    Compound 7, a paragraph after the table.
 605
 606    Compound 7, another paragraph.
 607
 608 Substitution Definitions
 609 ------------------------
 610
 611 An inline image (|EXAMPLE|) example:
 612
 613 .. |EXAMPLE| image:: ../../../docs/user/rst/images/biohazard.png
 614
 615
 616 (Substitution definitions are not visible in the HTML source.)
 617
 618 Comments
 619 --------
 620
 621 Here's one:
 622
 623 .. Comments begin with two dots and a space. Anything may
 624    follow, except for the syntax of footnotes, hyperlink
 625    targets, directives, or substitution definitions.
 626
 627    Double-dashes -- "--" -- must be escaped somehow in HTML output.
 628
 629 (View the HTML source to see the comment.)
 630
 631 Raw text
 632 --------
 633
 634 This does not necessarily look nice, because there may be missing white space.
 635
 636 It's just there to freeze the behavior.
 637
 638 .. raw:: html latex
 639
 640    A test.
 641
 642 .. raw:: html latex
 643
 644    Second test.
 645
 646 .. class:: myclass
 647
 648 .. raw:: html latex
 649
 650    Another test with myclass set.
 651
 652 This is the :RAW-ROLE:`fourth test` with myrawroleclass set.
 653
 654 .. raw:: html
 655
 656    Fifth test in HTML.<br />Line two.
 657
 658 .. raw:: latex
 659
 660    Fifth test in LaTeX.\\Line two.