sandbox/grubert/ltx-test.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 ================================
   5  reStructuredText Test Document
   6 ================================
   7
   8 .. Above is the document title, and below is the subtitle.
   9    They are transformed from section titles after parsing.
  10
  11 --------------------------------
  12  Examples of Syntax Constructs
  13 --------------------------------
  14
  15 .. bibliographic fields (which also require a transform):
  16
  17 :Author: David Goodger
  18 :Address: 123 Example Street
  19           Example, EX  Canada
  20           A1B 2C3
  21 :Contact: goodger@users.sourceforge.net
  22 :Authors: Me; Myself; I
  23 :organization: humankind
  24 :date: $Date$
  25 :status: This is a "work in progress"
  26 :revision: $Revision$
  27 :version: 1
  28 :copyright: This document has been placed in the public domain. You
  29             may do with it as you wish. You may copy, modify,
  30             redistribute, reattribute, sell, buy, rent, lease,
  31             destroy, or improve it, quote it at length, excerpt,
  32             incorporate, collate, fold, staple, or mutilate it, or do
  33             anything else to it that your or anyone else's heart
  34             desires.
  35 :field name: This is a generic bibliographic field.
  36 :field name 2:
  37     Generic bibliographic fields may contain multiple body elements.
  38
  39     Like this.
  40
  41 :Dedication:
  42
  43     For Docutils users & co-developers.
  44
  45 :abstract:
  46
  47     This is a test document, containing at least one example of each
  48     reStructuredText construct.
  49
  50 .. meta::
  51    :keywords: reStructuredText, test, parser
  52    :description lang=en: A test document, containing at least one
  53        example of each reStructuredText construct.
  54
  55 .. contents:: Table of Contents
  56 .. section-numbering::
  57
  58
  59 Structural Elements
  60 ===================
  61
  62 Section Title
  63 -------------
  64
  65 That's it, the text just above this line.
  66
  67 Transitions
  68 -----------
  69
  70 Here's a transition:
  71
  72 ---------
  73
  74 It divides the section.
  75
  76 Body Elements
  77 =============
  78
  79 Paragraphs
  80 ----------
  81
  82 A paragraph.
  83
  84 Inline Markup
  85 `````````````
  86
  87 Paragraphs contain text and may contain inline markup: *emphasis*,
  88 **strong emphasis**, `interpreted text`, ``inline literals``,
  89 standalone hyperlinks (http://www.python.org), external hyperlinks
  90 (Python_), internal cross-references (example_), footnote references
  91 (manually numbered [1]_, anonymous auto-numbered [#]_, labeled
  92 auto-numbered [#label]_, or symbolic [*]_), citation references
  93 ([CIT2002]_), substitution references (|example|), and _`inline
  94 hyperlink targets` (see Targets_ below for a reference back to here).
  95 Problems are indicated by |problematic| text (generated by processing
  96 errors; this one is intentional).
  97
  98 .. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
  99
 100 Let's test wrapping and whitespace significance in inline literals:
 101 ``This is an example of --inline-literal --text, --including some--
 102 strangely--hyphenated-words.  Adjust-the-width-of-your-browser-window
 103 to see how the text is wrapped.  -- ---- --------  Now note    the
 104 spacing    between the    words of    this sentence    (words
 105 should    be grouped    in pairs).``
 106
 107 If the ``--pep-references`` option was supplied, there should be a
 108 live link to PEP 258 here.
 109
 110 Bullet Lists
 111 ------------
 112
 113 - A bullet list
 114
 115   + Nested bullet list.
 116   + Nested item 2.
 117
 118 - Item 2.
 119
 120   Paragraph 2 of item 2.
 121
 122   * Nested bullet list.
 123   * Nested item 2.
 124
 125     - Third level.
 126     - Item 2.
 127
 128   * Nested item 3.
 129
 130 Enumerated Lists
 131 ----------------
 132
 133 1. Arabic numerals.
 134
 135    a) lower alpha)
 136
 137       (i) (lower roman)
 138
 139           A. upper alpha.
 140
 141              I) upper roman)
 142
 143 2. Lists that don't start at 1:
 144
 145    3. Three
 146
 147    4. Four
 148
 149    C. C
 150
 151    D. D
 152
 153    iii. iii
 154
 155    iv. iv
 156
 157 Definition Lists
 158 ----------------
 159
 160 Term
 161     Definition
 162 Term : classifier
 163     Definition paragraph 1.
 164
 165     Definition paragraph 2.
 166 Term
 167     Definition
 168
 169 Field Lists
 170 -----------
 171
 172 :what: Field lists map field names to field bodies, like database
 173        records.  They are often part of an extension syntax.  They are
 174        an unambiguous variant of RFC 2822 fields.
 175
 176 :how arg1 arg2:
 177
 178     The field marker is a colon, the field name, and a colon.
 179
 180     The field body may contain one or more body elements, indented
 181     relative to the field marker.
 182
 183 Option Lists
 184 ------------
 185
 186 For listing command-line options:
 187
 188 -a            command-line option "a"
 189 -b file       options can have arguments
 190               and long descriptions
 191 --long        options can be long also
 192 --input=file  long options can also have
 193               arguments
 194
 195 --very-long-option
 196               The description can also start on the next line.
 197
 198               The description may contain multiple body elements,
 199               regardless of where it starts.
 200
 201 -x, -y, -z    Multiple options are an "option group".
 202 -v, --verbose  Commonly-seen: short & long options.
 203 -1 file, --one=file, --two file
 204               Multiple options with arguments.
 205 /V            DOS/VMS-style options too
 206
 207 There must be at least two spaces between the option and the
 208 description.
 209
 210 Literal Blocks
 211 --------------
 212
 213 Literal blocks are indented, and indicated with a double-colon ("::")
 214 at the end of the preceding paragraph (right here ``-->``)::
 215
 216     if literal_block:
 217         text = 'is left as-is'
 218         spaces_and_linebreaks = 'are preserved'
 219         markup_processing = None
 220
 221 Block Quotes
 222 ------------
 223
 224 Block quotes consist of indented body elements:
 225
 226     This theory, that is mine, is mine.
 227
 228     -- Anne Elk (Miss)
 229
 230 Doctest Blocks
 231 --------------
 232
 233 >>> print 'Python-specific usage examples; begun with ">>>"'
 234 Python-specific usage examples; begun with ">>>"
 235 >>> print '(cut and pasted from interactive Python sessions)'
 236 (cut and pasted from interactive Python sessions)
 237
 238 Tables
 239 ------
 240
 241 Here's a grid table followed by a simple table:
 242
 243 +------------------------+------------+----------+----------+
 244 | Header row, column 1   | Header 2   | Header 3 | Header 4 |
 245 | (header rows optional) |            |          |          |
 246 +========================+============+==========+==========+
 247 | body row 1, column 1   | column 2   | column 3 | column 4 |
 248 +------------------------+------------+----------+----------+
 249 | body row 2             | Cells may span columns.          |
 250 +------------------------+------------+----------+----------+
 251 | body row 5             | Cells may also be     |          |
 252 |                        | empty: ``-->``        |          |
 253 +------------------------+-----------------------+----------+
 254
 255 .. not for latex
 256    +------------------------+------------+---------------------+
 257    | body row 3             | Cells may  | - Table cells       |
 258    +------------------------+ span rows. | - contain           |
 259    | body row 4             |            | - body elements.    |
 260
 261
 262 =====  =====  ======
 263    Inputs     Output
 264 ------------  ------
 265   A      B    A or B
 266 =====  =====  ======
 267 False  False  False
 268 True   False  True
 269 False  True   True
 270 True   True   True
 271 =====  =====  ======
 272
 273 Footnotes
 274 ---------
 275
 276 .. [1] A footnote contains body elements, consistently indented by at
 277    least 3 spaces.
 278
 279    This is the footnote's second paragraph.
 280
 281 .. [#label] Footnotes may be numbered, either manually (as in [1]_) or
 282    automatically using a "#"-prefixed label.  This footnote has a
 283    label so it can be referred to from multiple places, both as a
 284    footnore reference ([#label]_) and as a hyperlink reference
 285    (label_).
 286
 287 .. [#] This footnote is numbered automatically and anonymously using a
 288    label of "#" only.
 289
 290 .. [*] Footnotes may also use symbols, specified with a "*" label.
 291    Here's a reference to the next footnote: [*]_.
 292
 293 .. [*] This footnote shows the next symbol in the sequence.
 294
 295 .. [4] Here's an unreferenced footnote, with a reference to a
 296    nonexistent footnote: [5]_.
 297
 298 Citations
 299 ---------
 300
 301 .. [CIT2002] Citations are text-labeled footnotes. They may be
 302    rendered separately and differently from footnotes.
 303
 304 Here's a reference to the above, [CIT2002]_, and a [nonexistent]_
 305 citation.
 306
 307 Targets
 308 -------
 309
 310 .. _example:
 311
 312 This paragraph is pointed to by the explicit "example" target. A
 313 reference can be found under `Inline Markup`_, above. `Inline
 314 hyperlink targets`_ are also possible.
 315
 316 Section headers are implicit targets, referred to by name. See
 317 Targets_, which is a subsection of `Body Elements`_.
 318
 319 Explicit external targets are interpolated into references such as
 320 "Python_".
 321
 322 .. _Python: http://www.python.org/
 323
 324 Targets may be indirect and anonymous.  Thus `this phrase`__ may also
 325 refer to the Targets_ section.
 326
 327 __ Targets_
 328
 329 Here's a `hyperlink reference without a target`_, which generates an
 330 error.
 331
 332 Duplicate Target Names
 333 ``````````````````````
 334
 335 Duplicate names in section headers or other implicit targets will
 336 generate "info" (level-1) system messages.  Duplicate names in
 337 explicit targets will generate "warning" (level-2) system messages.
 338
 339 Duplicate Target Names
 340 ``````````````````````
 341
 342 Since there are two "Duplicate Target Names" section headers, we
 343 cannot uniquely refer to either of them by name.  If we try to (like
 344 this: `Duplicate Target Names`_), an error is generated.
 345
 346 Directives
 347 ----------
 348
 349 .. contents:: :local:
 350
 351 These are just a sample of the many reStructuredText Directives.  For
 352 others, please see http://docutils.sf.net/spec/rst/directives.html.
 353
 354 Document Parts
 355 ``````````````
 356
 357 An example of the "contents" directive can be seen above this section
 358 (a local, untitled table of contents_) and at the beginning of the
 359 document (a document-wide `table of contents`_).
 360
 361 Images
 362 ``````
 363
 364 An image directive:
 365
 366 .. image:: ../docs/rst/images/title.png
 367
 368 A figure directive:
 369
 370 .. figure:: ../docs/rst/images/title.png
 371    :alt: reStructuredText, the markup syntax
 372
 373    A figure is an image with a caption and/or a legend:
 374
 375    +------------+-----------------------------------------------+
 376    | re         | Revised, revisited, based on 're' module.     |
 377    +------------+-----------------------------------------------+
 378    | Structured | Structure-enhanced text, structuredtext.      |
 379    +------------+-----------------------------------------------+
 380    | Text       | Well it is, isn't it?                         |
 381    +------------+-----------------------------------------------+
 382
 383    This paragraph is also part of the legend.
 384
 385 Admonitions
 386 ```````````
 387
 388 .. Attention:: Directives at large.
 389
 390 .. Caution::
 391
 392    Don't take any wooden nickels.
 393
 394 .. DANGER:: Mad scientist at work!
 395
 396 .. Error:: Does not compute.
 397
 398 .. Hint:: It's bigger than a bread box.
 399
 400 .. Important::
 401    - Wash behind your ears.
 402    - Clean up your room.
 403    - Call your mother.
 404    - Back up your data.
 405
 406 .. Note:: This is a note.
 407
 408 .. Tip:: 15% if the service is good.
 409
 410 .. WARNING:: Strong prose may provoke extreme mental exertion.
 411    Reader discretion is strongly advised.
 412
 413 Target Footnotes
 414 ````````````````
 415
 416 .. target-notes::
 417
 418 Line Blocks
 419 ```````````
 420
 421 Take it away, Eric the Orchestra Leader!
 422
 423 .. line-block::
 424
 425    A one, two, a one two three four
 426
 427    Half a bee, philosophically,
 428        must, *ipso facto*, half not be.
 429    But half the bee has got to be,
 430        *vis a vis* its entity.  D'you see?
 431
 432    But can a bee be said to be
 433        or not to be an entire bee,
 434            when half the bee is not a bee,
 435                due to some ancient injury?
 436
 437    Singing...
 438
 439 Replacement Text
 440 ````````````````
 441
 442 I recommend you try |Python|_.
 443
 444 .. |Python| replace:: Python, *the* best language around
 445
 446 Substitution Definitions
 447 ------------------------
 448
 449 An inline image (|example|) example:
 450
 451 .. |EXAMPLE| image:: ../docs/rst/images/biohazard.png
 452
 453 (Substitution definitions are not visible in the HTML source.)
 454
 455 Comments
 456 --------
 457
 458 Here's one:
 459
 460 .. Comments begin with two dots and a space. Anything may
 461    follow, except for the syntax of footnotes, hyperlink
 462    targets, directives, or substitution definitions.
 463
 464    Double-dashes -- "--" -- must be escaped somehow in HTML output.
 465
 466 (View the HTML source to see the comment.)
 467
 468 Error Handling
 469 ==============
 470
 471 Any errors caught during processing will generate system messages.
 472
 473 There should be five messages in the following, auto-generated
 474 section, "Docutils System Messages":
 475
 476 .. section should be added by Docutils automatically