SourceCode zu reStructured Text

Hier eine kleine Zusammenstellung, wie *strukturierter Text* [1]_ (*structured Text*) beim Editieren in "PyDS" funktioniert. Der der `Source-Code`_ zu dieser Einführung kann in Text 29 eingesehen werden. Dort kann man genau sehen, wie die einzelnen Textelemente im Editor erzeugt wurden. Eine weitere `Kurzanleitung`_ gibt es im Weblog des "PyDS"-Programmierers Georg Bauer. Wer mehr dazu wissen will, sollte sich die Anleitung `Quick reStructuredText`_ durchlesen.

Inhalt:

.. contents:: :local:

Überschriften
==============

Überschriften werden durch Unterstreichungen gekennzeichnet. Dabei klassifiziert immer eine Zeichenart eine bestimmte Ebene. Überschriften der höchsten Ebene habe ich mit Gleicheitszeichen gekennzeichnet. Die Unterstreichung muß mindestens so lang sein wie die Überschrift.

Überschrift 2
----------------

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

Überschrift 3
__________________

Für die dritte Ebene - mehr hat dieser Text nicht - habe ich Unterstriche gewählt.

Inhaltsübersichten
====================

Inhaltsverzeichnisse kann man automatisch anlegen lassen. In PyDS sollte man das lokale Inhaltsverzeichnis benutzen, da sonst eine weitere H1-Überschrift gebildet wird. Lokale Inhaltsverzeichnisse erfassen alle nachfolgenden Überschriften bis zu dem Level, der dem Befehl folgt. Die erste folgende Überschrift muß also den höchsten Level haben, damit ein kompletter Inhalt erstellt wird.

Text
======

Normaler Text beginnt linksbündig und kann fortlaufend geschrieben werden. Ein Absatz endet jeweils mit einer Leerzeile. Im können weitere Absätze oder andere Elemente folgen.

Listen und Aufzählungen
=========================

Es gibt einfache (ungeordnete) Listen, numerische Listen und Definitionslisten. Listen können ineinander verschachtelt sein.

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

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

Absätze
==============

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. Jedem Block 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.

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
  ====== ====== ======

Tabellen
===============

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 |
+--------+--------+--------+

.. _Hier:

Hyperlinks (Verweise zu URLs)
==============================

Eine normale URL wird einfach eingegeben. PyDS erkennt http://www.westfalen.de als URL und hinterlegt sie mit einem Hyperlink auf die URL.

Wenn eine URL einem Text hinterlegt sein soll, so stellt man dem Text einen Unterstrich direkt nach. Besteht der Text aus mehreren Wörtern, so muß man diese mit umgekehrten einfachen Anführungsstrichen hinterlegen (dem Akzent, der sich auf der deutschen Tastatur rechts vom Fragezeichen findet). Die zugehörigen Links werden dann z. B. am Ende der Seite einfach aufgelistet. Die hier gewählte Form erfordert dabei keine bestimmte Reihenfolge. Man kann so z. B. vor dem Schreiben eines Textes die zu verwendenden URLs einfach in beliebiger Reihenfolge vor oder hinter dem Text auflisten. Der Text selbst wird dadurch wesentlich übersichtlicher als beim Verwenden von Makros für URLs.

Hyperlink Witch_

`Homepage Witch`_

.. _Witch: http://www.witch.westfalen.de
.. _Homepage Witch: http://www.witch.westfalen.de

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.
 

Fußnoten
=========

Fußnoten werden in eckige Klammern gesetzt. Um sie zu verlinken, muß der Klammer ein Unterstrich folgen. Hier ist eine Fußnote [2]_. Und hier kommt eine anonyme Fußnote dazu [#]_. Anonyme Fußnoten werden automatisch durchnummeriert.

Makros verwenden
===================

Insbesondere bei URLs ergibt sich das Problem, daß die in Makros verwendeten URLs normalerweise vom Interpreter für den strukturierten Text interpretiert werden. Hier behilft man sich, indem man den gesamten Makro-Aufruf in Rückwärts-Anführungsstriche (den Akzent rechts neben dem "?") setzt. Der Aufruf des Makros linkTag für die `$macros.linkTag('http://muensterland.org','Homepage Weblog-Server Muensterland.org')` sieht dann wie unten im Source ersichtlich aus.

Kürzel aus PyDS
================

Die in PyDS definierten Kürzel können wie vorgeschrieben in Anführungsstrichen im Text verwendet werden. Ist Text in Anführungsstriche gesetzt, ohne daß er in PyDS als Kürzel hinterlegt ist, werden die Anführungsstriche und der Text normal ausgegeben.

Bugs und Fehlerhinweise
=======================

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.

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.

Und am Schluß die Fußnoten selbst
==================================

.. [1] Die Beschreibung auf dieser Seite wird in Zukunft laufend erweitert. Die Änderungen werden dann im Weblog angekündigt.
.. [2] Hier der Text zu Fußnote 2
.. [#] Die anonyme Fußnote wird automatisch durchnummeriert

.. _Source-Code: http://witch.muensterland.org/stories/29.html
.. _Kurzanleitung: http://muensterland.org/users/0000006/stories/8.html
.. _Quick reStructuredText: http://docutils.sourceforge.net/docs/rst/quickref.html

Quelltext dieses Textes
========================

Im nachfolgenden Block ist der Quelltext dieses Textes zu finden, also der Text genau so, wie ich ihn eingegeben habe.