Struktur

Das grundlegende Strukturelement ist ein Paragraph (quickref). Es handelt sich um eine Textpassage, die durch eine Leerzeile von anderen Textpassagen getrennt wird. Paragraphen müssen die gleiche Einrücktiefe haben -- d.h. die gleiche Anzahl an Leerzeichen auf der linken Seite. Paragraphen stärkerer Einrückung erzeugen einen eingerückten Block. Beispiel:

Dies ist ein Paragraph.  Er ist sehr 
kurz.

   Dieser Paragraph erzeugt einen eingerückten Textblock. 
   Üblicher Weise wird diese Textauszeichnung für Zitate genommen.

Dies ist ein weiterer Paragraph.

Wird wie folgt dargestellt:

Dies ist ein Paragraph. Er ist sehr kurz.

Dieser Paragraph erzeugt einen eingerückten Textblock. Üblicher Weise wird diese Textauszeichnung für Zitate genommen.

Dies ist ein weiterer Paragraph.

Textstile

(quickref)

Innerhalb von Paragraphen und anderen Textblocken läßt sich Text noch kursiv durch "*kursiv*" oder fett durch "**fett**" auszeichen.

Wenn etwas als Schrift mit fester Zeichenbreite dargestellt werden soll, nimmt man "``zwei öffnende einfache Anführungszeichen``". Darin wird keine weitere Textauszeichnung wirksam -- Sternchen "*" u.a bleiben erhalten.

Sofern man eines dieser Spezialzeichen im laufenden Text benötigt, wird es in der Regel auch richtig angezeigt. Beispielsweise wird dieses * Sternchen ohne weiteres behandelt. Möchte man hingegen das Text der *von Sternchen eingeschlossen ist* nicht kursivieren, dann muß man anzeigen, daß das Sternchen kein Spezialzeichen ist. Das macht man in dem man einen Backslash davor setzt, etwa "\*" (quickref), oder man schließt es in zwei öffnende einfache Anführungszeichen ein:

``\*``

Listen

Aufzählungen in Listenform gibt es in drei Haupttypen: geordnete Listen, ungeordnete Listen und Definitionslisten. In jedem dieser Fälle können beliebig viele Paragraphen, Unterlisten, u.a. gesetzt werden, solange die Einrücktiefe der Paragraphen ... mit der des ersten Listeneintrags übereinstimmt.

Jede Liste muss mit einem neuen Paragraphen eröffnet werden -- das bedeutet, sie folgen auf eine Leerzeile.

Geordnete Listen (Nummern, Buchstaben oder Römische Zahlen; quickref)

Beginnen Sie eine Zeile mit einer Nummer oder einem Buchstaben gefolgt von einem Punkt ".", einer schließenden runden Klammer ")" oder von runden Klammern umgeben "( )" -- so wie Sie es benötigen. Alle folgenden Notationen werden unterstützt:

1. Zahlen

A. Großbuchstaben
   wobei der Listeneintrag über mehrere Zeilen gehen kann

   nötigenfalls sogar über mehrere Paragraphen!

a. Kleinbuchstaben

   1 mit einer Unterliste und neuer Zählung

   2 wobei die Zählfolge unbedingt einzuhalten ist!

I. Großgeschriebene Römische Zahlen

i. Kleingeschrieben Römische Zahlen

(1) Weitere Zahlen

1) und noch mehr Zahlen

Wird wie folgt dargestellt (Anmerkung: die verschiedenen Stile geordneter Listen werden nicht von allen Browser unterstützt. Daher könnte es in folgender Anzeige eine mangelnde Differenzierung geben):

1. Zahlen

1. Großbuchstaben wobei der Listeneintrag über mehrere Zeilen gehen kann

   nötigenfalls sogar über mehrere Paragraphen!

1. Kleinbuchstaben

   1 mit einer Unterliste und neuer Zählung

   2 wobei die Zählfolge unbedingt einzuhalten ist!

1. Großgeschriebene Römische Zahlen

1. Kleingeschrieben Römische Zahlen

1. Weitere Zahlen

1. und noch mehr Zahlen

Ungeordnete Listen (quickref)

Ungeordnete Listen beginnen mit einem Sonderzeichen - entweder "-", "+" oder "*":

* ein Punkt "*"

  - eine Unterliste eingeleitet durch "-"

    + eine weitere Unterliste

  - ein weiterer Anstrich

Wird wie folgt dargestellt:

• ein Punkt "*"
  • eine Unterliste eingeleitet durch "-"
    • eine weitere Unterliste
  • ein weiterer Anstrich

Definitionslisten (quickref)

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.

Vorformatierter Text

(quickref)

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

Gliederung

(quickref)

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 overline 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 Listen heading, I write "Listen_". If the heading has a space in it like Textstile, we need to quote the heading "`Textstile`_".

To indicate the document title, 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" 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.

Bilder

(quickref)

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

.. image:: images/biohazard.png

results in:

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.

Wie geht es weiter?

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 [1].

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.