prest/doc/src/quickstart.rst

   1 A ReStructuredText Primer
   2 =========================
   3
   4 :Author: Richard Jones
   5 :Version: $Revision: 684 $
   6 :Copyright: This document has been placed in the public domain.
   7
   8 .. contents::
   9
  10
  11 The text below contains links that look like "(quickref__)".  These
  12 are relative links that point to the `Quick reStructuredText`_ user
  13 reference.  If these links don't work, please refer to the `master
  14 quick reference`_ document.
  15
  16 __
  17 .. _Quick reStructuredText: quickref.html
  18 .. _master quick reference:
  19    http://docutils.sourceforge.net/docs/rst/quickref.html
  20
  21
  22 Structure
  23 ---------
  24
  25 From the outset, let me say that "Structured Text" is probably a bit
  26 of a misnomer.  It's more like "Relaxed Text" that uses certain
  27 consistent patterns.  These patterns are interpreted by a HTML
  28 converter to produce "Very Structured Text" that can be used by a web
  29 browser.
  30
  31 The most basic pattern recognised is a **paragraph** (quickref__).
  32 That's a chunk of text that is separated by blank lines (one is
  33 enough).  Paragraphs must have the same indentation -- that is, line
  34 up at their left edge.  Paragraphs that start indented will result in
  35 indented quote paragraphs. For example::
  36
  37   This is a paragraph.  It's quite
  38   short.
  39
  40      This paragraph will result in an indented block of
  41      text, typically used for quoting other text.
  42
  43   This is another one.
  44
  45 Results in:
  46
  47   This is a paragraph.  It's quite
  48   short.
  49
  50      This paragraph will result in an indented block of
  51      text, typically used for quoting other text.
  52
  53   This is another one.
  54
  55 __ quickref.html#paragraphs
  56
  57 Text styles
  58 -----------
  59
  60 (quickref__)
  61
  62 __ quickref.html#inline-markup
  63
  64 Inside paragraphs and other bodies of text, you may additionally mark
  65 text for *italics* with "``*italics*``" or **bold** with
  66 "``**bold**``".
  67
  68 If you want something to appear as a fixed-space literal, use
  69 "````double back-quotes````".  Note that no further fiddling is done
  70 inside the double back-quotes -- so asterisks "``*``" etc. are left
  71 alone.
  72
  73 If you find that you want to use one of the "special" characters in
  74 text, it will generally be OK -- reStructuredText is pretty smart.
  75 For example, this * asterisk is handled just fine.  If you actually
  76 want text \*surrounded by asterisks* to **not** be italicised, then
  77 you need to indicate that the asterisk is not special.  You do this by
  78 placing a backslash just before it, like so "``\*``" (quickref__), or
  79 by enclosing it in double back-quotes (inline literals), like this::
  80
  81     ``\*``
  82
  83 __ quickref.html#escaping
  84
  85 Lists
  86 -----
  87
  88 Lists of items come in three main flavours: **enumerated**,
  89 **bulleted** and **definitions**.  In all list cases, you may have as
  90 many paragraphs, sublists, etc. as you want, as long as the left-hand
  91 side of the paragraph or whatever aligns with the first line of text
  92 in the list item.
  93
  94 Lists must always start a new paragraph -- that is, they must appear
  95 after a blank line.
  96
  97 **enumerated** lists (numbers, letters or roman numerals; quickref__)
  98   __ quickref.html#enumerated-lists
  99
 100   Start a line off with a number or letter followed by a period ".",
 101   right bracket ")" or surrounded by brackets "( )" -- whatever you're
 102   comfortable with.  All of the following forms are recognised::
 103
 104     1. numbers
 105
 106     A. upper-case letters
 107        and it goes over many lines
 108
 109        with two paragraphs and all!
 110
 111     a. lower-case letters
 112
 113        3. with a sub-list starting at a different number
 114        4. make sure the numbers are in the correct sequence though!
 115
 116     I. upper-case roman numerals
 117
 118     i. lower-case roman numerals
 119
 120     (1) numbers again
 121
 122     1) and again
 123
 124   Results in (note: the different enumerated list styles are not
 125   always supported by every web browser, so you may not get the full
 126   effect here):
 127
 128   1. numbers
 129
 130   A. upper-case letters
 131      and it goes over many lines
 132
 133      with two paragraphs and all!
 134
 135   a. lower-case letters
 136
 137      3. with a sub-list starting at a different number
 138      4. make sure the numbers are in the correct sequence though!
 139
 140   I. upper-case roman numerals
 141
 142   i. lower-case roman numerals
 143
 144   (1) numbers again
 145
 146   1) and again
 147
 148 **bulleted** lists (quickref__)
 149   __ quickref.html#bullet-lists
 150
 151   Just like enumerated lists, start the line off with a bullet point
 152   character - either "-", "+" or "*"::
 153
 154     * a bullet point using "*"
 155
 156       - a sub-list using "-"
 157
 158         + yet another sub-list
 159
 160       - another item
 161
 162   Results in:
 163
 164   * a bullet point using "*"
 165
 166     - a sub-list using "-"
 167
 168       + yet another sub-list
 169
 170     - another item
 171
 172 **definition** lists (quickref__)
 173   __ quickref.html#definition-lists
 174
 175   Unlike the other two, the definition lists consist of a term, and
 176   the definition of that term.  The format of a definition list is::
 177
 178     what
 179       Definition lists associate a term with a definition.
 180
 181     *how*
 182       The term is a one-line phrase, and the definition is one or more
 183       paragraphs or body elements, indented relative to the term.
 184       Blank lines are not allowed between term and definition.
 185
 186   Results in:
 187
 188   what
 189     Definition lists associate a term with a definition.
 190
 191   *how*
 192     The term is a one-line phrase, and the definition is one or more
 193     paragraphs or body elements, indented relative to the term.
 194     Blank lines are not allowed between term and definition.
 195
 196 Preformatting (code samples)
 197 ----------------------------
 198 (quickref__)
 199
 200 __ quickref.html#literal-blocks
 201
 202 To just include a chunk of preformatted, never-to-be-fiddled-with
 203 text, finish the prior paragraph with "``::``".  The preformatted
 204 block is finished when the text falls back to the same indentation
 205 level as a paragraph prior to the preformatted block.  For example::
 206
 207   An example::
 208
 209       Whitespace, newlines, blank lines, and all kinds of markup
 210         (like *this* or \this) is preserved by literal blocks.
 211     Lookie here, I've dropped an indentation level
 212     (but not far enough)
 213
 214   no more example
 215
 216 Results in:
 217
 218   An example::
 219
 220       Whitespace, newlines, blank lines, and all kinds of markup
 221         (like *this* or \this) is preserved by literal blocks.
 222     Lookie here, I've dropped an indentation level
 223     (but not far enough)
 224
 225   no more example
 226
 227 Note that if a paragraph consists only of "``::``", then it's removed
 228 from the output::
 229
 230   ::
 231
 232       This is preformatted text, and the
 233       last "::" paragraph is removed
 234
 235 Results in:
 236
 237 ::
 238
 239     This is preformatted text, and the
 240     last "::" paragraph is removed
 241
 242 Sections
 243 --------
 244
 245 (quickref__)
 246
 247 __ quickref.html#section-structure
 248
 249 To break longer text up into sections, you use **section headers**.
 250 These are a single line of text (one or more words) with adornment: an
 251 underline alone, or an overline and an overline together, in dashes
 252 "``-----``", equals "``======``", tildes "``~~~~~~``" or any of the
 253 non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you
 254 feel comfortable with.  An underline-only adornment is distinct from
 255 an overline-and-underline adornment using the same character.  The
 256 underline/overline must be at least as long as the title text.  Be
 257 consistent, since all sections marked with the same adornment style
 258 are deemed to be at the same level::
 259
 260   Chapter 1 Title
 261   ===============
 262
 263   Section 1.1 Title
 264   -----------------
 265
 266   Subsection 1.1.1 Title
 267   ~~~~~~~~~~~~~~~~~~~~~~
 268
 269   Section 1.2 Title
 270   -----------------
 271
 272   Chapter 2 Title
 273   ===============
 274
 275 This results in the following structure, illustrated by simplified
 276 pseudo-XML::
 277
 278     <section>
 279         <title>
 280             Chapter 1 Title
 281         <section>
 282             <title>
 283                 Section 1.1 Title
 284             <section>
 285                 <title>
 286                     Subsection 1.1.1 Title
 287         <section>
 288             <title>
 289                 Section 1.2 Title
 290     <section>
 291         <title>
 292             Chapter 2 Title
 293
 294 (Pseudo-XML uses indentation for nesting and has no end-tags.  It's
 295 not possible to show actual processed output, as in the other
 296 examples, because sections cannot exist inside block quotes.  For a
 297 concrete example, compare the section structure of this document's
 298 source text and processed output.)
 299
 300 Note that section headers are available as link targets, just using
 301 their name.  To link to the Lists_ heading, I write "``Lists_``".  If
 302 the heading has a space in it like `text styles`_, we need to quote
 303 the heading "```text styles`_``".
 304
 305 To indicate the document title, use a unique adornment style at the
 306 beginning of the document.  To indicate the document subtitle, use
 307 another unique adornment style immediately after the document title.
 308 For example::
 309
 310     ================
 311      Document Title
 312     ================
 313     ----------
 314      Subtitle
 315     ----------
 316
 317     Section Title
 318     =============
 319
 320     ...
 321
 322 Note that "Document Title" and "Section Title" both use equals signs,
 323 but are distict and unrelated styles.  The text of
 324 overline-and-underlined titles (but not underlined-only) may be inset
 325 for aesthetics.
 326
 327
 328 Images
 329 ------
 330
 331 (quickref__)
 332
 333 __ quickref.html#directives
 334
 335 To include an image in your document, you use the the ``image`` directive__.
 336 For example::
 337
 338   .. image:: images/biohazard.png
 339
 340 results in:
 341
 342 .. image:: images/biohazard.png
 343
 344 The ``images/biohazard.png`` part indicates the filename of the image
 345 you wish to appear in the document. There's no restriction placed on
 346 the image (format, size etc).  If the image is to appear in HTML and
 347 you wish to supply additional information, you may::
 348
 349   .. image:: images/biohazard.png
 350      :height: 100
 351      :width: 200
 352      :scale: 50
 353      :alt: alternate text
 354
 355 See the full image directive documentation__ for more info.
 356
 357 __ ../../spec/rst/directives.html
 358 __ ../../spec/rst/directives.html#images
 359
 360
 361 What Next?
 362 ----------
 363
 364 This primer introduces the most common features of reStructuredText,
 365 but there are a lot more to explore.  The `Quick reStructuredText`_
 366 user reference is a good place to go next.  For complete details, the
 367 `reStructuredText Markup Specification`_ is the place to go [#]_.
 368
 369 Users who have questions or need assistance with Docutils or
 370 reStructuredText should `post a message`_ to the `Docutils-Users
 371 mailing list`_.  The `Docutils project web site`_ has more
 372 information.
 373
 374 .. [#] If that relative link doesn't work, try the master document:
 375    http://docutils.sourceforge.net/spec/rst/reStructuredText.html.
 376
 377 .. _reStructuredText Markup Specification:
 378    ../../spec/rst/reStructuredText.html
 379 .. _post a message: mailto:docutils-users@lists.sourceforge.net
 380 .. _Docutils-Users mailing list:
 381    http://lists.sourceforge.net/lists/listinfo/docutils-users
 382 .. _Docutils project web site: http://docutils.sourceforge.net/