Das Textformat: Funky Stuff

Grundlage für erweiterte Möglichkeiten: Rollen und Direktiven

Neben den bereits vorgestellten einfachen 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

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.

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

Einfacher zu schreiben, dafür weniger übersichtlich sind Tabellen im Listen-Format: 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)

Gliederung

Ein Publikationsprojekt kann in mehrere Dateien aufgeteilt werden, sinnvollerweise geschieht dies anhand der Gliederungebenen (also z. B. der Kapitel oder unterabschnitte). Somit kann z. B. jedes Kapitel in einer eigenen Datei gespeichert werden. Es gibt dann eine Hauptdatei welche mittels der Direktive .. toctree:: Verweise auf andere Dateien enthält:

index.rst

################################
Das ist ein Titel
################################

.. toctree::

        Kapitel-1/index.rst

Dieser Text erscheint nach dem 1. Kapitel.

Der Compiler Sphinx fügt beim übersetzen an der entsprechenden Stelle die jeweilige(n) Datei(en) (hier Kapitel-1/index.rst, aber es könnte auch eine Kapitel-2/index.rst und eine Kapitel-3/index.rst geben) ein.

Eine Kapitel_Datei kann wiederum Verweise auf untergeordnete Abschnitte beinhalten:

Kapitel-1/index.rst

################################
Das ist Kapitel 1
################################

Dieses Kapitel ist das erste seiner Art.
Es werden im FOlgenden Thema 1 und Thema 2
behandelt.

.. toctree::

        Thema-1/index.rst
        Thema-2/index.rst

Sonderzeichen

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.

Quellenangaben

Zu tun

Literaturreferenzen!

Index-Einträge

Querverweise

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.

Formeln und Mathematik

Besondere Textauszeichnungen

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.