.. _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`.