test/functional/input/data/standard.txt

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