© Liashko/Shutterstock.com
Texte erstellen und aufbereiten mit Python und Sphinx

Die Schlange und die Statue


Das aus dem Umfeld von Python stammende Auszeichnungsformat reStructuredText wird meist verwendet, um Dokumentation für Python-Quellcode bzw. entsprechende Projekte zu erzeugen. Darauf muss sich der Einsatz aber nicht beschränken. Mit dem Werkzeug Sphinx lassen sich beliebige Texte für vielfache Verwendungen formatieren.

Wir zeigen in diesem Artikel, wie die Kombination von Python und Sphinx verwendet werden kann, um einen Text in einem bestimmten Ausgabeformat bereitzustellen. Unsere Fallstudie ist dabei dieser Artikel selbst, der im Quellformat reStructuredText geschrieben und anschließend ins Zielformat (die Dokumentvorlage des Software & Support Verlags) überführt wird.

Ein Blick zurück – Textverarbeitung und Computer

Persönliche Computer (Homecomputer und Personal Computer) wurden schon immer zur Texterstellung verwendet. Anfangs wurde das Ergebnis immer auf Papier ausgedruckt. Gegenüber dem direkten Schreiben auf Papier gab es aber auf dem Computer schon immer die Möglichkeit, einen geschriebenen Text vor dem Ausdrucken zu korrigieren, zu editieren und umzustrukturieren.

Die ersten Ansätze der Textverarbeitung ähnelten noch der Verwendung einer Schreibmaschine. Die Texte wurden als ASCII-Daten eingegeben und beim Druck in genau derselben Formatierung wie im Quelltext ausgegeben. Die damals verwendeten Typenraddrucker, die analog zu den vorhandenen Schreibmaschinen jeden Buchstaben nur in einer einzigen, festen Darstellung drucken konnten, ließen ein anderes Verfahren auch kaum zu. Ein damaliges Textverarbeitungssystem war, verkürzt gesagt, eine elektronische Schreibmaschine mit einem editierbaren Textspeicher. Ein mit einem solchen System geschriebener Text sah genauso aus, als wenn er mit einer Schreibmaschine geschrieben worden wäre.

Für viele Anwendungsfälle war das ausreichend. Da Geschäftsbriefe, Rechnungen etc. damals auch mit Schreibmaschinen geschrieben wurden, gab es hier keine Qualitätseinbußen. Für die Veröffentlichungen von Texten als Buch war die Ausgabequalität aber unbefriedigend. Insbesondere Computerliteratur wurde damals etwa in diesem Format veröffentlicht. Gegenüber einem richtig gesetzten Buch waren diese Bücher aber nicht sehr leserfreundlich. Neue Ausgabemöglichkeiten führten dazu, dass sich die Textverarbeitung weiterentwickelte:

  • Für den Ausdruck auf Papier kamen Matrixdrucker, Tintenstrahldrucker und Laserdrucker hinzu. Alle drei boten die Möglichkeit, Buchstaben in verschiedenen Größen, Schriftarten und Stilen darzustellen.

  • Außerdem führte die zunehmende Verbreitung von Computern dazu, dass Papier nicht mehr das einzige Zielformat war. Viele Texte wurden jetzt direkt auf Computerbildschirmen gelesen, z. B. Manpages in UNIX-Systemen oder Programmdokumentationen.

Um den neuen Möglichkeiten und Anforderungen gerecht zu werden, entwickelten sich zwei neue Methoden, Texte zu erstellen: Textverarbeitungen (Word Processors) und kompilierende Textformatiersysteme.

Textverarbeitungen

Textverarbeitungssysteme basieren auf dem Prinzip „What you see is what you get“ (WYSIWY): das Erscheinungsbild des Quelltexts im Editor entspricht weitestgehend dem Ausgabeformat (zunächst dem Ausdruck auf Papier). Ändert der Anwender etwas an der Formatierung, kann er den Effekt seiner Änderung, das Erscheinungsbild seines Texts, sofort sehen.

Der bekannteste Vertreter eines solchen Systems dürfte Microsoft Word sein, eine von vielen freien Alternativen ist Libre Office Writer. Diese beiden Beispiele finden im Office-Kontext Verwendung. Noch wichtiger ist das beschriebene WYSIWYG-Verhalten für Desktop-Publishing-(DTP-)Programme, bei denen eine exakte Positionierung, Dimensionierung und Formatierung von Textkomponenten elementar ist.

Kompilierende Textformatiersysteme

Bei diesen Systemen muss der Anwender seinen Text in einer bestimmten Syntax schreiben. Der Quelltext im Editor sieht anders aus als das Ausgabeformat. Um das Ausgabeformat zu erzeugen, ist ein zusätzlicher Arbeitsschritt erforderlich, bei dem der Text zum Ausgabeformat kompiliert wird. Das macht die Arbeit mit solchen Systemen weniger intuitiv, einerseits durch die Trennung von Texterstellung und Erzeugung der Ausgabe, andererseits, weil der Anwender eine spezielle Syntax erlernen muss. Beispiele für entsprechende Systeme sind etwa troff: ein Klassiker aus der UNIX-Welt, der u. a. zur Formatierung von UNIX-Manpages verwendet wird, und TeX/LaTeX, ein Textsatzsystem, das aufgrund seiner hohen Ausgabequalität oft im akademischen Bereich verwendet wird.

Die Gründe, warum solche Systeme überhaupt noch verwendet werden, obgleich sie weniger intuitiv und ergonomisch zu benutzen sind als die genannten Textverarbeitungssysteme, sind die folgenden:

  • Die Grundlage für das Quellformat ist einfacher Text, entsprechend kann der Text mit einem beliebigen Editor erstellt werden.

  • Weil das Quellformat einfacher Text ist, kann damit genauso gearbeitet werden wie mit Quellcode für Programme. Insbesondere kann der Quelltext mit Versionskontrollsystemen verwaltet und damit können Änderungen auch nachverfolgt werden. Das schützt vor Datenverlusten durch versehentliches Löschen/Überschreiben, und erleichtert die Zusammenarbeit in Teams.

  • Weil das Quellformat nur inhaltliches Markup enthält, kann es auch einfach benutzt werden, um automatisiert Informationen zu extrahieren.

  • Die Arbeitsweise, dass der Quelltext zunächst erstellt, dann kompiliert und zuletzt kontrolliert wird, entspricht dem Edit-Compile-Test-Zyklus aus der Softwareentwicklung und ist Softwareentwicklern von daher vertraut. Hinzu kommt, dass der Autor nicht in Versuchung gerät, zwei Dinge gleichzeitig zu tun, nämlich einerseits Inhalt zu erstellen und andererseits das Layout zu gestalten. Vielmehr begünstigt die Trennung der Verarbeitungsphasen, sich zunächst nur auf das Erstellen des Inhalts zu konzentrieren, und sich über die Gestaltung ggf. erst später Gedanken zu machen.

  • Da der Text ohnehin kompiliert wird, können hier auf einfache Weise automatisiert weitere Texte aus anderen Quellen programmgesteuert eingefügt werden.

  • Das Prinzip WYSIWYG kann eigentlich nur funktionieren, wenn ein festes Ausgabemedium mit bestimmten Eigenschaften vorgegeben ist. Für ein Papierformat wie A4 kann etwa ein Rahmen auf dem Bildschirm angezeigt werden, der genau dem Größenverhältnis von Höhe zu Breite entspricht. Heutzutage sind aber die Eigenschaften der Ausgabemedien zum Erstellungszeitpunkt nicht immer bekannt, da derselbe Text z. B. in einem Browser auf einem Monitor, einem Tablet oder einem Smartphone dargestellt wird, wobei auf allen Geräten sowohl die sichtbare Größe (der Viewport) als auch die Fontgröße vom Anwender stark angepasst werden können.

Insbesondere der letzte Punkt ist von Bedeutung. Wird der Text in einem von der konkreten Ausgabe unabhä...

Neugierig geworden?

Angebote für Teams

Für Firmen haben wir individuelle Teamlizenzen. Wir erstellen Ihnen gerne ein passendes Angebot.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang