Strukturierter Text mit PyDS

Überschrift 2

Die Überschriften der nächsten Ebene sind mit Bindestrichen unterstrichen.

Einfache Liste

Die einfache Liste beginnt nach einer Leerzeile. Vor jedes Element wird einfach ein Spiegelstrich (Bindestrich) gesetzt. Im Anschluß an die Liste folgt eine Leerzeile.

• Element1
• Element2

Um untergeordnete einfache Listen zu produzieren, werden diese einfach eingerückt eingeschoben. Wichtig sind dabei die Leerzeilen vor und nach der untergeordneten Liste und die Einrückung bis zur Textebene der äußeren Liste (also hier um zwei Zeichen).

• Liste 1, Element 1
• Liste 1, Element 2
  • Liste 2, Element 1
  • Liste 2, Element 2
• Liste 1, Element 3

Numerische Liste

Eine numerische Liste wird nach einer Leerzeile einfach als Liste mit Zahl und Punkt eingegeben. Hier sind in der Liste Auszeichnungselemente angegeben.

1. kursiv Element
2. fett Element
3. interpretierter Text
4. literal

Definitionsliste oder Glossar

Bei einem Glossar wird der Begriff zu Beginn der Zeile eingegeben und direkt in der Folgezeile eingerückt die Bedeutung. Die Liste endet wieder mit einer Leerzeile.

Def

Bedeutung von Def

Def2

Bedeutung von Def2

Field List (Feldliste?)

Man kann auch eine Liste erzeugen, in der Name und Inhalt durch Doppelpunkt abgetrennt sind (oder anders gekennzeichnet nebeneinander stehen). Im Unterschied zur Definition List wird der Begriff durch Doppelpunkte eingeklammert. Wichtig ist wieder das Leerzeichen vor dem Feldinhalt in der folgenden Zeile. Zwischen den Doppelpunkten können ab PyDS Version 0.5 auch Leerzeichen sein.

Titel:	Strukturierter Text mit PyDS Eine Einführung
Autorin:	Jutta Wrage
letzte Änderung:	10.06.2003

Und noch ein Beispiel:

letzte Änderung:	31.12.2005
Langtext:	Langtext verändert das aussehen der resultierenden Tabelle
Einrückung:	Da das vordere Feld releativ lang sein kann, müssen folgende Zeilen des Eintrages nicht an der selben Stelle beginnen, wie die erste Zeile. Sie müssen aber eingerückt sein und zwar um die gleiche Anzahl Zeichen.

Normale Absätze

Ein normaler Absatz beginnt am Zeilenanfang. Der Absatz endet mit der nachfolgenden Leerzeile.

Zitate

Zitate (Quoted Blocks) werden durch eingerückte Absätze wiedergegeben. Wenn kein besonderer Stil vorgegeben ist, kann diese Absatzform auch für eingerückte Absätze benutzt werden. Davor sei jedoch gewarnt, weil das BLOCKQUOTE-Tag semantisch ausschließlich für Ziate verwendet werden sollte.

Jedem Block oder Absatz eines Zitates folgt eine Leerzeile

Dies ist ein Normaler Absatz

Dem normalen Absatz folgt ein eingerückter Block für ein Zitat. Nach der Einrückung am Anfang des Absatzes wird bis zum Ende Fließtext geschrieben. Danach folgt eine Leerzeile.

Wenn man anschließend noch weiter einrückt, kommt ein verschachtelter Zitat-Block wie dieser hinzu.

Der Rest des äußeren Zitates erhält dann wieder die ursprüngliche Einrückung.

Achtung: Bei Anwendung der CSS in diesem Weblog muß nach dem eingeschobenen Zitat ein weiter Absatz des ursprünglichen Zitates folgen, weil sonst die äußeren Anführungsstriche offen bleiben.

Inzwischen kann man auch die Zitat-Quelle (Attribution) an den Block anfügen. Leider fügt reStructuredText aber nicht das erwartete CITE ein sondern einen Absatz innerhalb des Blockquotes mit der Klasse attribution. Verwendet man nicht die CSS, wie sie für dieses Weblog gelten, funktioniert die Quellangabe mittels -- Quelle oder --- Quelle als letzten Absatz des Block-Zitates einwandfrei.

Literale Blöcke

Beim literalen Block bleiben Formatierungen wie Zeilenumbrüche und Einrückungen erhalten. Sie eignen sich deshalb für Gedichte, einfache Tabellen (für die es auch eine andere Lösung gibt) und Source, sofern er nicht mit PyDS-internen Variablen kollidiert.

Literale Blöcke müssen in allen Zeilen um mindestens ein Zeichen eingerückt sein. Bei den Einrückungen ist zu beachten, daß immer so viele führende Leerzeichen aus allen Zeilen des Blockes entfernt werden, die die Zeile mit den wenigsten führenden Leerzeichen hat. Im folgenden Block steht deshalb ohne CSS-Definition die letzte Zeile linksbündig, obwohl auch sie führende Leerzeichen hat. Der literale Block wir immer durch zwei Doppelpunkte eingeleitet. Dabei gibt es drei Formen:

• Die Doppelpunkte stehen allein in einer Zeile,
• die Doppelpunkte stehen durch Leerzeichen abgetrennt am Ende des vorhergehenden Absatzes
• oder die Doppelpunkte stehen direkt hinter dem letzten Zeichen des vorhergehenden Absatzes

In den ersten beiden Fällen werden die Doppelpunkte nicht ausgegeben, im dritten Fall werden sie in der Ausgabe als einfacher Doppelpunkt wiedergegeben.

Literaler Block:

      Wir beginnen weit hinten
   und rücken die nächste Zeile weniger ein,
was im Ergebnis eigentlich zu sehen sein sollte

Tabelle als literaler Block:

======  ======  ======
Wahrheitstabelle
----------------------
A       B       A or B
======  ======  ======
wahr    wahr    wahr  
wahr    falsch  wahr
falsch  wahr    wahr
falsch  falsch  falsch
======  ======  ======

Einfache Tabelle

Alle einfachen Tabellen beginnen und enden mit Zeilen mit Gleichheitszeichen. Die Gleichheitszeichen der ersten Zeile geben dabei die Breite einer Zelle an.

Die folgende einfache Tabelle soll nur der Demonstaration dienen, wegen der Untauglichkeit für Blinde sollten Tabellen ohne Köpfe nicht benutzt werden:

Eine Tabelle	mit zwei Spalten
und	zwei Reihen

Zellen können auch miteinander verbunden sein, dies wird durch ersetzen der Leerzeichen zur Spaltentrennung in den Kennzeichnungen kenntlich gemacht:

Tabelle mit vier Zeilen,
und zwei	Spalten.
Erste und	letzte Zeile
enthalten verbundene Zellen.

Und hier noch eine Tabelle. Beim Schreiben muß man gut zählen, weil sonst die Umsetzung nicht klappt. Die Spalten müssen in jeder Zeile gleich breit sein (gleich viel Zeichen enthalten). Mehrere einfache Tabellen sollte man nicht direkt untereinander platzieren, da das unübersichtlich werden kann.

Wahrheitstabelle
A	B	A or B
wahr	wahr	wahr
wahr	falsch	wahr
falsch	wahr	wahr
falsch	falsch	falsch

Einfache Tabelle als literaler Block

Und nun die gleiche Tabelle als literaler Block hinter zwei Doppelpunkten und einer Leerzeile. Dabei wird jeder Zeile mindestens ein Leerzeichen vorangestellt.

======  ======  ======
Wahrheitstabelle
----------------------
A       B       A or B
======  ======  ======
wahr    wahr    wahr  
wahr    falsch  wahr
falsch  wahr    wahr
falsch  falsch  falsch
======  ======  ======

Tabelle mit Rahmen

Tabellen mit Rahmen werden in PyDS als normale Tabelle wiedergegeben.

Der Rahmen wir aus Bindestrichen, Pluszeichen, Umleitungs-Symbolen und Gleichheitszeichen (unter den Überschriften) gebildet.

Wahrheitstabelle
A | B | A or B
wahr	wahr	wahr
wahr	falsch	wahr
falsch	wahr	wahr
falsch	falsch	falsch

Interne Hyperlinks

Interne Hyperlinks verlinken innerhalb eines Dokuments. Hier geht es z. B. zum Kapitel über die externen Hyperlinks, die ich auf den Anker "Hier_" gelegt habe. Der Ankerdefinition folgt im Text eine Leerzeile, die genau wie der Anker selbst nicht mit ausgegeben wird. PyDS mißachtet bei den Ankern die Groß-/Kleinschreibung. Außerdem werden Umlaute durch andere Zeichen ersetzt, so daß man in dieser Hinsicht auf Doppelangaben achten muß, die zu einer Fehlermeldung führen.

Bugs

PyDS-Versionen vor 0.5 haben eine unvollständige Implementation von strukturiertem Text. In PyDS 0.52 funktionieren in reStructured Text einige Sachen (noch) nicht so, wie sie sollten. Für PyDS 0.7.4 gilt: Bei Einschaltung der Unterdrückung "leerer" Absätze, werden leider die Blockquotes (Zitat-Blöcke) mit fehlerhaftem HTML gerendert. Schaltet man die Unterdrückung ab, so werden durch zu viele Tags jedoch weitaus mehr Fehler produziert.

• Das globale Inhaltsverzeichnis sorgt dafür, daß eine weitere H1-Überschrift entsteht, dem kann man durch die Nutzung des lokalen Inhaltsverzeichnisses begegnen.
• Überschriften lassen sich nicht direkt anspringen. Man kann dem begegnen, indem man einen versteckten internen Link anlegt.
• Tabellen mit Rahmen erscheinen als einfache Tabellen.
• Bei neuren Kombinationen PyDS und Docutils muß einer Feldliste ein anderer Absatz vorangehen, sonst wird die Tabelle nicht angezeigt.

Fehlerhinweise

Einige Eingabefehler führen zu unvorhergesehen Umwandlungen oder Fehlermeldungen.

• Überschriften, die von PyDS als Sprungmarken definiert sind, können nicht direkt angesprungen werden. Tut man das dennoch, geht das Überschriften-Rendering kaputt und Inhaltsverzeichnisse sind unvollständig oder fehlen
• Fehlen Leerzeilen am Ende von Absätzen oder anderen Blöcken, so wird das folgende in den Block mit eingebaut. Gibt es ein merkwürdiges Ergebnis, ist also hier zuerst zu suchen.
• Fehlen die Sprungmarken zu Hyperlinks, so wird das Wiki angesprungen. Es kann aber auch andere unerwünschte Nebenwirkungen geben.
• Zu kurze Unterstreichungen von Überschriften führen z. B. auch zu Fehlern im Inhaltsverzeichnis.
• Der Fehler steckt nicht immer da, wo man ihn vermutet. Als ich z. B. die Unterstreichung der folgenden Überschrift zu kurz hatte, fehlten alle vorangegangenen Überschriften im Inhalt, erst die kaputte und die nachfolgenden waren im Inhaltsverzeichnis angelegt.