Was ist ReStructuredText?

ReStructuredText ist ein leicht lesbares Textauszeichnungsverfahren und Verarbeitungs-System. Es eignet sich für EMails, Programm-Dokumentationen, um schnell einfache Web-Seiten zu erzeugen und für für sich stehende Dokumente. ReStructuredText ist erweiterbar auf spezielle Anwendungsgebiete. Mit ReStructuredText wurde das aus Zope bekannte Textauszeichungsverfahren StructuredText formal spezifiziert und neu implementiert.

Die Auszeichnung (engl. markup) mit ReStructuredText wird von Menschen, die neu auf Wikis stossen, oft als natürlicher und einfacher zu erlernen empfunden.

ReStructuredText Parser

Installation

Bevor ReStructuredText benutzt werden kann, muss das Python docutils Paket installiert sein, welches die von MoinMoin für ReStructuredText benötigten Funktionen zur Verfügung stellt.

Die benötigte Version des docutils-Paketes hängt von der MoinMoin Version ab. Wenn Du diesen Text im Rahmen Deiner MoinMoin Installation liest, hast wahrscheinlich MoinMoin 1.5 oder neuer installiert, was zur Zeit (Januar 2006) die Version docutils 0.4.0 oder neuer oder einen aktuellen Schnappschuß von 0.3.10 voraussetzt. Unter Linux ist docutils wahrscheinlich als Teil der Linux-Distribution bereits vorhanden. Zum Beispiel in Debian GNU/Linux reicht es aus das Kommando apt-get install python-docutils auszuführen. Andere Distributionen benutzen andere Methoden um Pakete zu installieren: Siehe Dokumentation der Linux Distribution.

Der Parser in MoinMoin

Der Parser-Baustein bietet die gleichen Möglichkeiten wie der in docutils enthaltene HTML Generator (engl. writer). Allerdings mussten für die Integration in MoinMoin einige Aspekte geringfügig modifiziert werden. Diese Bereiche werden weiter unten skizziert.

ReST in MoinMoin benutzen

Beispiel

Dies ist ein sehr einfaches Beispiel. Falls das Wort "sehr" im vorigen Satz in zwei Sternchen eingeschlossen erscheint, dann wurde der Modul docutils nicht richtig installiert (oder sogar ganz vergessen). Wenn der Modul docutils vorhanden ist, wird das Wort kursiv dargestellt und dieser Absatz wird nicht im speziellen Quelltext-Format ausgegeben, sondern wie ein normaler Teil der Seite.

Unbekannte Verweisziele

Verweise auf unbekannte Ziele werden benutzt, um neue Wiki-Seiten zu erzeugen. Normalerweise würde ein Verweis z.B. auf eine nicht vorhandene Überschrift in ReStructuredText einen Fehler hervor rufen. Ein Beispiel:

{{{ #!rst

Hier ist ein Verweis auf eine MoinMoin Seite namens NochNeSeite_. }}}

Hier ist ein Verweis auf eine MoinMoin Seite namens NochNeSeite.

Das obige enthält einen ReStructuredText Verweis auf "NochNeSeite". Dieser Verweis würde normalerweise einen unknown target Fehler im docutils Parser hervor rufen.

Unterstützung MoinMoin spezifischer Verweise

MoinMoin-specific link schemes are supported when used in a reStructuredText explicit hyperlink target. For example:

{{{ #!rst

Here is a link to a page attachment.

attachment:Attachment.zip }}}

Here is a link to a page Attachment.zip.

The above creates a link to an attachment named Attachment.zip. If the attachment for the page does not exist, the link text will be replaced with the typical MoinMoin replacement text for uploading an attachment. Supported MoinMoin-specific link schemes are:

wiki:
attachment:
inline:
drawing:

Bilder einfügen

Docutils Bilddirektiven, die keine URLs sind, werden in MoinMoin inline:-Verweise umgewandelt. Dadurch können Bilder in das Dokument eingefügt werden. Falls das Bild nicht existiert, wird statt dessen die normale MoinMoin meldung zum Hochladen eines Bildes angezeigt. Ein Beispiel:

{{{ #!rst

Hier das Foto, was ich gestern aufgenommen habe |foto|

.. |foto| image:: Gestern.jpg }}}

Hier das Foto, was ich gestern aufgenommen habe

Das obige ersetzt |foto| durch das Bild "Gestern.jpg".

Experimentelle Möglichkeiten

Die include und macro Direktiven werden als experimentell angesehen, da sie nicht sonderlich getestet wurden. Es wird erwartet, dass sie funktionieren, sie wurden aber noch nicht umfassend benutzt.

Include Unterstützung

Die ReStructuredText include Direktive wird mit einigen Einschränkungen unterstützt.

Die include Anweisung erlaubt das Einfügen von Seiten aus demselben Wiki (ausgenommen Dateianhänge). Auf diese Weise eingefügte Seiten müssen dann aber auch mit Hilfe von ReStructuredText ausgezeichnet sein. Mit MoinMoin Auszeichnung versehene Seiten würden unpassend formatiert ausgegeben. Zum Beispiel das folgende würde die Seiten kopf und fuss um den Inhalt der Seite herum einfügen.

{{{ #!rst

.. include:: kopf

Der eigentliche Inhalt des Dokumentes hier.

.. include:: fuss }}}

Die Anzahl der so eingefügten Dokumente ist auf zehn begrenzt. Dies dient dazu, eine sogenannte Denial of service Attacke durch rekursive include-Anweisungen zu verhindern.

Makro Unterstützung

Der MoinMoin ReStructuredText parser fügt eine neue MoinMoin spezifische Makro Direktive hinzu. Mit dieser Direktive kann aus dem ReStructuredText Dokument auf MoinMoin Makros zugegriffen werden. Zum Beispiel:

{{{ #!rst

Benutze das *title search* Makro um ein Sucheingabefeld zum Durchsuchen der Seitentitel in die Seite einzufügen.

.. macro:: TitleSearch }}}

Benutze das title search Makro um ein Sucheingabefeld zum Durchsuchen der Seitentitel in die Seite einzufügen.
<<TitleSearch>>

Bekannte Probleme

Die Pakete Docutils und MoinMoin benutzen CSS (Cascading style sheets) zur HTML-Formatierung. Einige Direktiven überschneiden sich in den Namen, andere nicht. Zum Beispiel die note Direktive wird ohne spezielle Formatierung angezeigt. Dieses Problem stört am meisten zusammen mit dem rightsightbar Thema und der docutils sidebar Direktive. Momentan wird empfohlen, die sidebar Direktive nicht zusammen mit MoinMoin zu benutzen.
Die Möglichkeiten bezüglich des Aufrufs externer URLs oder lokaler Dateien werden vom Parser aus Gründen der Sicherheit nicht unterstützt. Außerdem
werden auch sogenannte raw roles und einige andere Möglichkeiten, die es dem Benutzer erlauben würden, reine HTML auszugeben, verboten.