Grundlagen und einfache Formatierungen („Markup“)

Basierend auf <http://docutils.sf.net/rst.html> und http://docutils.sourceforge.net/docs/user/rst/quickref.html. Dank an Tibs (tibs@tibsnjoan.co.uk) and David Goodger (goodger@python.org)

Basics

Da die RST-Syntax nur einfacher Text („Rohtext“) ist, kann man ein RST-Dokument mit einem beliebigen Texteditor verfassen. Man benötigt keine komplexen Textverarbeitungsprogramme wie Microsoft Word, OpenOffice/LibreOffice Writer oder Google Text & Tabellen, welche Formatierungsanweisungen in nicht-menschenlesbarer Form in ihren Dokumenten platzieren.

Der Großteil des Inhalts in einem Dokument besteht aus Absatztext. In RST bilden benachbarte oder aufeinanderfolgende Textzeilen einen Absatz. Absätze sind durch eine oder mehrere Leerzeilen voneinander getrennt.

Einrückungen sind in RST von großer Bedeutung, daher müssen alle Zeilen desselben Absatzes linksbündig auf die gleiche Einrückungsebene ausgerichtet sein. Eingerückte Absätze haben einen Bezug zum obigen nicht- (oder weniger-) eingerückten Text.

Da unmittelbar aufeinanderfolgende Textzeilen zu einem einheitlichen Absatz zusammengefasst werden, kann an beliebiger Stelle ein einfacher Zeilenumbruch erfolgen. Dies ermöglicht durch Zeilenumbrüche die logische Struktur eines Satzes hervorzuheben und Satzteile visuell zu trennen ohne dass es Auswirkungen auf die Ausgabe hat. Diese Technik wird als semantischer Zeilenumbruch bezeichnet. Dadurch wird die Bearbeitung, Versionskontrolle und Nachvollziehbarkein von Änderungen einer Textdatei wesentlich vereinfacht. D. h. man kann (und soll!) nach jeden Satz, jeder Phrase bzw. jedem inhaltlich zusammenhängenden Satzteil / Gedanken einen Zeilenumbruch einfügen.

So wie wir beim Sprechen bestimmte Wörter und Sätze hervorheben, können wir sie im Text hervorheben, indem wir sie mit bestimmten Interpunktionszeichen umgeben. Eine Hervorhebung erfolgt mittels eines Sterns (*) wie *Hervorhebung*, eine starke Hervorhebung mit 2 Sternen (** ), also z. B. **starke Hervorhebung**. Web-Links werden normalerweise automatisch erkannt, z. B. ergibt http://www.criticalcareclub.at http://www.criticalcareclub.at.

Beachte:

  • Verschachtelungen sind nicht möglich

  • Der Text muss unmittelbar dem beginnendem Markup-Zeichen folgen bzw. das beendente Markup-Zeichen muss unmittelbar dem Text folgen: * Text* wäre falsch

  • Es muss durch „Nicht-Wort-Zeichen“ vom umgebenden Text getrennt werden. Verwenden Sie einen umgekehrten Schrägstrich mit Leerzeichen (\), um dies zu umgehen: Dasist\ **ein**\ Wort ergibt DasisteinWort.

    Ohne dieser Trennung wird die Hervorhebung nicht erkannt: Dasist**ein**Wort: Dasist**ein**Wort

Um zu verhindern, dass Interpunktion als Formatierungsmarkup interpretiert wird, muss ein Backslash (\) vorangestellt werden. Dadurch wird die spezielle Bedeutung von Markup-Zeichen widerrufen. Dies gilt auch für den Backslash selber, ein \\ ergibt einen Backslash (\).

Überschriften und Gliederung

Überschriften werden mit speziellen Zeichen unterstrichen (oder über- und unterstrichen), ähnlich wie bei einem Schreibmaschinentext. Möglich sind die Zeichen = - : ' " ~ ^ _ * + # < >. Welches Zeichen für welche Gliederungebene verwendet wird ist grundsätzlich egal und wird, sofern über ein Dokument konsequent das gleiche Zeichen für die gleiche Gliederungebene verwendet wird, von Sphinx aufgrund der im Dokument verwendetes Abfolge automatisch erkannt. Empfohlen ist jedoch folgende Abfolge:

###############################
Gliederungsebene 1 (z.B. Teil)
###############################

**********************************
Gliederungsebene 2 (z.B. Kapitel)
**********************************

Gliederungsebene 3 (z.B. Abschnitt)
====================================

Gliederungsebene 4 (z.B. Unterabschnitt)
-----------------------------------------

Gliederungsebene 5
^^^^^^^^^^^^^^^^^^

Gliederungsebene 6
""""""""""""""""""

Die Unter-/Überstreichung muss mindestens so lang sein wie der Titeltext.

Listen

Nicht-nummerierte Liste

Aufzählungszeichen sind -, * oder +. Der fortlaufende Text muss am Aufzählungszeichen plus Einrückung ausgerichtet sein.

Eine Leerzeile vor dem ersten und nach dem letzten Punkt einer Gliederungsebene erforderlich, sowie optional zwischen den Elementen möglich.

Beispiel: Nicht-nummerierte Liste

-       Dies ist Punkt 1
-       Dies ist Punkt 2
-       Punkt 3 ist deutlich länger

        Er umfasst auch einen zweiten Absatz,
        welcher entsprechend eingerückt ist.

        -       Punkt 4 zeigt, dass man durch
                Einrückung die Gliederungsebene
                beeinflussen kann.

ergibt:

  • Dies ist Punkt 1

  • Dies ist Punkt 2

  • Punkt 3 ist deutlich länger

    Er umfasst auch einen zweiten Absatz, welcher entsprechend eingerückt ist.

    • Punkt 4 zeigt, dass man durch Einrückung die Gliederungsebene beeinflussen kann.

Nummerierte Listen

Aufzählungszeichen für nummerierte Listen (Enumeratoren) sind arabische Zahlen, einzelne Buchstaben oder römische Ziffern, sowie # um automatisch zu nummerieren, jeweils gefolgt von einem Punkt (.). Listenelemente sollten fortlaufend nummeriert sein, müssen jedoch nicht bei 1 beginnen (obwohl nicht alle Ausgabeprogramme den ersten Index berücksichtigen).

Beispiel:

3. Dies ist der erste Punkt
4. Dies ist der zweite Punkt
#. Dieser Punkt wird automatisch nummeriert
  1. Dies ist der erste Punkt

  2. Dies ist der zweite Punkt

  3. Dieser Punkt wird automatisch nummeriert

Definitions- und Feldlisten

Definitionslisten verknüpfen einen Begriff mit einem Inhalt.

Der Begriff ist ein einzeiliger Ausdruck, und die Definition besteht aus einem oder mehreren Absätzen oder Textelementen, die relativ zum Begriff eingerückt sind. Leerzeilen zwischen Begriff und Definition sind nicht zulässig.

Beispiel: Defintionsliste

Begriff
        Erklärung

Anderer Begriff
        Eine längere Erklärung.

        Sie beinhaltet sogar einen weiteren Absatz.
        Und sogar eine Aufzählung ist möglich:

        1. Erstens
        2. Zweitens
        3. Drittens
Begriff

Erklärung

Anderer Begriff

Eine längere Erklärung.

Sie beinhaltet sogar einen weiteren Absatz. Und sogar eine Aufzählung ist möglich:

  1. Erstens

  2. Zweitens

  3. Drittens

Feldlisten ähneln Definitionlisten. Sie werden vor allem intern zur Angabe von Optionen bei Direktiven verwendet.

Beispiel: Feldliste

:Feld:
        Inhalt

:Autoren:
        Hinz, Kunz

        Weiters danken wir:

        1. Erna
        2. Resi
        3. Zenzi
Feld

Inhalt

Autoren

Hinz, Kunz

Weiters danken wir:

  1. Erna

  2. Resi

  3. Zenzi