Zusammenfassung

Dieses Dokument enthält die Anleitung zur Verwendung von 'structured text'. Dieses Dokument wurde mit Microsoft Word erstellt und mit WordXML automatisch in XML , HTML und HTMLHelp (.chm) konvertiert. Mit WordXML, dem Word-PlugIn der struktur AG, erweitern Sie Microsoft Word zu einem leistungsfähigen XML-Werkzeug.

Zusammenfassung

Mit structured text hat man ein einfaches Werkzeug, mittels dem man sich durch einfachen Text ausdrücken kann. Die Implementierung von structured text erlaubt die Anpassung der Syntax und der Ausgabe. Außerdem ist structured text sowohl in Zope integriert, als auch außerhalb verwendbar.

Quellen

Structured Text Wiki - behandelt structured text und STXNG.

reStructuredText - Eine structured text Alternative, entwickelt als Python docstring Standard.

Structured Text

Von millejoh. Letzte Änderung 16.10.2000

Siehe auch http://www.zope.org/Members/millejoh/structuredText

Einleitung

Structured Text ist ein verdammt gutes Werkzeug, und sollte von allen gekannt werden. Es eignet sich hervorragend für schnelles prototyping bei der Erstellung von Webseiten in Zope.

Irgendwie kann ich mich selbst nicht immer an alle Funktionen von structured text erinnern, ergo der ‘raison d'etre’ für dieses HOWTO.

Es ist fast nur eine Sammlung von Dokumentation, die ich in Quellcode gefunden und zusammenkopiert habe. Als ich dieses Dokument das erste Mal zusammengestellt habe war mir nicht bewußt, daß ich keine Ahnung davon hatte, wie ich structured text in meine DTML Methoden und Dokumente einfügen kann. Für diejenigen, die sich ähnlichen Problemen gegenübersehen, habe ich am Schluß ein kleines Beispiel dafür eingefügt, wie man structured text in DTML Dokumente einbindet. Keine Angst – wenn man die magischen Zauberformeln einmal kennt, ist alles ganz einfach. Viel Spaß! Vorschläge jeder Art sind jederzeit willkommen.

Structured Text Manipulation

Analysiere einen structured text-String so, daß man ihn mit strukturierten Formaten wie HTML verwendet kann. Structured text ist Text, der Einrückung und eine einfache Symbolik verwendet, um die Struktur eines Dokuments zu bestimmten.

Ein strukturierter String besteht aus einer Folge von Paragraphen, die durch eine oder mehere Leerzeilen voneinander getrennt sind. Jeder Paragraph hat einen Level, der definiert ist als die minimale Einrückung des Paragraphen. Ein Paragraph ist Unterparagraph eines anderen Paragraphen, wenn der andere Paragraph direkt vorausgeht und einen niedrigeren Level hat.

Eine spezielle Symbolik wird für die Anzeige spezieller Konstrukte verwendet:

  • Ein einzeiliger Paragraph dessen direkt folgende Paragraphen einen niedrigeren Level haben, wird als Überschrift behandelt.
  • Ein Paragraph, der mit ‘-‘,‘*‘, oder ‘o‘ anfängt, wird als Element einer ungeordneten Liste behandelt.
  • Ein Paragraph, der mit einer Folge von Zahlen beginnt, gefolgt von einem Leerzeichen, wird als Element einer geordneten Liste betrachtet.
  • Ein Paragraph, der mit einer Folge von Folgen beginnt, wobei jede Folge eine Folge von Zahlen oder Buchtstaben ist, gefolgt von einem Punkt, wird als Element einer geordneten Liste betrachtet.
  • Ein Paragraph, dessen erste Zeile aus etwas Text besteht, gefolgt von beliebigen Leerzeichen und ‘--‘ wird als beschreibendes Listenelement behandelt. Der führende Text ist der Titel des Elements.
  • Unterparagraphen von Paragraphen die mit dem Wort ‘example’ oder dem Wort ‘examples’ oder ‘::’ beginnen, werden als Beispielcode betrachtet und behalten ihre Formatierung bei.
  • Text in einfachen Anführungszeichen, mit einem Leerzeichen vor dem linken und einem Leerzeichen oder einem Satzzeichen vor dem rechten, wird als Beispielcode betrachtet.
  • Text der in ‘*‘ eingeschlossen ist, mit einem Leerzeichen vor dem linken und einem Leerzeichen oder einem Satzzeichen vor dem rechten, wird hervorgehoben.
  • Text der in ‘**‘ eingeschlossen ist, mit einem Leerzeichen vor dem linken und einem Leerzeichen oder einem Satzzeichen vor dem rechten, wird stark hervorgehoben.
  • Text der in ‘_‘ eingeschlossen ist, mit einem Leerzeichen vor dem linken und einem Leerzeichen oder einem Satzzeichen vor dem rechten, wird unterstrichen.
  • Text der in doppelte Anführungszeichen eingeschlossen ist, gefolgt von einem Doppelpunkt ’:’, wiederum gefolgt von einer URL und mit einem Satzzeichen abgeschlossen, wird als
    Hyperlink behandelt. Zum Beispiel:

    “Zope“:http://www.zope.org/ wird als http://ww.zope.org“>Zope interpretiert.

    Dies gilt sowohl für relative als auch für absolute URLs.
  • Text der in doppelte Anführungszeichen eingeschlossen ist, gefolgt von einem Komma ’,’, einem oder mehreren Leerzeichen gefolgt von einer absoluten URL und mit einem Satzzeichen und Leerzeichen abgeschlossen, wird als Hyperlink behandelt. Zum Beispiel

    “Schreib mir“, mailto:linus@peanuts.com.

    wird als

    mailto:linus@peanuts.com“>Schreib mir

    interpretiert. Dies gilt sowohl für relative als auch für absolute URLs.
  • Text, der in eckige Klammern eingeschlossen ist die nur Buchstaben, Zahlen, ’_’ und ’-’ enthalten, wird als Hyperlink innerhalb des Dokuments interpretiert. Ein Beispiel:

    Wie A. Smith [a12] gezeigt hat, ist diese Technik sehr effektiv. [r1]

    wird interpretiert als „Wie A.Smith [12] gezeigt hat, ...“.

    Zusammen mit der nächsten Regel können so einfach Verweise und Endnoten eingefügt werden.
  • Text in eckiger Klammer am Zeilenanfang, dem zwei Punkte und ein Leerzeichen vorangehen, wird als benannter Link behandelt. Zum Beispiel:

    .. [a12] „Effektive Techniken“ Smith, A.

    wird interpretiert als [12] „Effektive Techniken“ Smith, A. .... [r2] Zusammen mit der vorigen Regel lassen sich so einfach Verweise und Links einfügen.

[r1] Gemäß der HTML 4.0 Spezifikation müssen Bezeichner mit einem Buchstaben beginnen, also ist die Verwendung einer Referenenz namens [12] eigentlich tabu, obwohl es funktioniert (wenigstens in allen Browsern, die getestet worden sind). Das StructuredText Python Modul sollte wahrscheinlich aktualisiert werden, um ein besseres Verhalten zu implementieren, etwa dem voranstellen von ‘ref’ bei Linkadressen, die nur aus Zahlen bestehen.

[r2] Der Verwendung des Attributes ‘name’ ist veraltet. Stattdessen sollte ‘id’ verwendet werden. Nicht daß man dagegen etwas unternehmen könnte, da structured text das HTML generiert (eigentlich sollte es geändert werden). Aber man sollte wenigstens Bescheid wissen, falls einer pingelig ist.

Structured Text in DTML verwenden

Die härteste Zeit hatte ich, als ich versucht habe, structured text innerhalb von HTML zu verwenden und anzeigen zu lassen, bis ich folgenden Zauberspruch gelernt habe:

<dtml-var stx_doc_name fmt=structured-text>

Ohne den Teil ‘fmt=structured-text’ wird einfach der bloße Text ausgegeben, aber nicht das, was man sehen will.

Andere Quellen

Das Structured Text Document von Tres Seaver ist es auf jeden Fall Wert, angeschaut zu werden. Nützlicherweise wird auch eine ZClass bereitgestellt, die man als Wrapper für STX verwenden kann. Einfach besorgen, benutzen und glücklich damit sein.

Es gibt zwei kleinere Vorbehalte, die aber in 99% aller denkbaren Anwendungsfälle nicht zum Tragen kommen. In den Release Notes ist näheres darüber zu finden.