Intuitive Syntax

• Generelle Idee: Einfache Sachen einfach, komplexe Sachen möglich

• Syntax orientiert sich an üblichen Gepflogenheiten in ASCII-basierter Auszeichnung

  Beispiele:

  Überschrift Level 1
  ===================
  
  Überschrift Level 2
  -------------------
  
  * Bullet-Listen mit der erwarteten Syntax
  
    Insbesondere ist dies hier der zweite Paragraph.
  
  1. Geordnete Listen mit vielen Enumeratoren möglich
  
     a. Ein Unterpunkt mit anderem Enumerator
  
        i) Sogar römische Enumeratoren gehen
  
           Auch hier funktionieren Folgeparagraphen wie erwartet.
  
        #) Und ab hier möchte ich gerne automatisch nummerieren
  
  2. Zweiter Punkt
  
  3. Dritter Punkt
  
  1. Eine neue Liste kann ich ganz zwanglos anfangen
  
     Ich muss nur mit einer 1. beginnen.
  
     (1) Auch die Syntax der Enumeratoren ist flexibel
  
         Für HTML muss allerdings das richtige CSS verwendet werden
         - was in MoinMoin nur eine minimale Erweiterung der
         Installation erfordert.
  
  #. Autonummerierter zweiter Punkt der zweiten Liste

  Deswegen: Extrem flache Lernkurve.

  • MoinMoin: Orientiert sich hier und da an üblichen Gepflogenheiten, beinhaltet aber viele üble Fallen. Meine Lieblingsfalle sind die Regeln für die richtige Einrückung. Grundproblem ist die Orientierung an der Ur-Wiki-Syntax, die m.E. ein Paradebeispiel für ein schlechtes Konzept ist.

• Einfache Tabellen sind einfach:

  =============  ================  ========
  Linker Header  Mittlerer Header  Rechter Header
  =============  ================  ========
  Zeile 1        Mittle 1          Rechts 1
  Zeile 2        Mittel 2          Rechts 2
  =============  ================  ========

  Und so sieht das dann in Echt aus:

  Linker Header	Mittlerer Header	Rechter Header
  Zeile 1	Mittle 1	Rechts 1
  Zeile 2	Mittel 2	Rechts 2

• Selbst einfache Tabellen bieten schon einige Möglichkeiten:

  =============  ================  ========
  Linker Header  Mittlerer Header  Rechter Header
  =============  ================  ========
  Zeile 1        Mittle 1          Rechts 1
  Zeile 2        Eine Zelle, die
                 viel Text           1. Punkt Eins
                 enthält
                                     2. Punkt Zwei
                 Und einen
                 zweiten                * Mit Unterpunkt
                 Paragraphen
                                        * Und noch einem
  Zeile 3        Hier wieder kurz
  =============  ================  ========

  Und so sieht das dann in Echt aus:

  Linker Header	Mittlerer Header	Rechter Header
  Zeile 1	Mittle 1	Rechts 1
  Zeile 2	Eine Zelle, die viel Text enthält Und einen zweiten Paragraphen	Punkt Eins Punkt Zwei Mit Unterpunkt Und noch einem
  Zeile 3	Hier wieder kurz

• Daneben gibt es auch .. csv-table:: und .. list-table::

• Zweispaltige Tabellen gehen auch mit Field-Lists:

  :Feld 1: Feldinhalt
  
  :Feld 2: Feldinhalte können selbstverständlich komplex sein
  
           Sie können z.B. mehrere Zeilen umfassen.
  :Feld 3: Feldinhalt #3

  Und so sieht das dann in Echt aus:

  Feld 1:	Feldinhalt
  Feld 2:	Feldinhalte können selbstverständlich komplex sein Sie können z.B. mehrere Zeilen umfassen.
  Feld 3:	Feldinhalt #3

• MoinMoin: Tabellen sind kompliziert und wenig leistungsfähig

  Tabellen in MoinMoin haben eine komplexe und kaum zu verstehende Syntax. Viele Möglichkeiten selbst einfacher ReStructuredText-Tabellen bieten sie nicht.

Komplexe Konstruktionen sind möglich

• Komplexe Tabellen sind möglich:

  +------------------------+------------+----------+----------+
  | Header row, column 1   | Header 2   | Header 3 | Header 4 |
  | (header rows optional) |            |          |          |
  +========================+============+==========+==========+
  | body row 1, column 1   | column 2   | column 3 | column 4 |
  +------------------------+------------+----------+----------+
  | body row 2             | Cells may span columns.          |
  +------------------------+------------+---------------------+
  | body row 3             | Cells may  | - Table cells       |
  +------------------------+ span rows. | - contain           |
  | body row 4             |            | - body elements.    |
  +------------------------+------------+---------------------+

  Und so sieht das dann in Echt aus:

  Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
  body row 1, column 1	column 2	column 3	column 4
  body row 2	Cells may span columns.
  body row 3	Cells may span rows.	Table cells contain body elements.
  body row 4

• Einfache Objekte können angereichert werden

  Beispiele:

  .. image:: SomePicture.gif
  
  bindet ein einfaches Bild ein. Eine bessere Beschreibung gelingt
  so:
  
  .. figure:: SomePicture.gif
  
     Ein Titel für das Bild
  
     Hier kann eine beliebig komplexe Legende für das Bild stehen.
  
     Wie vieles andere wird die Legende im HTML mit passenden
     Klassen versehen, so dass ein CSS das Layout übernehmen kann.
  
  .. table:: Eine optisch reizvolle Tabelle
  
     +---+---+---+
     |       |   |
     +---+---+   +
     |   |   |   |
     +   +---+---+
     |   |       |
     +---+---+---+

  Und so sieht die Tabelle dann in Echt aus:

  Eine optisch reizvolle Tabelle

• Es gibt nicht nur ein globales Inhaltsverzeichnis, sondern es können auch lokale Inhaltsverzeichnisse angelegt werden. Damit lassen sich lange Dokumente strukturieren.

• MoinMoin: Solche Dinge gehen weit über die Möglichkeiten von MoinMoin hinaus.

Konkrete Vorteile in Wikis/Hypertext

• Interne Anchors sind einfach zu setzen:

  _`Hierher` gibt es jetzt einen Anchor #hierher.

  • MoinMoin: Anchors können mit einem Makro auf einer eigenen Zeile definiert werden. Inline-Anchor sind nicht möglich und in jedem Fall muss der Name des Anchors gesondert notiert werden.

• Anchors können beliebige Namen haben

  Insbesondere sind auch Leerzeichen und Non-ASCII-Zeichen erlaubt. Diese werden nach einem einfachen und festen Algorithmus in Ids verwandelt.

  • MoinMoin: Anchors sind auf die Möglichkeiten von HTML-names eingeschränkt

• Automatische Anchors für Überschriften:

  Eine Kapitelüberschrift
  =======================
  
  Jetzt gibt es automatisch einen Anchor
  #eine-kapitel-berschrift, auf den ich sehr einfach mit `Eine
  Kapitelüberschrift`_ referenzieren kann.

  • MoinMoin: Kapitelüberschriften bekommen einen kryptischen Hash als name zugewiesen. Dieser ist nur in der fertigen Seite zu ermitteln und es ist nicht klar, wann der Hash geändert wird.

• Umbenennungen sind einfach möglich, ohne externe Links zu brechen, in dem weitere Anchor gesetzt werden:

  .. _Eine Kapitelüberschrift:
  
  Eine neue Kapitelüberschrift
  ============================
  
  Dieses Stelle kann jetzt mit `Eine Kapitelüberschrift`_ *und*
  mit `Eine neue Kapitelüberschrift`_ referenziert werden.

  • MoinMoin: Ist in MoinMoin nicht wirklich möglich, da für den alten Namen der kryptische Hash als Anchor verwendet werden müsste.

• Links setzen ist super-einfach:

  Ein Link_ ist einfach ein Wort mit einem anhängenden ``_``. Für
  `Links mit komplexem Namen`_ gibt es eine einfache Syntax mit
  Backquotes.

  Dadurch wird das Setzen von Links zu einer Sache, die man ganz nebenbei macht - und Hypertext gewinnt erst seine Kraft.

  • MoinMoin: Die Syntax zum Setzen von Links ist eine Geheimwissenschaft, derer wohl kaum jemand mächtig ist.

• Worte in CamelCase haben keine besondere Bedeutung

  In vielen Wiki-Syntaxen haben CamelCase-Worte eine besondere Bedeutung. Gerade für Software-nahe Texte ist dies von Nachteil, da CamelCase dort für die verschiedensten Zwecke eingesetzt wird. In ReStructuredText gibt es keine solche Automatik.

  • MoinMoin: Getreu der Ur-Wiki-Syntax bilden Worte in CamelCase automatisch Links auf - evt. nicht existierende - Wiki-Seiten. Gerade bei hierarchischen Wikis ist das in aller Regel nicht sinnvoll.

Integration in MoinMoin

ReStructuredText ist vollständig in MoinMoin integriert.

• MoinMoin-Makros können verwendet werden

  Insbesondere ist es über die .. macro::-Direktive auch möglich, die MoinMoin-Makros zu verwenden.

• Attachments werden unterstützt

  Es können ganz normal Attachments wie Bilder oder anderes hochgeladen werden.

• Wiki-Link-Syntax wird unterstützt

  Insbesondere werden ansonsten nicht interpretierbare Links wie z.B. StefanMerten als Links auf Wiki-Seiten interpretiert. Auch InterWiki-Links sind möglich. Dies bettet sich in die ReStructuredText-Syntax für Links ein.

Weitere Vorteile

• Erweiterbar

  Es können bei Bedarf einfach neue Direktiven oder Roles hinzu gefügt werden. Damit können auch solche Dinge in die Syntax integriert werden, die nicht schon enthalten sind.

  • MoinMoin: Die Wiki-Syntax ist über Makros erweiterbar.

• Hervorragende Dokumentation

  ReStructuredText verfügt über eine hervorragende Dokumentation. Vom Schnellstart über das Cheat-Sheet bis zur formalen und vollständigen Dokumentation ist alles vorhanden, was man sich wünschen kann.

  • MoinMoin: Die Dokumentation der Syntax ist dürftig, unvollständig und zerstreut.

• Logische Auszeichnung anstatt Layout-Auszeichnung

  In ReStructuredText wird nach logischen und nicht nach Layout-Kriterien ausgezeichnet. Das Layout wird erst durch entsprechende CSS-Definitionen festgelegt.

  • MoinMoin: Praktisch alle Auszeichnung ist Layout-orientiert.

• Weitere Output-Formate

  Für ReStructuredText existieren Writer für verschiedene Output-Formate. Darunter ist ein Writer, der via LaTeX PDF generieren kann und es gibt auch einen Writer, der die interne Struktur als XML ausgibt.

  Es gibt auch einen Writer, der OpenOffice-Dokumente produziert. Damit wäre auch der Weg zur Generierung von Word-Dokumenten offen.

  • MoinMoin: Nur für Docbook(?) und PDF.

• Integration in Editoren

  Es gibt einen hervorragenden Mode in Emacs - incl. Syntax-Highlighting.

  Es gibt wohl auch einen Mode für vi.

  • MoinMoin: Wenig bis keine Unterstützung.

• Aktives OpenSource-Projekt

  ReStructuredText wird vom docutils-Projekt entwickelt und steht unter der Python-Lizenz. Es handelt sich um ein aktives OpenSource-Projekt, in dem die gesamte Infrastruktur ständig weiter entwickelt wird.

  • MoinMoin: Die Syntax ist im MoinMoin-Projekt ein Stiefkind, an der ab und an mal rumgebastelt wird. Leider endet das nicht immer in einer Verbesserung...

• Erheblicher Unterschied zu anderen Wiki-Syntaxen

  ReStructuredText hat nie versucht die Ur-Wiki-Syntax zu kopieren, sondern ist eine Neuentwicklung, die sich aus anderen Quellen speist. Sie hat deswegen auch nicht die ganzen Defizite der Ur-Wiki-Syntax geerbt. Sie ist auch so unterschiedlich, dass ein Umschalten zwischen einer Wiki-Syntax und ReStructuredText problemlos möglich ist.

• Fehlermeldungen anstatt unsinnigem Output

  ReStructuredText geht von einer strikten Syntax aus. Dies führt dazu, dass syntaktisch falsche Konstrukte mit einer Fehlermeldung quittiert werden - wobei die Verarbeitung aber weiter geht. Damit ist sicher gestellt, dass falsche Syntax tatsächlich auffällt.

  • MoinMoin: Bei MoinMoin wird falsche Syntax nicht behandelt, sondern irgendwie interpretiert. In der Anzeige entsteht dadurch oft ein Mischmasch aus verunglückter Syntax und Inhalten. Mangels Fehlerbehandlung fällt dies auch nur beim Lesen der Seite auf. Um auf der sicheren Seite zu sein, muss also die Seite nochmal im fertigen Zustand gelesen und dann ggf. korrigiert werden - was den Aufwand für die Erstellung einer Seite erhöht.

• Als Dokumentenauszeichnung konzipiert

  ReStructuredText ist als vollständige Syntax zur Dokumentenauszeichnung konzipiert. Deswegen finden sich hier viele Features, die gerade auch für anspruchsvollere Dokumente nütlich sind. Als ein Beispiel sei die Möglichkeit genannt, Inhaltsverzeichnisse für Unterabschnitte generieren zu lassen.

  • MoinMoin: Die MoinMoin-Syntax ist lediglich für die wichtigsten Aspekte eines Wikis gebaut. Elemente für komplexere Texte sind in ihr nicht oder höchstens ansatzweise enthalten.

Defekte im Parser

• Inline-Auszeichnungen funktionieren nicht über mehrere Zeilen
• Kommentare brechen Einrückungsstruktur
• Definition Lists und andere eingerückte Konstruktionen funktionieren mehrzeilig nur in manchen Versionen und dann unterschiedlich
• Parser ist "Broken by Design"
• Neue MoinMoin-Versionen haben oft (neue) Fehler im Parser
• Inline-Markup funktioniert nicht in Überschriften oder Definition-List-Items