| [FrontPage] [TitleIndex] [WordIndex]

# HelpOnParsers/ReStructuredText/RstPrimer

Rendering of reStructured text is not possible, please install docutils.

    A ReStructuredText Primer
    =========================

    :Author: Richard Jones
    :Version: $Revision: 1.17 $
    :Copyright: This document has been placed in the public domain.

    .. contents::

    The text below contains links that look like "(quickref__)".  These
    are relative links that point to the `Quick reStructuredText`_ user
    reference.  If these links don't work, please refer to the `master
    quick reference`_ document.

    __
    .. _Quick reStructuredText: quickref.html
    .. _master quick reference:
       http://docutils.sourceforge.net/docs/user/rst/quickref.html

    Structure
    ---------

    From the outset, let me say that "Structured Text" is probably a bit
    of a misnomer.  It's more like "Relaxed Text" that uses certain
    consistent patterns.  These patterns are interpreted by a HTML
    converter to produce "Very Structured Text" that can be used by a web
    browser.

    The most basic pattern recognised is a **paragraph** (quickref__).
    That's a chunk of text that is separated by blank lines (one is
    enough).  Paragraphs must have the same indentation -- that is, line
    up at their left edge.  Paragraphs that start indented will result in
    indented quote paragraphs. For example::

      This is a paragraph.  It's quite
      short.

         This paragraph will result in an indented block of
         text, typically used for quoting other text.

      This is another one.

    Results in:

      This is a paragraph.  It's quite
      short.

         This paragraph will result in an indented block of
         text, typically used for quoting other text.

      This is another one.

    __ quickref.html#paragraphs

    Text styles
    -----------

    (quickref__)

    __ quickref.html#inline-markup

    Inside paragraphs and other bodies of text, you may additionally mark
    text for *italics* with "``*italics*``" or **bold** with
    "``**bold**``".

    If you want something to appear as a fixed-space literal, use
    "````double back-quotes````".  Note that no further fiddling is done
    inside the double back-quotes -- so asterisks "``*``" etc. are left
    alone.

    If you find that you want to use one of the "special" characters in
    text, it will generally be OK -- reStructuredText is pretty smart.
    For example, this * asterisk is handled just fine.  If you actually
    want text \*surrounded by asterisks* to **not** be italicised, then
    you need to indicate that the asterisk is not special.  You do this by
    placing a backslash just before it, like so "``\*``" (quickref__), or
    by enclosing it in double back-quotes (inline literals), like this::

        ``\*``

    __ quickref.html#escaping

    Lists
    -----

    Lists of items come in three main flavours: **enumerated**,
    **bulleted** and **definitions**.  In all list cases, you may have as
    many paragraphs, sublists, etc. as you want, as long as the left-hand
    side of the paragraph or whatever aligns with the first line of text
    in the list item.

    Lists must always start a new paragraph -- that is, they must appear
    after a blank line.

    **enumerated** lists (numbers, letters or roman numerals; quickref__)
      __ quickref.html#enumerated-lists

      Start a line off with a number or letter followed by a period ".",
      right bracket ")" or surrounded by brackets "( )" -- whatever you're
      comfortable with.  All of the following forms are recognised::

        1. numbers

        A. upper-case letters
           and it goes over many lines

           with two paragraphs and all!

        a. lower-case letters

           3. with a sub-list starting at a different number
           4. make sure the numbers are in the correct sequence though!

        I. upper-case roman numerals

        i. lower-case roman numerals

        (1) numbers again

        1) and again

      Results in (note: the different enumerated list styles are not
      always supported by every web browser, so you may not get the full
      effect here):

      1. numbers

      A. upper-case letters
         and it goes over many lines

         with two paragraphs and all!

      a. lower-case letters

         3. with a sub-list starting at a different number
         4. make sure the numbers are in the correct sequence though!

      I. upper-case roman numerals

      i. lower-case roman numerals

      (1) numbers again

      1) and again

    **bulleted** lists (quickref__)
      __ quickref.html#bullet-lists

      Just like enumerated lists, start the line off with a bullet point
      character - either "-", "+" or "*"::

        * a bullet point using "*"

          - a sub-list using "-"

            + yet another sub-list

          - another item

      Results in:

      * a bullet point using "*"

        - a sub-list using "-"

          + yet another sub-list

        - another item

    **definition** lists (quickref__)
      __ quickref.html#definition-lists

      Unlike the other two, the definition lists consist of a term, and
      the definition of that term.  The format of a definition list is::

        what
          Definition lists associate a term with a definition.

        *how*
          The term is a one-line phrase, and the definition is one or more
          paragraphs or body elements, indented relative to the term.
          Blank lines are not allowed between term and definition.

      Results in:

      what
        Definition lists associate a term with a definition.

      *how*
        The term is a one-line phrase, and the definition is one or more
        paragraphs or body elements, indented relative to the term.
        Blank lines are not allowed between term and definition.

    Preformatting (code samples)
    ----------------------------
    (quickref__)

    __ quickref.html#literal-blocks

    To just include a chunk of preformatted, never-to-be-fiddled-with
    text, finish the prior paragraph with "``::``".  The preformatted
    block is finished when the text falls back to the same indentation
    level as a paragraph prior to the preformatted block.  For example::

      An example::

          Whitespace, newlines, blank lines, and all kinds of markup
            (like *this* or \this) is preserved by literal blocks.
        Lookie here, I've dropped an indentation level
        (but not far enough)

      no more example

    Results in:

      An example::

          Whitespace, newlines, blank lines, and all kinds of markup
            (like *this* or \this) is preserved by literal blocks.
        Lookie here, I've dropped an indentation level
        (but not far enough)

      no more example

    Note that if a paragraph consists only of "``::``", then it's removed
    from the output::

      ::

          This is preformatted text, and the
          last "::" paragraph is removed

    Results in:

    ::

        This is preformatted text, and the
        last "::" paragraph is removed

    Sections
    --------

    (quickref__)

    __ quickref.html#section-structure

    To break longer text up into sections, you use **section headers**.
    These are a single line of text (one or more words) with adornment: an
    underline alone, or an underline and an overline together, in dashes
    "``-----``", equals "``======``", tildes "``~~~~~~``" or any of the
    non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you
    feel comfortable with.  An underline-only adornment is distinct from
    an overline-and-underline adornment using the same character.  The
    underline/overline must be at least as long as the title text.  Be
    consistent, since all sections marked with the same adornment style
    are deemed to be at the same level::

      Chapter 1 Title
      ===============

      Section 1.1 Title
      -----------------

      Subsection 1.1.1 Title
      ~~~~~~~~~~~~~~~~~~~~~~

      Section 1.2 Title
      -----------------

      Chapter 2 Title
      ===============

    This results in the following structure, illustrated by simplified
    pseudo-XML::

        <section>
            <title>
                Chapter 1 Title
            <section>
                <title>
                    Section 1.1 Title
                <section>
                    <title>
                        Subsection 1.1.1 Title
            <section>
                <title>
                    Section 1.2 Title
        <section>
            <title>
                Chapter 2 Title

    (Pseudo-XML uses indentation for nesting and has no end-tags.  It's
    not possible to show actual processed output, as in the other
    examples, because sections cannot exist inside block quotes.  For a
    concrete example, compare the section structure of this document's
    source text and processed output.)

    Note that section headers are available as link targets, just using
    their name.  To link to the Lists_ heading, I write "``Lists_``".  If
    the heading has a space in it like `text styles`_, we need to quote
    the heading "```text styles`_``".

    Document Title / Subtitle
    `````````````````````````

    The title of the whole document is distinct from section titles and
    may be formatted somewhat differently (e.g. the HTML writer by default
    shows it as a centered heading).

    To indicate the document title in reStructuredText, use a unique adornment
    style at the beginning of the document.  To indicate the document subtitle,
    use another unique adornment style immediately after the document title.  For
    example::

        ================
         Document Title
        ================
        ----------
         Subtitle
        ----------

        Section Title
        =============

        ...

    Note that "Document Title" and "Section Title" above both use equals
    signs, but are distict and unrelated styles.  The text of
    overline-and-underlined titles (but not underlined-only) may be inset
    for aesthetics.

    Images
    ------

    (quickref__)

    __ quickref.html#directives

    To include an image in your document, you use the the ``image`` directive__.
    For example::

      .. image:: images/biohazard.png

    results in:

    .. image:: images/biohazard.png

    The ``images/biohazard.png`` part indicates the filename of the image
    you wish to appear in the document. There's no restriction placed on
    the image (format, size etc).  If the image is to appear in HTML and
    you wish to supply additional information, you may::

      .. image:: images/biohazard.png
         :height: 100
         :width: 200
         :scale: 50
         :alt: alternate text

    See the full `image directive documentation`__ for more info.

    __ ../../ref/rst/directives.html
    __ ../../ref/rst/directives.html#images

    What Next?
    ----------

    This primer introduces the most common features of reStructuredText,
    but there are a lot more to explore.  The `Quick reStructuredText`_
    user reference is a good place to go next.  For complete details, the
    `reStructuredText Markup Specification`_ is the place to go [#]_.

    Users who have questions or need assistance with Docutils or
    reStructuredText should `post a message`_ to the `Docutils-Users
    mailing list`_.  The `Docutils project web site`_ has more
    information.

    .. [#] If that relative link doesn't work, try the master document:
       http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.

    .. _reStructuredText Markup Specification:
       ../../ref/rst/restructuredtext.html
    .. _post a message: mailto:docutils-users@lists.sourceforge.net
    .. _Docutils-Users mailing list:
       http://lists.sourceforge.net/lists/listinfo/docutils-users
    .. _Docutils project web site: http://docutils.sourceforge.net/

2007-07-30 15:45