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 .. table::
 638    :widths: auto
 639
 640    ======= ======= ==========
 641    A       B       A or B
 642    ======= ======= ==========
 643    False   False   False
 644    True    False   True
 645    False   True    True
 646    True    True    True
 647    ======= ======= ==========
 648
 649
 650 Admonitions
 651 ```````````
 652
 653 .. Attention:: Directives at large.
 654
 655 .. Caution::
 656
 657    Don't take any wooden nickels.
 658
 659 .. DANGER:: Mad scientist at work!
 660
 661 .. Error:: Does not compute.
 662
 663 .. Hint:: It's bigger than a bread box.
 664
 665 .. Important::
 666    - Wash behind your ears.
 667    - Clean up your room.
 668    - Call your mother.
 669    - Back up your data.
 670
 671 .. Note:: This is a note.
 672
 673 .. Tip:: 15% if the service is good.
 674
 675 .. WARNING:: Strong prose may provoke extreme mental exertion.
 676    Reader discretion is strongly advised.
 677
 678 .. admonition:: And, by the way...
 679
 680    You can make up your own admonition too.
 681
 682    .. _Docutils: http://docutils.sourceforge.net/
 683
 684 Topics, Sidebars, and Rubrics
 685 `````````````````````````````
 686
 687 *Sidebars* are like miniature, parallel documents.
 688
 689 .. sidebar:: Sidebar Title
 690    :subtitle: Optional Subtitle
 691
 692    This is a sidebar.  It is for text outside the flow of the main
 693    text.
 694
 695    .. rubric:: This is a rubric inside a sidebar
 696
 697    Sidebars often appear beside the main text with a border and a different
 698    background or font color.
 699
 700 A *topic* is like a block quote with a title, or a self-contained section
 701 with no subsections.
 702
 703 .. topic:: Topic Title
 704
 705    This is a topic.
 706
 707 A *rubric* is like an informal heading that doesn't correspond to the
 708 document's structure. It is typically highlighted in red (hence the name).
 709
 710 .. rubric:: This is a rubric
 711
 712 Topics and rubrics can be used at places where a `section title`_ is not
 713 allowed (e.g. inside a directive).
 714
 715 Target Footnotes
 716 ````````````````
 717
 718 .. target-notes::
 719
 720
 721 Replacement Text
 722 ````````````````
 723
 724 I recommend you try |Python|_.
 725
 726 .. |Python| replace:: Python, *the* best language around
 727
 728 Compound Paragraph
 729 ``````````````````
 730
 731 .. compound::
 732    :class: some-class
 733
 734    Compound 1, paragraph 1.
 735
 736    Compound 1, paragraph 2.
 737
 738    * Compound 1, list item one.
 739    * Compound 1, list item two.
 740
 741 Another compound statement:
 742
 743 .. compound::
 744
 745    Compound 2, a literal block::
 746
 747        Compound 2, literal.
 748
 749    Compound 2, this is a test.
 750
 751 .. compound::
 752
 753    Compound 3, only consisting of one paragraph.
 754
 755 .. compound::
 756
 757    ::
 758
 759        Compound 4.
 760        This one starts with a literal block.
 761
 762    Compound 4, a paragraph.
 763
 764 Now something *really* perverted -- a nested compound block.  This is
 765 just to test that it works at all; the results don't have to be
 766 meaningful.
 767
 768 .. compound::
 769
 770    Compound 5, block 1 (a paragraph).
 771
 772    .. compound::
 773
 774       Compound 6, block 2 in compound 5.
 775
 776       Compound 6, another paragraph.
 777
 778    Compound 5, block 3 (a paragraph).
 779
 780 .. compound::
 781
 782    Compound 7, with a table inside:
 783
 784    +--------------------+--------------------+--------------------+
 785    | Left cell, first   | Middle cell,       | Right cell.        |
 786    | paragraph.         | consisting of      |                    |
 787    |                    | exactly one        | Paragraph 2.       |
 788    | Left cell, second  | paragraph.         |                    |
 789    | paragraph.         |                    | Paragraph 3.       |
 790    +--------------------+--------------------+--------------------+
 791
 792    Compound 7, a paragraph after the table.
 793
 794    Compound 7, another paragraph.
 795
 796 Parsed Literal Blocks
 797 `````````````````````
 798
 799 .. parsed-literal::
 800
 801    This is a parsed literal block.
 802        This line is indented.  The next line is blank.
 803
 804    Inline markup is supported, e.g. *emphasis*, **strong**, ``literal
 805    text``, :sub:`sub-` and :sup:`super`\ scripts,
 806    inline formulas: :math:`A = 2 \pi r^2`,
 807    footnotes [1]_, _`hyperlink targets`, and `references
 808    <http://www.python.org/>`_.
 809
 810 Code
 811 ````
 812
 813 Blocks of source code can be set with the `code` directive. If the code
 814 language is specified, the content is parsed and tagged by the Pygments_
 815 syntax highlighter and can be formatted with a style sheet. (Code parsing
 816 is turned off using the ``syntax-highlight`` config setting in the test
 817 conversions in order to get identical results with/without installed
 818 Pygments highlighter.)
 819
 820 .. code:: python
 821
 822   print 'This is Python code.'
 823
 824 The ``:number-lines:`` option (with optional start value) generates line
 825 numbers:
 826
 827 .. code:: python
 828   :number-lines: 8
 829
 830   # print integers from 0 to 9:
 831   for i in range(10):
 832       print i
 833
 834 For inline code snippets, there is the `code` role, which can be used
 835 directly (the code will not be parsed/tagged, as the language is not known)
 836 or as base for special code roles, e.g. the LaTeX code in the next
 837 paragraph.
 838
 839 .. role:: tex(code)
 840    :language: tex
 841
 842 Docutils uses LaTeX syntax for math directives and roles:
 843 :tex:`\alpha = f(x)` prints :math:`\alpha = f(x)`.
 844
 845 The ``:code:`` option of the `include` directive sets the included content
 846 as a code block, here the rst file ``header_footer.txt`` with line numbers:
 847
 848 .. include:: header_footer.txt
 849    :code: rst
 850    :number-lines:
 851
 852 .. _Pygments: http://pygments.org/
 853
 854 Substitution Definitions
 855 ------------------------
 856
 857 An inline image (|example|) example:
 858
 859 .. |EXAMPLE| image:: ../../../docs/user/rst/images/biohazard.png
 860
 861 (Substitution definitions are not visible in the HTML source.)
 862
 863 Comments
 864 --------
 865
 866 Here's one:
 867
 868 .. Comments begin with two dots and a space. Anything may
 869    follow, except for the syntax of footnotes, hyperlink
 870    targets, directives, or substitution definitions.
 871
 872    Double-dashes -- "--" -- must be escaped somehow in HTML output.
 873
 874    Comments may contain non-ASCII characters: ä ö ü æ ø å
 875
 876 (View the HTML source to see the comment.)
 877
 878 Raw text
 879 --------
 880
 881 This does not necessarily look nice, because there may be missing white space.
 882
 883 It's just there to freeze the behavior.
 884
 885 .. raw:: html latex
 886
 887    A test.
 888
 889 .. raw:: html latex
 890
 891    Second test.
 892
 893 .. class:: myclass
 894
 895 .. raw:: html latex
 896
 897    Another test with myclass set.
 898
 899 .. role:: raw-role(raw)
 900    :format: html latex
 901    :class: myrawroleclass
 902
 903 This is the :raw-role:`fourth test` with myrawroleclass set.
 904
 905 .. raw:: html
 906
 907    Fifth test in HTML.<br />Line two.
 908
 909 .. raw:: latex
 910
 911    Fifth test in LaTeX.\\Line two.
 912
 913 Container
 914 ---------
 915
 916 .. container:: custom
 917
 918    paragraph 1
 919
 920    paragraph 2