.. _reST-Basics:
**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 :ref:`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* :program:`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. ä.).
.. sidebar:: Querverweis
Weitere Informationen zum Textformat ReST finden sich im Abschnitt :ref:`Thema-Rst`.
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
(:literal:`# * = - ^ " ' : ~ _ + < >`)
**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.
.. note::
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.
- :literal:`#.` 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.
.. admonition:: 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.
.. admonition:: Beispiel: Nummerierte Liste
::
1. Dies ist der erste Punkt
2. Dies ist der zweite Punkt
#. Dieser Punkt wird automatisch nummeriert
3. Dies ist der erste Punkt
4. Dies ist der zweite Punkt
#. 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** (`````):
:samp:`:{Befehl}:\`{Parameter}\``.
.. admonition:: Beispiel: Feldliste
::
Man kann sehr einfach einen Indexeintrag
für den Begriff :index:`Wachteleier` erstellen.
.. important::
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 :kbd:`ß`-
und :kbd:`Backspace`-Taste, über dem Akut (``´``, :kbd:`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
.. admonition:: Weiterführende Informationen
Weitere Informationen zum ReST-Textformat
sowie eine Sammlung von wichtigen Befehlen
findet sich unter :ref:`Thema-Rst`.