Referenz: reStructuredText#

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)

Das Textformat reStructuredText (reST, RST) ist eng mit der Sphinx-Toolchain verbunden. Es handelt sich dabei um eine Auszeichnungssprache (Markup) mit dem Ziel, in der reinen Textform besonders lesbar zu sein. Ursprünglich wurde reST vor allem zur Dokumentation der Programmiersprache Python eingesetzt. Sie ist Teil des Docutils-Projekts, welches sich zu einer universell einsetzbaren Textverarbeitungsbibliothek entwickelt und den Export in viele andere Formate (LaTeX, HTML, ePUB, ODT usw.) ermöglicht. Dies macht das System auch für andere Anwendungsbereiche sehr interessant.

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.

Auszeichnungen („Markup“)#

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.criticalcare.at http://www.criticalcare.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:

1. Dies ist der erste Punkt
2. 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

Befehle: Rollen und Direktiven#

Neben den grundlegenden Formatierungsanweisungen (Markup) gibt es noch sog. Rollen und Direktiven. Im Prinzip handelt es sich bei beiden Varianten um Befehle, die die Möglichkeiten von RST deutlich erweitern. Wichtig ist das Verständnis des grundsätzlichen Schemas dieser Befehle:

Rollen#

Rollen sind im Prinzip Befehle die im Textverlauf angewendet werden. Der Befehl steht zwischen Doppelpunkten (:), das Argument zwischen jeweils einem Accent grave (`).

:Befehl:`Argument` bzw. :Befehl:`Optionales Argument <Argument>`. Z. b. ein Querverweis: :ref:`Beispiel-Verweis`.

Direktiven#

Direktiven sind im Prinzip erweiterte Befehle und erlauben mehr Optionen. Sie werden im Prinzip wie Absätze behandelt, bzw. können auch Absätze enthalten.

Rollen beginnen mit einem .. gefolgt von einem Leerzeichen, gefolgt von einem einem Befehl und schließen mit einem doppelten Doppelpunkt ab, danach kann ein Argument folgen:

.. Befehl:: Argument

Ein konkretes Beospiel wäre z. B. .. figure:: /Pfad/zu/einem/Bild.jpg. Weitere Optionen oder Argumente können eingerückt als Feldliste in den nächsten Zeilen Folgen, weiters können – durch eine Leerzeile getrennt – entsprechend eingerückte Absätze folgen:

.. Befehl:: Argument
        :Option1: Wert
        :Option2: Anderer Wert

        Dies ist ein Absatz

Ein konkretes Beispiel wäre:

.. figure:: /Pfad/zu/einem/Bild.jpg
        :scale: 50 %
        :alt: Alternativer Titel

        Das ist der Titel des Bildes

        Die weiteren Absätze sind Teil der Bild-Legende.

        Sie kann auch mehrere Absätze geben usw.

Bilder#

Bei Bildern unterscheidet man zwischen dem einfachen Bild und dem Bild mit Beschriftung.

Einfaches Bild: image#

Der Befehl .. image:: bindet ein einfaches Bild ein:

.. image:: /Pfad/zu/dem/Bild.jpg

Der Pfad für die Bildquelldatei wird als Argument angegeben. Optional können weitere Optionen angegeben werden, z. B.:

.. image:: /Pfad/zu/dem/Bild.jpg
   :height: 30000px
   :width: 500 px
   :scale: 50 %
   :alt: Alternativer Titel
   :align: center

Folgende Optionen sind typisch:

.. image:: Pfad#
:alt: alternativer Text (Text)#

Alternativer Text. Eine kurze Beschreibung des Bildes, die von Anwendungen angezeigt wird, die keine Bilder anzeigen können, oder von Anwendungen für Benutzer mit Sehbehinderung gesprochen wird.

:height: (integer or no value)#

Dient zum Reservieren von Speicherplatz oder zum vertikalen Skalieren des Bildes. Wenn die Option „scale“ ebenfalls angegeben ist, werden sie kombiniert. Zum Beispiel entspricht eine Höhe von 200px und eine Skala von 50 einer Höhe von 100px ohne Skala.

:width: (Länge oder Verhältnis (%) zur aktuellen Zeilenbreite)#

Die Breite des Bildes. Wird verwendet, um Platz zu reservieren oder das Bild horizontal zu skalieren. Wie bei „height“ oben werden sie kombiniert, wenn die Option „scale“ ebenfalls angegeben wird.

:scale: (ganzzahliger Prozentsatz (das Symbol ``%`` ist optional))#

Der einheitliche Skalierungsfaktor des Bildes. Die Standardeinstellung ist 100%, d. H. Keine Skalierung.

:align: (``top``, ``middle``, ``bottom``, ``left``, ``center`` oder ``right``)#

Die Ausrichtung des Bildes.

Die Werte top, middle und bottom steuern die vertikale Ausrichtung eines Bildes (relativ zur Textbasislinie). Sie sind nur für Inline-Bilder (Ersetzungen) nützlich.

Die Werte left, center und right steuern die horizontale Ausrichtung eines Bildes, sodass das Bild schweben kann und der Text darum herum fließt. Das spezifische Verhalten hängt vom verwendeten Browser oder Exporter ab.

:target: (Text (URI oder Referenzname))#

Macht das Bild zu einer Hyperlink-Referenz („anklickbar“). Das Optionsargument kann eine URL (relativ oder absolut) oder ein „Referenzname“ mit einem Unterstrichsuffix (z. B. `ein Name`_) sein.

Bild mit Beschriftung: figure#

Eine .. figure:: ist im Prinzip ein .. image::, jedoch mit zusätzlicher optionaler Beschreibung (Titel) und Legende. .. figure:: unterstützt alle Optionen von .. image::. Vor dem Beschreibungs-Absatz und vor der Legende müssen Leerzeilen stehen.

.. figure:: /Pfad/zu/einem/Bild.jpg
        :scale: 50 %
        :alt: Alternativer Titel

        Das ist der Titel des Bildes

        Die weiteren Absätze sind Teil der Bild-Legende.

        Sie kann auch mehrere Absätze geben usw.

Boxen#

Mittels .. admonition:: können Textboxen erzeugt werden, z. B.:

Besipiel: Textbox mittels admonition

.. admonition:: Das ist ein Titel

        Das ist der Text in der Box

Das ist ein Titel

Das ist der Text in der Box

Neben der generischen Box gibt es spezielle Boxen:

  • „caution“,

  • „danger“,

  • „error“,

  • „hint“,

  • „important“,

  • „note“,

  • „tip“,

  • „warning“

Beispiel: „Danger“

.. danger::

        Das ist eine Gefahr!

Gefahr

Das ist eine Gefahr!

Fußnoten, Verweise und Spezielles#

Fußnoten#

Fußnoten werden in eckigen Klammern gesetzt, beginnen mit einem # gefolgt von einem Namen; nach der schließenden eckigen Klammer folgt ein Unterstrich: ([#Name]_). Die Nummerierung erfolgt automatisch. In dem Dokument müssen Fußnoten dann auch mittels .. [#Name] definiert werden. Zwecks Übersichtlichkeit empfiehlt es sich, die Fußnoten unmittelbar nach dem Absatz zu definieren.

Beispiel: Fußnote

Das ist ein Absatz mit einer Fußnote [#Beispiel-Fussnote]_.

.. [#Beispiel-Fussnote] Und hier erfolgt die Definition der Fußnote.

Das ist ein Absatz mit einer Fußnote 1.

1

Und hier erfolgt die Definition der Fußnote.

Verweise#

Zuerst muss ein Querverweisziel vor einer Überschrift gesetzt werden:

.. _Beispiel-Querverweis:

Verweise
========

Zuerst muss ein Querverweisziel *vor einer Überschrift* gesetzt werden:

Anschließend kann darauf ein Verweis erfolgen:

Ein Querverweisziel sieht man unter :ref:`Beispiel-Querverweis`.

Ein Querverweisziel sieht man unter Verweise.

Möchte man einen bestimmten Verweistext angezeigt bekommen, anstatt der zum Verweis gehördenen Überschrift, setzt man den Querverweis zwischen < und > und gibt davor den gewünschten Text an:

Ein Querverweisziel sieht man in diesem :ref:`Abschnitt <Beispiel-Querverweis>`.

Ein Querverweisziel sieht man in diesem Abschnitt.

Literaturreferenzen#

Zu tun

Literaturreferenzen!

Tabellen#

Tabelle mit Raster#

Raster-Tabellen sehen im Quelltext am schönsten aus, sind aber schwieriger zu erstellen bzw. auszubessern. Allerdings ist hierbei das Zusammenführen von Zellen möglich.

Im Prinzip werden sie durch „Zeichnen“ mit +, |, - und = erzeugt:

Beispiel: Tabelle mit Raster

+--------------------------------+-------------------------------+
| Überschrift 1                  | Überschrift 2                 |
+================================+===============================+
| Ich bin eine Zelle             | Ich bin eine zusammen-        |
|                                | geführte Zelle (vertikal).    |
| Ich bin ein zweiter Absatz,    |                               |
| getrennt durch eine Leerzeile. | Auch hier kann es einen       |
+--------------------------------+ zweiten, durch eine Leerzeile |
| Ich bin eine andere Zelle.     | getrennten Absatz geben.      |
|                                |                               |
|                                | Es kann auch:                 |
|                                |                               |
|                                | -   Aufzählungen              |
|                                | -   andere **Formatierungen** |
|                                |                               |
|                                | geben.                        |
+--------------------------------+-------------------------------+
| Ich bin eine horizontal zusammengeführte Zelle.                |
+----------------------------------------------------------------+

Überschrift 1

Überschrift 2

Ich bin eine Zelle

Ich bin ein zweiter Absatz, getrennt durch eine Leerzeile.

Ich bin eine zusammengeführte Zelle (vertikal).

Auch hier kann es einen zweiten, durch eine Leerzeile getrennten Absatz geben.

Es kann auch:

  • Aufzählungen

  • andere Formatierungen

geben.

Ich bin eine andere Zelle.

Ich bin eine horizontal zusammengeführte Zelle.

Tabelle mit Liste#

Listen-Tabellen sind die einfachste Art um Tabellen zu erzeugen:

Die Direktive lautet .. list-table:: Tabellentitel, als Optionen sind möglich:

widths

gibt die jeweiligen Spaltenbreiten (in Prozent) an,

header-rows

definiert wieviele Zeilen als Überschrift gerechnet werden,

stub-columns

analog dazu, wie viele Spalten als Zeilentitel gerechnet werden.

Eine neue Zeile wird mittels Stern * begonnen, eine eingerückte, nicht-nummerierte Liste definiert die Spalten.

.. list-table:: Tabellenüberschrift
        :widths: 25 25 25 25
        :header-rows: 1
        :stub-columns: 1

        *       -       Erste Spalte, erste Zeile
                -       Zweite Spalte, erste Zeile
                -       noch immer die erste Zeile
                -       und die letzte (4.)Spalte der 1. Zeile
        *       -       jetzt geht es in die 2. Zeile
                -       usw. (2/2)
                -       usw. (3/2)
                -       usw. (4/2)
        *       -       (1/3)
                -       (2/3)
                -       (3/3)
                -       (4/3)
Tab. 1 Tabellenüberschrift#

Erste Spalte, erste Zeile

Zweite Spalte, erste Zeile

noch immer die erste Zeile

und die letzte (4.)Spalte der 1. Zeile

jetzt geht es in die 2. Zeile

usw. (2/2)

usw. (3/2)

usw. (4/2)

(1/3)

(2/3)

(3/3)

(4/3)

Einfache Tabellen:#

==============        ==============
Titel Spalte 1        Titel Spalte 2
==============        ==============
Inhalt 11              Inhalt 21
Inhalt 12              Inhalt 22
Inhalt 13              Inhalt 23
==============        ==============

Kommentare#

Jeder Text, der mit .. ohne einer folgenden gültigen Anweisung mit Leerzeilen davor und danach beginnt, ist ein Kommentar.

Ersetzungen#

Substitutionen sind Zeichenfolgen innerhalb zweier |-Zeichen. Andernorts kann für eine Substitution ein Ersetzungstext definiert werden.

Beispiel: Feldliste

Es werden die |StdMVitBedPat| durchgeführt.
Die |StdMVitBedPat| beinhalten fünf verschiedene Maßnahmen.

.. |StdMVitBedPat| replace:: Standardmaßnahmen für vital bedrohte Patienten

Es werden die Standardmaßnahmen für vital bedrohte Patienten durchgeführt. Die Standardmaßnahmen für vital bedrohte Patienten beinhalten fünf verschiedene Maßnahmen.

Weiteres#

Eine vollständige Auflistung findet sich unter <http://docutils.sf.net/docs/ref/rst/roles.html>.

Creative Commons Lizenzvertrag Dieses Werk ist lizenziert unter der Creative Commons Namensnennung - Weitergabe unter gleichen Bedingungen 3.0 Österreich Lizenz (CC BY-SA 3.0 AT). Einzelne Beiträge und Medien können abweichend lizensiert sein.