.. highlight:: ReST .. index:: single: * single: ** single: Markup single: Absatz single: Einrückung single: Hervorhebung single: Hervorhebung; starke single: Web-Link single: Backslash single: \ .. _Thema-Rst: .. _Rst-Referenz: Referenz: reStructuredText ######################################################################## Basierend auf und http://docutils.sourceforge.net/docs/user/rst/quickref.html. Dank an Tibs (tibs@tibsnjoan.co.uk) and David Goodger (goodger@python.org) .. contents:: Das Textformat :dfn:`reStructuredText` (*reST*, *RST*) ist eng mit der :dfn:`Sphinx-Toolchain` verbunden. Es handelt sich dabei um eine Auszeichnungssprache (Markup) mit dem Ziel, in der reinen Textform besonders lesbar zu sein. Ursprünglich wurde reST vor allem zur Dokumentation der Programmiersprache Python eingesetzt. Sie ist Teil des Docutils-Projekts, welches sich zu einer universell einsetzbaren Textverarbeitungsbibliothek entwickelt und den Export in viele andere Formate (LaTeX, HTML, ePUB, ODT usw.) ermöglicht. Dies macht das System auch für andere Anwendungsbereiche sehr interessant. Basics ************************************************************************ Da die RST-Syntax nur **einfacher Text** (*"Rohtext"*) ist, kann man ein RST-Dokument mit einem *beliebigen Texteditor* verfassen. Man benötigt keine komplexen Textverarbeitungsprogramme wie Microsoft Word, OpenOffice/LibreOffice Writer oder Google Text & Tabellen, welche Formatierungsanweisungen in nicht-menschenlesbarer Form in ihren Dokumenten platzieren. Der Großteil des Inhalts in einem Dokument besteht aus Absatztext. In RST bilden benachbarte oder aufeinanderfolgende Textzeilen einen **Absatz**. Absätze sind durch eine oder mehrere *Leerzeilen voneinander getrennt*. **Einrückungen** sind in RST von *großer* Bedeutung, daher müssen alle Zeilen desselben Absatzes linksbündig auf die *gleiche Einrückungsebene* ausgerichtet sein. Eingerückte Absätze haben einen Bezug zum obigen nicht- (oder weniger-) eingerückten Text. Da unmittelbar aufeinanderfolgende Textzeilen zu einem einheitlichen Absatz zusammengefasst werden, kann an beliebiger Stelle ein einfacher Zeilenumbruch erfolgen. Dies ermöglicht durch Zeilenumbrüche die *logische Struktur* eines Satzes hervorzuheben und Satzteile *visuell zu trennen* ohne dass es Auswirkungen auf die Ausgabe hat. Diese Technik wird als :dfn:`semantischer Zeilenumbruch` bezeichnet. Dadurch wird die Bearbeitung, Versionskontrolle und Nachvollziehbarkein von Änderungen einer Textdatei wesentlich vereinfacht. D. h. man kann (und soll!) *nach jeden Satz*, *jeder Phrase* bzw. *jedem inhaltlich zusammenhängenden Satzteil / Gedanken* einen **Zeilenumbruch** einfügen. Auszeichnungen ("Markup") ************************************************************************ So wie wir beim Sprechen bestimmte Wörter und Sätze hervorheben, können wir sie im Text hervorheben, indem wir sie mit bestimmten **Interpunktionszeichen** **umgeben**. Eine *Hervorhebung* erfolgt mittels eines Sterns (``*``) wie ``*Hervorhebung*``, eine **starke Hervorhebung** mit 2 Sternen (``**`` ), also z. B. ``**starke Hervorhebung**``. Web-Links werden normalerweise automatisch erkannt, z. B. ergibt ``http://www.criticalcare.at`` http://www.criticalcare.at. Beachte: - Verschachtelungen sind *nicht* möglich - Der Text muss unmittelbar dem beginnendem Markup-Zeichen folgen bzw. das beendente Markup-Zeichen muss unmittelbar dem Text folgen: ``* Text*`` wäre falsch - Es muss durch "Nicht-Wort-Zeichen" vom umgebenden Text getrennt werden. Verwenden Sie einen umgekehrten Schrägstrich mit Leerzeichen (``\``), um dies zu umgehen: ``Dasist\ **ein**\ Wort`` ergibt Dasist\ **ein**\ Wort. Ohne dieser Trennung wird die Hervorhebung nicht erkannt: ``Dasist**ein**Wort``: Dasist**ein**Wort Um zu verhindern, dass Interpunktion als Formatierungsmarkup interpretiert wird, muss ein **Backslash** (``\``) vorangestellt werden. Dadurch wird die spezielle Bedeutung von Markup-Zeichen widerrufen. Dies gilt auch für den Backslash selber, ein ``\\`` ergibt einen Backslash (\\). .. index:: single: Überschriften single: Gliederungsebenen Überschriften und Gliederung ************************************************************************ Überschriften werden mit speziellen Zeichen **unterstrichen** (oder *über- und unterstrichen*), ähnlich wie bei einem Schreibmaschinentext. Möglich sind die Zeichen :literal:`= - : ' " ~ ^ _ * + # < >`. Welches Zeichen für welche Gliederungebene verwendet wird ist grundsätzlich egal und wird, sofern über ein Dokument konsequent das gleiche Zeichen für die gleiche Gliederungebene verwendet wird, von Sphinx aufgrund der im Dokument verwendetes Abfolge automatisch erkannt. Empfohlen ist jedoch folgende Abfolge: :: ############################### 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 Unter-/Überstreichung muss mindestens so lang sein wie der Titeltext. .. index:: single: Listen Listen ************************************************************************ Nicht-nummerierte Liste ======================================================================== Aufzählungszeichen sind ``-``, ``*`` oder ``+``. Der fortlaufende Text muss am Aufzählungszeichen plus Einrückung ausgerichtet sein. Eine Leerzeile 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. Nummerierte Listen ======================================================================== Aufzählungszeichen für nummerierte Listen (*Enumeratoren*) sind *arabische Zahlen*, einzelne *Buchstaben* oder *römische Ziffern*, sowie :literal:`#` um automatisch zu nummerieren, jeweils gefolgt von einem *Punkt* (``.``). Listenelemente sollten fortlaufend nummeriert sein, müssen jedoch nicht bei 1 beginnen (obwohl nicht alle Ausgabeprogramme den ersten Index berücksichtigen). .. admonition:: Beispiel: :: 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 Definitions- und Feldlisten ======================================================================== Definitionslisten verknüpfen einen Begriff mit einem Inhalt. Der Begriff ist ein einzeiliger Ausdruck, und die Definition besteht aus einem oder mehreren Absätzen oder Textelementen, die relativ zum Begriff eingerückt sind. Leerzeilen zwischen Begriff und Definition sind nicht zulässig. .. admonition:: Beispiel: Defintionsliste :: Begriff Erklärung Anderer Begriff Eine längere Erklärung. Sie beinhaltet sogar einen weiteren Absatz. Und sogar eine Aufzählung ist möglich: 1. Erstens 2. Zweitens 3. Drittens Begriff Erklärung Anderer Begriff Eine längere Erklärung. Sie beinhaltet sogar einen weiteren Absatz. Und sogar eine Aufzählung ist möglich: 1. Erstens 2. Zweitens 3. Drittens Feldlisten ähneln Definitionlisten. Sie werden vor allem intern zur Angabe von Optionen bei Direktiven verwendet. .. admonition:: Beispiel: Feldliste :: :Feld: Inhalt :Autoren: Hinz, Kunz Weiters danken wir: 1. Erna 2. Resi 3. Zenzi :Feld: Inhalt :Autoren: Hinz, Kunz Weiters danken wir: 1. Erna 2. Resi 3. Zenzi Befehle: *Rollen* und *Direktiven* ************************************************************************ Neben den grundlegenden 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: .. index:: single: Rollen .. _Rollen: Rollen ======================================================================== Rollen sind im Prinzip **Befehle** die *im Textverlauf* angewendet werden. Der Befehl steht zwischen Doppelpunkten (``:``), das Argument zwischen jeweils einem **Accent grave** (`````). :samp:`:{Befehl}:\`{Argument}\`` bzw. :samp:`:{Befehl}:\`{Optionales Argument} <{Argument}>\``. Z. b. ein Querverweis: ``:ref:`Beispiel-Verweis```. .. index:: single: Direktiven .. _Direktiven: 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. .. index:: single: Bilder Bilder ************************************************************************ Bei Bildern unterscheidet man zwischen dem einfachen Bild und dem Bild mit Beschriftung. .. _image: 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: .. rst:directive:: .. image:: Pfad .. rst:directive:option:: alt: alternativer Text :type: 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. .. rst:directive:option:: height :type: 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. .. rst:directive:option:: width :type: 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. .. rst:directive:option:: scale :type: ganzzahliger Prozentsatz (das Symbol ``%`` ist optional) Der einheitliche **Skalierungsfaktor** des Bildes. Die Standardeinstellung ist ``100%``, d. H. Keine Skalierung. .. rst:directive:option:: align :type: ``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. .. rst:directive:option:: target :type: 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. .. _figure: 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. .. index:: single: Boxen Boxen ************************************************************************ Mittels ``.. admonition::`` können Textboxen erzeugt werden, z. B.: .. admonition:: Besipiel: Textbox mittels admonition :: .. admonition:: Das ist ein Titel Das ist der Text in der Box .. admonition:: 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" .. admonition:: Beispiel: "Danger" :: .. danger:: Das ist eine Gefahr! .. danger:: Das ist eine Gefahr! Fußnoten, Verweise und Spezielles ************************************************************************ .. index:: single: Fußnoten 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. .. admonition:: 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 [#Beispiel-Fussnote]_. .. [#Beispiel-Fussnote] Und hier erfolgt die Definition der Fußnote. .. index:: single: Querverweise .. _Beispiel-Querverweis: 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 :ref:`Beispiel-Querverweis`. 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 `. Ein Querverweisziel sieht man in diesem :ref:`Abschnitt `. .. index:: single: Literaturreferenzen Literaturreferenzen ======================================================================== .. todo:: Literaturreferenzen! .. index:: single: Tabellen 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: .. admonition:: Beispiel: Tabelle mit Raster .. code-block:: none +--------------------------------+-------------------------------+ | Ü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 eine zusammengeführte | | | Zelle (vertikal). | | Ich bin ein zweiter Absatz, | | | getrennt durch eine Leerzeile. | Auch hier kann es einen zweiten, | +--------------------------------+ durch eine Leerzeile getrennten | | Ich bin eine andere Zelle. | Absatz geben. | | | | | | Es kann auch: | | | | | | - Aufzählungen | | | - andere **Formatierungen** | | | | | | geben. | +--------------------------------+-----------------------------------+ | Ich bin eine horizontal zusammengeführte Zelle. | +--------------------------------------------------------------------+ Tabelle mit Liste ======================================================================== Listen-Tabellen sind die einfachste Art um Tabellen zu erzeugen: Die Direktive lautet :samp:`.. 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) .. 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) Einfache Tabellen: ======================================================================== .. code-block:: none ============== ============== Titel Spalte 1 Titel Spalte 2 ============== ============== Inhalt 11 Inhalt 21 Inhalt 12 Inhalt 22 Inhalt 13 Inhalt 23 ============== ============== .. index:: single: Kommentar Kommentare ************************************************************************ Jeder Text, der mit ``..`` ohne einer folgenden gültigen Anweisung mit Leerzeilen davor und danach beginnt, ist ein Kommentar. .. index:: single: Ersetzung Ersetzungen ************************************************************************ Substitutionen sind Zeichenfolgen innerhalb zweier ``|``-Zeichen. Andernorts kann für eine Substitution ein Ersetzungstext definiert werden. .. admonition:: 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 |StdMVitBedPat| durchgeführt. Die |StdMVitBedPat| beinhalten fünf verschiedene Maßnahmen. .. |StdMVitBedPat| replace:: Standardmaßnahmen für vital bedrohte Patienten Weiteres **************************** Eine vollständige Auflistung findet sich unter .