restructuredText: Das Textformat#

reStructuredText (reST) ist das Format bzw. die Auszeichnungssprache für den Quelltext der Text-Inhalte des Kompendiums des CCCA. Diese Inhalte werden von Sphinx in das gewünschte Ausgabeformat (PDF, Webseiten, E-Book, …) übersetzt.

Grundlegendes#

Die Quelltext-Dateien sind Roh- bzw. Klartext-Dateien, d. h. sie beinhalten ausschließlich Zeichen, keine direkten Formatierunginformationen oder andere Objekte (wie beispielsweise Bilder). Sie ähneln somit einem mittels einer Schreibmaschine erstellten Dokument und weniger einem Word™-Dokument. Um Formatierungen, Bilder etc. einzufügen müssen die Textdateien in einem bestimmten Format erstellt werden, welches Befehle definiert, die bewirken, dass bei der Übersetzung in das Ausgabeformat durch den Compiler Sphinx die passenden Formatierungen, Bilder u. ä. eingefügt werden. Dieses Textformat wird restructuredText, abgekürzt ResT oder RST, genannt.

ResT ist einerseits weitgehend simpel zu lesen und ähnelt oft der Art und Weise wie wir gewohnt sind einen Schreibmaschinentext zu formatieren. Andererseits ermöglicht ResT den fortgeschrittenen Anwender (das wären in unserem Fall die Reaktuere bzw. technischen Mitarbeiter) weitreichende und für eine professionelle Publikation notwendige Möglichkeiten (Index-Einträge, Querverweise u. ä.).

Querverweis

Weitere Informationen zum Textformat ReST finden sich im Abschnitt Referenz: reStructuredText.

reST definiert Formatierungen u. ä. durch Auszeichnungen (Markup) und Befehle (Rollen, Direktiven). Für den Autor reicht es normalerweise, sich lediglich mit dem Markup zu beschäftigen und die weiterführenden Möglichkeiten den technischen Mitarbeitern zu überlassen.

Einrückungen und Absätze#

Absätze werden durch eine oder mehrere Leerzeilen getrennt. Einfache Zeilenumbrüche haben dabei keine Auswirekungen.

Einrückungen sind von großer Bedeutung. Alle Zeilen desselben Absatzes müssen linksbündig gleich eingerückt sein. Eingerückte Zeilen sind dem vorhergehenden nicht- (oder weniger-) eingerückten Text untergeordnet.

Textauszeichnungen: Markup#

Hervorhebungen#

Hervorhebungen erfolgen durch vor- und nachgestellte Sterne:

  • Eine einfache Hervorhebung erfolgt mittels eines Sterns (*) wie *Hervorhebung*,

  • eine starke Hervorhebung mit 2 Sternen (** ), also z. B. **starke Hervorhebung**.

Der Text muss unmittelbar dem beginnendem Markup-Zeichen folgen bzw. das beendente Markup-Zeichen muss unmittelbar dem Text folgen (* Text* wäre falsch). Verschachtelungen sind dabei leider nicht möglich.

Überschriften und Gliederungsebenen#

Überschriften werden mit speziellen Zeichen (# * = - ^ " ' : ~ _ + < >) unterstrichen (oder über- und unterstrichen), ähnlich wie bei Schreibmaschinentext. Die Unter-/Überstreichung muss dabei mindestens so lang wie der Titeltext sein:

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 Hierarchie der Zeichen, d. h. welches Zeichen für welche Gliederungsebene steht, ergibt sich dynamisch daraus, in welcher Reihenfolge die Zeichen im Dokument zuerst verwendet werden. Die Bedeutung ist kann somit vom Autor grundsätzlich frei gewählt, muss aber konsequent innerhalb der Datei beibehalten werden.

Bemerkung

Es darf keine Lücke zwischen Gliederungsebenen geben, d. h. auf Ebene 2 darf nicht Ebene 4 folgen usw.

Listen#

Listen werden mittels

  • Aufzählungszeichen (-, * oder + für nicht-nummerierte Listen, oder

  • arabische Zahlen mit folgendem Punkt (1.) für nummerierte Listen bzw.

  • #. für automatisch nummerierte Listen

vor jedem Listeneintrag, gefolgt von einer Einrückung, bewerkstelligt. Der fortlaufende Text muss am Aufzählungszeichen plus Einrückung ausgerichtet sein.

Die Einrückung vor dem Aufzählungszeichen entscheidet über die Gliederungsebene (Einrückungen sind in ReST von großer Bedeutung!). Eine Leerzeile ist 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.

Beispiel: Nummerierte Liste

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

Befehle: Rollen und Direktiven#

Mit dem Markup wäre die wesentliche Basisfunktionalität zur Texterstellung abgedeckt. ReST und Sphinx bieten jedoch noch weitere, unzählige Möglichkeiten um Text zu formatieren, Vorgänge zu automatisieren (z. B. die Erstellung von Verzeichnissen, Fußnoten, …) oder Objekte wie Bilder einzufügen. Dafür gibt es Spezielle Befehle. Befehle können Parameter (z. B. den Pfad zu einer Bild-Datei) und weitere Optionen (z. B. die Soll-Größe eines Bildes oder dessen Beschriftung) berücksichtigen.

Man unterscheidet zwischen einfachen Befehlen (Rollen), welche im Textverlauf angewendet werden, und komplexeren, mehrzeiligen Direktiven, welche in der Regel umfangreichere Optionen ermöglichen.

Bei einfachen Befehlen (Rollen) steht der Befehl zwischen zwei Doppelpunkten (:), der Parameter zwischen zwei Accent grave (`): :Befehl:`Parameter`.

Beispiel: Feldliste

Man kann sehr einfach einen Indexeintrag
für den Begriff :index:`Wachteleier` erstellen.

Wichtig

Der Accent grave (Gravis, `) ist ein eigenständiges Zeichen und nicht mit einem Anführungsstrich bzw. Apostroph gleichzusetzen!

Auf deutschen Tastaturen befindet er sich zwischen der ß- und Backspace-Taste, über dem Akut (´, Shift + ´).

Direktiven benötigen einen eigenen Absatz und haben die Form:

.. Befehl:: Parameter

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

.. 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 umfassen

Weiterführende Informationen

Weitere Informationen zum ReST-Textformat sowie eine Sammlung von wichtigen Befehlen findet sich unter Referenz: reStructuredText.

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.