In diesem (derzeit notwendigerweise sehr dynamisch gehaltenen) Dokument wird beschrieben, wie ein HOWTO-Dokument aufgebaut ist und welche Schritte zu unternehmen sind, wenn man es in ein HTML-Dokument umwandeln will. Da die Verwaltung und Publikation der HOWTOs in einem späteren Stadium weitgehend automatisiert werden soll, ist vor allem beim zweiten Schritt – also bei der Publikation – mit einigen Veränderungen zu rechnen. (Siehe "Weitere Überlegungen" weiter unten.)
Ein HOWTO ist eine kurze, prägnante Beschreibung zur Lösung eines überschaubaren Problems. Es ist besonders geeignet für Tätigkeiten, die immer wieder durchgeführt werden müssen, dies aber nicht in einer Regelmäßigkeit und Häufigkeit, die ein schnelles Erlernen begünstigt.
Das HOWTO-Dokument ist ein XML-Dokument, das recht einfach aufgebaut ist:
Das Root-Element heißt <howto>. Es enthält einen <head> und einen <body>. Über letzteren braucht hier nichts weiter gesagt werden, da er einfach dem Body eines HTML-Dokuments nachempfunden ist. Es empfiehlt sich, auf besondere Formatierungen und "exotische" Dokumente zu verzichten. Eine Beschränkung auf Überschriften (H1 bis H3), Absätze (P) sowie einfache Formatierungen (BR) erscheint sinnvoll. Daneben können Tabellen (TABLE) und Links (A) verwendet werden.
Der Head eines HOWTO-Dokuments ist folgendermaßen aufgebaut:
<head>
<title>TITEL DES HOWTO</title>
<!-- Sollte sich in der ersten Überschrift (H1) im Dokument wiederholen -->
<author>
<name>NAME</name>
<mail>EMAIL-ADRESSE</mail>
</author>
<date>DATUM</date>
<!-- So, wie es vom CVS durch keyword substitution erzeugt wird -->
<revision>REVISION</revision>
<!-- So, wie es vom CVS durch keyword substitution erzeugt wird -->
</head>
Eine Template-Datei für das Verfassen eines HOWTOs findet sich im Verzeichnis admin.
Stellen, die noch einer späteren Bearbeitung bedürfen, sollten als solche durch drei Klammeraffen (@) kenntlich gemacht werden.
Derzeit erfolgt die Umwandlung noch von Hand:
xsltproc admin/howto2html.xsl NAME_DES_HOWTOS.xml >~/howto/NAME_DES_HOWTOS.htm
@@@
Auf die Dauer ist die Umwandlung von Hand unbefriedigend. Mit Hilfe eines Skriptes soll jederzeit aus der CVS-Sandbox das fertige HTML-Verzeichnis mit sämtlichen HOWTOs erzeugt werden können. Das Verzeichnis ist durch ein sinnvolles Inhaltsverzeichnis (automatisch erzeugt) zu erschließen. Verlinkungen der HOWTOs untereinander sind zu ermöglichen.
Da mit der Zeit mit einem starken Anwachsen der Zahl der Dokumente zu rechnen ist, ist über die Anlage einer vernünftigen Herarchie nachzudenken. Eine solche Hierarchie würde sich zumindest im Inhaltsverzeichnis wiederspiegeln. Dieses könnte mehrstufig angelegt werden. Die Ablage der HOWTOs im HTML-Format könnte in einer Ordnerstruktur erfolgen. Die Ablage im CVS kann ebenfalls in einer Ordnerstruktur erfolgen. Dabei ist aber zu bedenken, dass im CVS ein Umstellen und Umgruppieren der Dateien nicht ohne weiteres möglich ist. Daher ist auf jeden Fall in einer Steuerungsdatei die jeweilige Position eines HOWTOs in der Hierarchie festzuhalten. Dies kann auf zweierlei Art und Weise geschehen: Zum einen könnte die Inhaltsverzeichnisdatei separat als XML-Dokument geführt werden oder aber es könnte einfach in jedem HOWTO im Head die Position des jeweiligen Dokuments vermerkt werden. Ein Inhaltsverzeichnis würde sich dann erst aus der Zusammenstellung der Einzeldokumente ergeben.
Ferner ist über die Erstellung eines Volltextindex nachzudenken. Dieser könnte mit einem Python-Skript angelegt werden. Es könnten aber auch die gesamten HOWTOs in der Datenbank gehalten werden.
| Titel | Schreiben und Umwandeln eines HOWTOs |
| Autor | Clemens Radl <clemens.radl@uni-tuebingen.de> |
| Datum | 2003-05-21 09:36:33 |
| Revision | 1.4 |