docutils/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`); an abbreviation (:ab:`abb.`), an acronym
 125 (:ac:`reST`), code (:code:`print "hello world"`); a :sub:`subscript`;
 126 a :sup:`superscript` and explicit roles for :title:`Docutils`'
 127 :emphasis:`standard` :strong:`inline` :literal:`markup`.
 128
 129 .. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
 130
 131 Let's test wrapping and whitespace significance in inline literals:
 132 ``This is an example of --inline-literal --text, --including some--
 133 strangely--hyphenated-words.  Adjust-the-width-of-your-browser-window
 134 to see how the text is wrapped.  -- ---- --------  Now note    the
 135 spacing    between the    words of    this sentence    (words
 136 should    be grouped    in pairs).``
 137
 138 If the ``--pep-references`` option was supplied, there should be a
 139 live link to PEP 258 here.
 140
 141 Bullet Lists
 142 ------------
 143
 144 - A bullet list
 145
 146   + Nested bullet list.
 147   + Nested item 2.
 148
 149 - Item 2.
 150
 151   Paragraph 2 of item 2.
 152
 153   * Nested bullet list.
 154   * Nested item 2.
 155
 156     - Third level.
 157     - Item 2.
 158
 159   * Nested item 3.
 160
 161   * This nested list should be compacted by the HTML writer.
 162
 163     .. _target:
 164
 165     .. Even if this item contains a target and a comment.
 166
 167 Enumerated Lists
 168 ----------------
 169
 170 1. Arabic numerals.
 171
 172    a) lower alpha)
 173
 174       (i) (lower roman)
 175
 176           A. upper alpha.
 177
 178              I) upper roman)
 179
 180 2. Lists that don't start at 1:
 181
 182    3. Three
 183
 184    4. Four
 185
 186    C. C
 187
 188    D. D
 189
 190    iii. iii
 191
 192    iv. iv
 193
 194 Definition Lists
 195 ----------------
 196
 197 Term
 198     Definition
 199 Term : classifier
 200     Definition paragraph 1.
 201
 202     Definition paragraph 2.
 203 Term
 204     Definition
 205 Term : classifier one  :  classifier two
 206     Definition
 207
 208 Field Lists
 209 -----------
 210
 211 :what: Field lists map field names to field bodies, like database
 212        records.  They are often part of an extension syntax.  They are
 213        an unambiguous variant of RFC 2822 fields.
 214
 215 :how arg1 arg2:
 216
 217     The field marker is a colon, the field name, and a colon.
 218
 219     The field body may contain one or more body elements, indented
 220     relative to the field marker.
 221
 222 :credits:
 223
 224     .. class:: credits
 225
 226     This paragraph has the `credits` class set.  (This is actually not
 227     about credits but just for ensuring that the class attribute
 228     doesn't get stripped away.)
 229
 230 Option Lists
 231 ------------
 232
 233 For listing command-line options:
 234
 235 -a            command-line option "a"
 236 -b file       options can have arguments
 237               and long descriptions
 238 --long        options can be long also
 239 --input=file  long options can also have
 240               arguments
 241
 242 --very-long-option
 243               The description can also start on the next line.
 244
 245               The description may contain multiple body elements,
 246               regardless of where it starts.
 247
 248 -x, -y, -z    Multiple options are an "option group".
 249 -v, --verbose  Commonly-seen: short & long options.
 250 -1 file, --one=file, --two file
 251               Multiple options with arguments.
 252 /V            DOS/VMS-style options too
 253
 254 There must be at least two spaces between the option and the
 255 description.
 256
 257 Literal Blocks
 258 --------------
 259
 260 Literal blocks are indicated with a double-colon ("::") at the end of
 261 the preceding paragraph (over there ``-->``).  They can be indented::
 262
 263     if literal_block:
 264         text = 'is left as-is'
 265         spaces_and_linebreaks = 'are preserved'
 266         markup_processing = None
 267
 268 Or they can be quoted without indentation::
 269
 270 >> Great idea!
 271 >
 272 > Why didn't I think of that?
 273
 274 Line Blocks
 275 -----------
 276
 277 This section tests line blocks.  Line blocks are body elements which
 278 consist of lines and other line blocks.  Nested line blocks cause
 279 indentation.
 280
 281 | This is a line block.  It ends with a blank line.
 282 |     New lines begin with a vertical bar ("|").
 283 |     Line breaks and initial indent are significant, and preserved.
 284 |         Continuation lines are also possible.  A long line that is intended
 285           to wrap should begin with a space in place of the vertical bar.
 286 |     The left edge of a continuation line need not be aligned with
 287   the left edge of the text above it.
 288
 289 | This is a second line block.
 290 |
 291 | Blank lines are permitted internally, but they must begin with a "|".
 292
 293 Another line block, surrounded by paragraphs:
 294
 295 | And it's no good waiting by the window
 296 | It's no good waiting for the sun
 297 | Please believe me, the things you dream of
 298 | They don't fall in the lap of no-one
 299
 300 Take it away, Eric the Orchestra Leader!
 301
 302     | A one, two, a one two three four
 303     |
 304     | Half a bee, philosophically,
 305     |     must, *ipso facto*, half not be.
 306     | But half the bee has got to be,
 307     |     *vis a vis* its entity.  D'you see?
 308     |
 309     | But can a bee be said to be
 310     |     or not to be an entire bee,
 311     |         when half the bee is not a bee,
 312     |             due to some ancient injury?
 313     |
 314     | Singing...
 315
 316 A line block, like the following poem by Christian Morgenstern, can
 317 also be centre-aligned:
 318
 319 .. class:: language-de align-center
 320
 321 | **Die Trichter**
 322 |
 323 | Zwei Trichter wandeln durch die Nacht.
 324 | Durch ihres Rumpfs verengten Schacht
 325 | fließt weißes Mondlicht
 326 | still und heiter
 327 | auf   ihren
 328 | Waldweg
 329 | u. s.
 330 | w.
 331 |
 332
 333 Block Quotes
 334 ------------
 335
 336 Block quotes consist of indented body elements:
 337
 338     My theory by A. Elk.  Brackets Miss, brackets.  This theory goes
 339     as follows and begins now.  All brontosauruses are thin at one
 340     end, much much thicker in the middle and then thin again at the
 341     far end.  That is my theory, it is mine, and belongs to me and I
 342     own it, and what it is too.
 343
 344     -- Anne Elk (Miss)
 345
 346 The language of a quote (like any other object) can be specified by
 347 a class attribute:
 348
 349 .. class:: language-fr
 350
 351 ..
 352
 353     ReStructuredText est un langage de balisage léger utilisé
 354     notamment dans la documentation du langage Python.
 355
 356 Doctest Blocks
 357 --------------
 358
 359 >>> print 'Python-specific usage examples; begun with ">>>"'
 360 Python-specific usage examples; begun with ">>>"
 361 >>> print '(cut and pasted from interactive Python sessions)'
 362 (cut and pasted from interactive Python sessions)
 363
 364 Footnotes
 365 ---------
 366
 367 .. [1] A footnote contains body elements, consistently indented by at
 368    least 3 spaces.
 369
 370    This is the footnote's second paragraph.
 371
 372 .. [#label] Footnotes may be numbered, either manually (as in [1]_) or
 373    automatically using a "#"-prefixed label.  This footnote has a
 374    label so it can be referred to from multiple places, both as a
 375    footnote reference ([#label]_) and as a `hyperlink reference`__.
 376
 377    __ label_
 378
 379 .. [#] This footnote is numbered automatically and anonymously using a
 380    label of "#" only.
 381
 382    This is the second paragraph.
 383
 384    And this is the third paragraph.
 385
 386 .. [*] Footnotes may also use symbols, specified with a "*" label.
 387    Here's a reference to the next footnote: [*]_.
 388
 389 .. [*] This footnote shows the next symbol in the sequence.
 390
 391 .. [4] Here's an unreferenced footnote, with a reference to a
 392    nonexistent footnote: [5]_.
 393
 394 Citations
 395 ---------
 396
 397 .. [CIT2002] Citations are text-labeled footnotes. They may be
 398    rendered separately and differently from footnotes.
 399
 400 Here's a reference to the above, [CIT2002]_, and a [nonexistent]_
 401 citation.
 402
 403 .. _Another Target:
 404
 405 Targets
 406 -------
 407
 408 .. _example:
 409
 410 This paragraph is pointed to by the explicit "example" target. A
 411 reference can be found under `Inline Markup`_, above. `Inline
 412 hyperlink targets`_ are also possible.
 413
 414 Section headers are implicit targets, referred to by name. See
 415 Targets_, which is a subsection of `Body Elements`_.
 416
 417 Explicit external targets are interpolated into references such as
 418 "Python_".
 419
 420 .. _Python: http://www.python.org/
 421
 422 Targets may be indirect and anonymous.  Thus `this phrase`__ may also
 423 refer to the Targets_ section.
 424
 425 __ Targets_
 426
 427 Here's a `hyperlink reference without a target`_, which generates an
 428 error.
 429
 430 Duplicate Target Names
 431 ``````````````````````
 432
 433 Duplicate names in section headers or other implicit targets will
 434 generate "info" (level-1) system messages.  Duplicate names in
 435 explicit targets will generate "warning" (level-2) system messages.
 436
 437 Duplicate Target Names
 438 ``````````````````````
 439
 440 Since there are two "Duplicate Target Names" section headers, we
 441 cannot uniquely refer to either of them by name.  If we try to (like
 442 this: `Duplicate Target Names`_), an error is generated.
 443
 444 Directives
 445 ----------
 446
 447 .. contents:: :local:
 448
 449 These are just a sample of the many reStructuredText Directives.  For
 450 others, please see
 451 http://docutils.sourceforge.net/docs/ref/rst/directives.html.
 452
 453 Document Parts
 454 ``````````````
 455
 456 An example of the "contents" directive can be seen above this section
 457 (a local, untitled table of contents_) and at the beginning of the
 458 document (a document-wide `table of contents`_).
 459
 460 Images and Figures
 461 ``````````````````
 462
 463 An image directive (also clickable -- a hyperlink reference):
 464
 465 .. image:: ../../../docs/user/rst/images/title.png
 466    :class: class1 class2
 467    :target: directives_
 468
 469 Image with multiple IDs:
 470
 471 .. _image target 1:
 472 .. _image target 2:
 473 .. _image target 3:
 474 .. image:: ../../../docs/user/rst/images/title.png
 475
 476 A centered image:
 477
 478 .. image:: ../../../docs/user/rst/images/biohazard.png
 479    :align: center
 480
 481 A left-aligned image:
 482
 483 .. image:: ../../../docs/user/rst/images/biohazard.png
 484    :align: left
 485
 486 This paragraph might flow around the image.
 487 The specific behavior depends upon the style sheet and
 488 the browser or rendering software used.
 489
 490 A right-aligned image:
 491
 492 .. image:: ../../../docs/user/rst/images/biohazard.png
 493    :align: right
 494
 495 This paragraph might flow around the image.
 496 The specific behavior depends upon the style sheet and
 497 the browser or rendering software used.
 498
 499 For inline images see `Substitution Definitions`_.
 500
 501 Image size:
 502
 503 An image 2 em wide:
 504
 505 .. image:: ../../../docs/user/rst/images/biohazard.png
 506    :width: 2 em
 507
 508 An image 2 em wide and 15 pixel high:
 509
 510 .. image:: ../../../docs/user/rst/images/biohazard.png
 511    :width: 2em
 512    :height: 15 px
 513
 514 An image occupying 50% of the line width:
 515
 516 .. image:: ../../../docs/user/rst/images/title.png
 517    :width: 50%
 518
 519 An image 2 cm high:
 520
 521 .. image:: ../../../docs/user/rst/images/biohazard.png
 522    :height: 2 cm
 523
 524 A *figure* is an image with a caption and/or a legend.  With page-based output
 525 media, figures might float to a different position if this helps the page
 526 layout.
 527
 528 .. figure:: ../../../docs/user/rst/images/title.png
 529    :figclass: figclass1 figclass2
 530    :class: class1 class2
 531    :alt: reStructuredText, the markup syntax
 532    :width: 258
 533
 534    Plaintext markup syntax and parser system.
 535
 536    +------------+-----------------------------------------------+
 537    | re         | Revised, revisited, based on 're' module.     |
 538    +------------+-----------------------------------------------+
 539    | Structured | Structure-enhanced text, structuredtext.      |
 540    +------------+-----------------------------------------------+
 541    | Text       | Well it is, isn't it?                         |
 542    +------------+-----------------------------------------------+
 543
 544    This paragraph is also part of the legend.
 545
 546 A left-aligned figure:
 547
 548 .. figure:: ../../../docs/user/rst/images/biohazard.png
 549    :figclass: figclass1 figclass2
 550    :class: class1 class2
 551    :alt: reStructuredText, the markup syntax
 552    :align: left
 553    :width: 40 px
 554    :figwidth: 70 %
 555
 556    This is the caption.
 557
 558    This is the legend.
 559
 560    The legend may consist of several paragraphs.
 561
 562 This paragraph might flow around the figure.
 563
 564 The specific behavior depends upon the style sheet and the browser or
 565 rendering software used.
 566
 567 A centered figure:
 568
 569 .. figure:: ../../../docs/user/rst/images/biohazard.png
 570    :align: center
 571    :width: 40 px
 572
 573    This is the caption.
 574
 575    This is the legend.
 576
 577    The legend may consist of several paragraphs.
 578
 579 This paragraph might flow around the figure.
 580
 581 The specific behavior depends upon the style sheet and the browser or
 582 rendering software used.
 583
 584 A right-aligned figure:
 585
 586 .. figure:: ../../../docs/user/rst/images/biohazard.png
 587    :align: right
 588    :width: 40 px
 589
 590    This is the caption.
 591
 592    This is the legend.
 593
 594    The legend may consist of several paragraphs.
 595
 596 This paragraph might flow around the figure. The specific behavior depends
 597 upon the style sheet and the browser or rendering software used.
 598
 599
 600 Tables may be given titles and additional arguments with the *table*
 601 directive:
 602
 603 .. Table:: left-aligned table
 604    :align: left
 605
 606    =====  =====
 607      A    not A
 608    =====  =====
 609    False  True
 610    True   False
 611    =====  =====
 612
 613 .. Table:: center-aligned table
 614    :align: center
 615
 616    =====  =====
 617      A    not A
 618    =====  =====
 619    False  True
 620    True   False
 621    =====  =====
 622
 623 .. Table:: right-aligned table
 624    :align: right
 625
 626    =====  =====
 627      A    not A
 628    =====  =====
 629    False  True
 630    True   False
 631    =====  =====
 632
 633 With the "widths" argument "auto" (or "class" value "colwidths-auto"),
 634 column widths are determined by the backend (if supported by the
 635 writer/backend).
 636
 637 .. _target1:
 638 .. _target2:
 639
 640 .. table::
 641    :widths: auto
 642
 643    ======= ======= ==========
 644    A       B       A or B
 645    ======= ======= ==========
 646    False   False   False
 647    True    False   True
 648    False   True    True
 649    True    True    True
 650    ======= ======= ==========
 651
 652
 653 Admonitions
 654 ```````````
 655
 656 .. Attention:: Directives at large.
 657
 658 .. Caution::
 659
 660    Don't take any wooden nickels.
 661
 662 .. DANGER:: Mad scientist at work!
 663
 664 .. Error:: Does not compute.
 665
 666 .. Hint:: It's bigger than a bread box.
 667
 668 .. Important::
 669    - Wash behind your ears.
 670    - Clean up your room.
 671    - Call your mother.
 672    - Back up your data.
 673
 674 .. Note:: This is a note.
 675
 676 .. Tip:: 15% if the service is good.
 677
 678 .. WARNING:: Strong prose may provoke extreme mental exertion.
 679    Reader discretion is strongly advised.
 680
 681 .. admonition:: And, by the way...
 682
 683    You can make up your own admonition too.
 684
 685    .. _Docutils: http://docutils.sourceforge.net/
 686
 687 Topics, Sidebars, and Rubrics
 688 `````````````````````````````
 689
 690 *Sidebars* are like miniature, parallel documents.
 691
 692 .. sidebar:: Sidebar Title
 693    :subtitle: Optional Subtitle
 694
 695    This is a sidebar.  It is for text outside the flow of the main
 696    text.
 697
 698    .. rubric:: This is a rubric inside a sidebar
 699
 700    Sidebars often appear beside the main text with a border and a different
 701    background or font color.
 702
 703 A *topic* is like a block quote with a title, or a self-contained section
 704 with no subsections.
 705
 706 .. topic:: Topic Title
 707
 708    This is a topic.
 709
 710 A *rubric* is like an informal heading that doesn't correspond to the
 711 document's structure. It is typically highlighted in red (hence the name).
 712
 713 .. rubric:: This is a rubric
 714
 715 Topics and rubrics can be used at places where a `section title`_ is not
 716 allowed (e.g. inside a directive).
 717
 718 Target Footnotes
 719 ````````````````
 720
 721 .. target-notes::
 722
 723
 724 Replacement Text
 725 ````````````````
 726
 727 I recommend you try |Python|_.
 728
 729 .. |Python| replace:: Python, *the* best language around
 730
 731 Compound Paragraph
 732 ``````````````````
 733
 734 .. compound::
 735    :class: some-class
 736
 737    Compound 1, paragraph 1.
 738
 739    Compound 1, paragraph 2.
 740
 741    * Compound 1, list item one.
 742    * Compound 1, list item two.
 743
 744 Another compound statement:
 745
 746 .. compound::
 747
 748    Compound 2, a literal block::
 749
 750        Compound 2, literal.
 751
 752    Compound 2, this is a test.
 753
 754 .. compound::
 755
 756    Compound 3, only consisting of one paragraph.
 757
 758 .. compound::
 759
 760    ::
 761
 762        Compound 4.
 763        This one starts with a literal block.
 764
 765    Compound 4, a paragraph.
 766
 767 Now something *really* perverted -- a nested compound block.  This is
 768 just to test that it works at all; the results don't have to be
 769 meaningful.
 770
 771 .. compound::
 772
 773    Compound 5, block 1 (a paragraph).
 774
 775    .. compound::
 776
 777       Compound 6, block 2 in compound 5.
 778
 779       Compound 6, another paragraph.
 780
 781    Compound 5, block 3 (a paragraph).
 782
 783 .. compound::
 784
 785    Compound 7, with a table inside:
 786
 787    +--------------------+--------------------+--------------------+
 788    | Left cell, first   | Middle cell,       | Right cell.        |
 789    | paragraph.         | consisting of      |                    |
 790    |                    | exactly one        | Paragraph 2.       |
 791    | Left cell, second  | paragraph.         |                    |
 792    | paragraph.         |                    | Paragraph 3.       |
 793    +--------------------+--------------------+--------------------+
 794
 795    Compound 7, a paragraph after the table.
 796
 797    Compound 7, another paragraph.
 798
 799 Parsed Literal Blocks
 800 `````````````````````
 801
 802 .. parsed-literal::
 803
 804    This is a parsed literal block.
 805        This line is indented.  The next line is blank.
 806
 807    Inline markup is supported, e.g. *emphasis*, **strong**, ``literal
 808    text``, :sub:`sub-` and :sup:`super`\ scripts,
 809    inline formulas: :math:`A = 2 \pi r^2`,
 810    footnotes [1]_, _`hyperlink targets`, and `references
 811    <http://www.python.org/>`_.
 812
 813 Code
 814 ````
 815
 816 Blocks of source code can be set with the `code` directive. If the code
 817 language is specified, the content is parsed and tagged by the Pygments_
 818 syntax highlighter and can be formatted with a style sheet. (Code parsing
 819 is turned off using the ``syntax-highlight`` config setting in the test
 820 conversions in order to get identical results with/without installed
 821 Pygments highlighter.)
 822
 823 .. code:: python
 824
 825   print 'This is Python code.'
 826
 827 The ``:number-lines:`` option (with optional start value) generates line
 828 numbers:
 829
 830 .. code:: python
 831   :number-lines: 8
 832
 833   # print integers from 0 to 9:
 834   for i in range(10):
 835       print i
 836
 837 For inline code snippets, there is the `code` role, which can be used
 838 directly (the code will not be parsed/tagged, as the language is not known)
 839 or as base for special code roles, e.g. the LaTeX code in the next
 840 paragraph.
 841
 842 .. role:: tex(code)
 843    :language: tex
 844
 845 Docutils uses LaTeX syntax for math directives and roles:
 846 :tex:`\alpha = f(x)` prints :math:`\alpha = f(x)`.
 847
 848 The ``:code:`` option of the `include` directive sets the included content
 849 as a code block, here the rst file ``header_footer.txt`` with line numbers:
 850
 851 .. include:: header_footer.txt
 852    :code: rst
 853    :number-lines:
 854
 855 .. _Pygments: http://pygments.org/
 856
 857 Substitution Definitions
 858 ------------------------
 859
 860 An inline image (|example|) example:
 861
 862 .. |EXAMPLE| image:: ../../../docs/user/rst/images/biohazard.png
 863
 864 (Substitution definitions are not visible in the HTML source.)
 865
 866 Comments
 867 --------
 868
 869 Here's one:
 870
 871 .. Comments begin with two dots and a space. Anything may
 872    follow, except for the syntax of footnotes, hyperlink
 873    targets, directives, or substitution definitions.
 874
 875    Double-dashes -- "--" -- must be escaped somehow in HTML output.
 876
 877    Comments may contain non-ASCII characters: ä ö ü æ ø å
 878
 879 (View the HTML source to see the comment.)
 880
 881 Raw text
 882 --------
 883
 884 This does not necessarily look nice, because there may be missing white space.
 885
 886 It's just there to freeze the behavior.
 887
 888 .. raw:: html latex
 889
 890    A test.
 891
 892 .. raw:: html latex
 893
 894    Second test.
 895
 896 .. class:: myclass
 897
 898 .. raw:: html latex
 899
 900    Another test with myclass set.
 901
 902 .. role:: raw-role(raw)
 903    :format: html latex
 904    :class: myrawroleclass
 905
 906 This is the :raw-role:`fourth test` with myrawroleclass set.
 907
 908 .. raw:: html
 909
 910    Fifth test in HTML.<br />Line two.
 911
 912 .. raw:: latex
 913
 914    Fifth test in LaTeX.\\Line two.
 915
 916 Container
 917 ---------
 918
 919 .. container:: custom
 920
 921    paragraph 1
 922
 923    paragraph 2