Das Textformat: Grundlagen

Der Quelltext

Das Projekt „Kompendium des CCCA“ wird in Textdateien im Textformat restructuredText (ReST, reST, RST)1 geschrieben, welche von einem Programm, der Sphinx-Toolchain, in das gewünschte Ausgabeformat (z. B. PDF für den Druck, HTML für Webseiten, ePub für eBooks, …) übersetzt werden.

1

reStructuredText ist ein Nachfolger der früher beschriebenen einfachen Markup-Sprache StructuredText, reST stellt somit eine weiterentwickelte („revised“) Version von StructuredText“ dar.

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.

digraph {

"Datei.rst"
        [
                shape = note,
                color=crimson,
                style=filled,
                fillcolor=white,
                fontcolor=crimson,
                fontname="Source Code Pro",
                label="index.rst",
        ];
"Compiler"
        [
                shape = box3d,
                color=grey,
                style=filled,
                fillcolor=black,
                fontcolor=white,
                fontname="Source Sans Pro",
                label="Compiler\n(Sphinx)",
        ];



"Datei.pdf"
        [
                shape = note,
                color=black,
                style=filled,
                fillcolor=white,
                fontcolor=black,
                fontname="Source Serif Pro",
                label="index.pdf",
        ];

"Datei.html"
        [
                shape = note,
                color=blue,
                style=filled,
                fillcolor=white,
                fontcolor=blue,
                fontname="Source Sans Pro",
                label="index.html",
        ];
"Datei.epub"
        [
                shape = note,
                color=darkgreen,
                style=filled,
                fillcolor=white,
                fontcolor=darkgreen,
                fontname="Source Sans Pro",
                label="index.epub",
        ];

rankdir = TB;

subgraph {
        "Datei.rst" -> "Compiler" -> "Datei.pdf";
        "Compiler" -> "Datei.html";
        "Compiler" -> "Datei.epub";

        # {rank = same; "Datei.rst" ; "Compiler"}
        }
}

Abb. 36 Aus einer Quelltextdatei erzeugt der Compiler unterschiedliche Ausgabedateien und -formate

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. ä.).

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.

Textauszeichnungen: Markup

In ReST bilden aufeinanderfolgende Textzeilen einen Absatz. Absätze werden durch eine oder mehrere Leerzeilen voneinander getrennt. Die Einrückung ist in ReST von großer Bedeutung, daher müssen alle Zeilen desselben Absatzes linksbündig auf die gleiche Einrückungsebene ausgerichtet sein. Eingerückte Zeilen sind dem vorhergehenden nicht- (oder weniger-) eingerückten Text untergeordnet.

Hervorhebungen

Auszeichnungen (Markup) wie zum Beispiel Hervorhebungen erfolgen durch Interpunktionszeichen:

  • Eine 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

Ü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

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

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 Hintergrund: reStructuredText (reST).