Too Cool for Internet Explorer

Handbücher mit Latex


Ich habe im Laufe der vergangenen Jahre ein recht umfangreiches Framework zum Entwickeln webbasierter Anwendungen geschrieben. Die ganze Sache hat mittlerweile eine Komplexität erreicht, bei der mir die API Dokumentation alleine nicht mehr aussreicht. Aber womit schreibt man gute Handbücher, welche Tools werden dafür eingesetzt? Eine Textverarbeitung? Ein Texteditor?

Ich bin mit dem Schreiben von komplexen Dokumenten in einer Textverarbeitung wie Word oder OpenOffice nicht wirklich glücklich. Immer wenn ich also vor dieser Problematik stand, tauchte früher oder später "Latex" in meinen Gedanken auf. Bisher hatte ich jedoch immer den Lernaufwand gescheut :o).

Kürzlich war ich jedoch gezwungen längere Zeit auf meinen Internet-Anschluss daheim zu verzichten, packte die Gelegenheit beim Schopf und bestellte bei Lehmanns die DVD "TeX Collection 2005" - randgefüllt mit TeX Distributionen und Erweiterungen. Dazu besorgte ich mir noch eine gute Einführung in LaTeX, sowie eine mässige Referenz.

Ich muss sagen: der Lernaufwand war nicht wirklich hoch. Auf der DVD fand ich die Distribution MacTeX, die sich - wie man es unter OSX gewohnt ist - nahezu von selbst installiert. Auch für Windows und Linux bzw. Unix befindet sich selbstverständlich Software auf der DVD. Am Anfang ist es sicherlich ein wenig aufwändiger die Formatierungsbefehle von Hand zu setzen. Mit der Zeit geht dies aber immer flüssiger von der Hand und wenn man dann das Ergebnis als PDF vor sich sieht oder als Ausdruck in der Hand hält, dann erkennt man schnell, warum sich die Mühe gelohnt hat. Endlich eine Dokumentation, die professionell aussieht.

Ein Vorteil von LaTeX ist meines Erachtens auch, dass man LaTeX leicht in den Entwicklungs-Workflow integrieren kann, weil man den Text mit Kommandozeilen-Tools verarbeiten kann und es viele Tools gibt, die LaTeX produzieren oder man sich schnell auch eigene Tools entwickeln kann, die eigene Informationen automatisiert in das Dokument mit einbinden können.

So bin ich jetzt von phpdoc zum Generieren der API Dokumentation auf Doxygen umgestiegen. Neben der Ausgabemöglichkeit als LaTeX Dokument hat Doxygen zudem noch den Vorteil, dass man API Dokumentation auch aus Programmen, die in anderen Sprachen entwickelt wurden (wie JavaScript), damit verarbeiten kann. Es gibt sogar eine Erweiterung für das von mir favorisierte Build-System - ANT - für Doxygen.

Zum Schluss benötigte ich nur noch ein Tool, mit dem ich Quellcode von Beispielprogrammen farblich formatiert in die Dokumentation integrieren kann. Hier bin ich mit highlight fündig geworden, das zahlreiche Programmiersprachen unterstützt und LaTeX exportieren kann.

Ein ganz wichtiger Vorteil von LaTeX ist, dass die Texte selbst im reinen ASCII Format vorliegen. TeX Systeme gibt es für die meisten Plattformen. Es ist ein ausgereiftes System, das so schon seit viele Jahren besteht. Die Gefahr von inkompatibler Software, die in ein paar Jahren das Dokument nicht mehr Anzeigen oder verarbeiten kann, besteht deshalb nicht. Ausserdem eignen sich LaTeX Dokumente Aufgrund des ASCII-Formats natürlich hervorragend dazu über ein Versionssystem wie subversion oder cvs verwaltet zu werden.

Es würde mich interessieren, mit welchen Tools andere ihre Handbücher schreiben. Wer selbst noch auf der Suche ist, dem kann ich LaTeX jedenfalls nur ans Herz legen.