Erweiterte Fähigkeiten

Basierend auf <http://docutils.sf.net/rst.html> und http://docutils.sourceforge.net/docs/user/rst/quickref.html. Dank an Tibs (tibs@tibsnjoan.co.uk) and David Goodger (goodger@python.org)

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.

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

Listen-Tabellen sind die einfachste Art um Tabellen zu erzeugen:

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

Einfache Tabellen:

==============        ==============
Titel Spalte 1        Titel Spalte 2
==============        ==============
Inhalt 11              Inhalt 21
Inhalt 12              Inhalt 22
Inhalt 13              Inhalt 23
==============        ==============

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

Folgende Optionen sind typisch:

.. image:: Pfad
:alt: alternativer Text (Text)

Alternativer Text. Eine kurze Beschreibung des Bildes, die von Anwendungen angezeigt wird, die keine Bilder anzeigen können, oder von Anwendungen für Benutzer mit Sehbehinderung gesprochen wird.

:height: (integer or no value)

Dient zum Reservieren von Speicherplatz oder zum vertikalen Skalieren des Bildes. Wenn die Option „scale“ ebenfalls angegeben ist, werden sie kombiniert. Zum Beispiel entspricht eine Höhe von 200px und eine Skala von 50 einer Höhe von 100px ohne Skala.

:width: (Länge oder Verhältnis (%) zur aktuellen Zeilenbreite)

Die Breite des Bildes. Wird verwendet, um Platz zu reservieren oder das Bild horizontal zu skalieren. Wie bei „height“ oben werden sie kombiniert, wenn die Option „scale“ ebenfalls angegeben wird.

:scale: (ganzzahliger Prozentsatz (das Symbol ``%`` ist optional))

Der einheitliche Skalierungsfaktor des Bildes. Die Standardeinstellung ist 100%, d. H. Keine Skalierung.

:align: (``top``, ``middle``, ``bottom``, ``left``, ``center`` oder ``right``)

Die Ausrichtung des Bildes.

Die Werte top, middle und bottom steuern die vertikale Ausrichtung eines Bildes (relativ zur Textbasislinie). Sie sind nur für Inline-Bilder (Ersetzungen) nützlich.

Die Werte left, center und right steuern die horizontale Ausrichtung eines Bildes, sodass das Bild schweben kann und der Text darum herum fließt. Das spezifische Verhalten hängt vom verwendeten Browser oder Exporter ab.

:target: (Text (URI oder Referenzname))

Macht das Bild zu einer Hyperlink-Referenz („anklickbar“). Das Optionsargument kann eine URL (relativ oder absolut) oder ein „Referenzname“ mit einem Unterstrichsuffix (z. B. `ein Name`_) sein.

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.

Boxen

Mittels .. admonition:: können Textboxen erzeugt werden, z. B.:

Besipiel: Textbox mittels admonition

.. admonition:: Das ist ein Titel

        Das ist der Text in der Box

Das ist ein Titel

Das ist der Text in der Box

Neben der generischen Box gibt es spezielle Boxen:

  • „caution“,

  • „danger“,

  • „error“,

  • „hint“,

  • „important“,

  • „note“,

  • „tip“,

  • „warning“

Beispiel: „Danger“

.. danger::

        Das ist eine Gefahr!

Gefahr

Das ist eine Gefahr!

Fußnoten, Verweise und Spezielles

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.

Verweise

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.

Literaturreferenzen

Zu tun

Literaturreferenzen!

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.

Beispiel: Feldliste

Es werden die |StdMVitBedPat| durchgeführt.
Die |StdMVitBedPat| beinhalten fünf verschiedene Maßnahmen.

.. |StdMVitBedPat| replace:: Standardmaßnahmen für vital bedrohte Patienten

Es werden die Standardmaßnahmen für vital bedrohte Patienten durchgeführt. Die Standardmaßnahmen für vital bedrohte Patienten beinhalten fünf verschiedene Maßnahmen.