27. April 2004
von
Wolfgang Wershofen
In diesem Dokument geht es um die Handhabung der
udrec-Dokumentation und die Pflege der Webseiten mit UDO. Kai hatte
dieses Tool Ende 2003 aufgetan und es eignet ich hervorragend, um
erstens das Design der Website von deren Inhalt zu trennen und
zweitens die Dokumentation aus einer Quelle in verschiedene
Zielformate umzuwandeln. Dadurch erspart man sich eine Menge
Doppelpflege und vor allem könnt auch ihr Nicht-HTMLer ganz
bequem kleinere Updates an der Website durchführen.
Um Euch diese Arbeit so einfach wie möglich zu machen, habe
ich diese Doku erstellt, in der ich Euch das Konzept der UDO-Sourcen
und wie man daraus welches Zielformat erstellt, erläutern
möchte.
Viel Spaß dabei. Bei Fragen, schickt mir eine Mail. ;-)
cu
Wolle
P.S.: Übrigens, dieses Dokument habe ich auch mit UDO
erzeugt. :)
Ich möchte hier eigentlich nicht näher auf die UDO-Syntax bzw. den generellen Aufbau von UDO- Dokumenten eingehen. Dazu gibt es ziemlich ausführliche Informationen unter http://www.udo-open-source.org. Hier soll es mehr darum gehen, wie ich die UDO-Sourcen speziell für unsere udrec_suite angelegt habe und wie man wo was findet.
In den UDO-Sourcefiles der udrec_suite gibt es z.Zt. drei verschiedene Dateitypen, die ich durch unterschiedliche Extensions kenntlich gemacht habe.
Bei den eigentlichen Dateinamen habe ich auch versucht, mich an einige Konventionen zu halten. Die Dateinamen fangen immer mit dem hauptsächlichen Einsatzgebiet an, für den die jeweilige Datei gedacht ist. z.Zt. sind das:
Natürlich läßt sich durch die Tatsache, daß die meisten Textinhalte in allen Zielformaten Verwendung finden, trefflich drüber streiten, ob eine Datei nun eher für die Webseite oder für das readme gemacht wurde, aber das bringt wohl nicht viel. Vielmehr sollte man sich einmal für einen Prefix entscheiden und diesen dann beibehalten, da eine Änderung des Dateinamens mit viel Aufwand verbunden ist, wenn dieser schon in einigen anderen Files verwendet wird.
Neben dem Ziel, eine Quelle für alle Dokumentationen zu haben, bietet UDO auch eine prima Gelegenheit, Design und Inhalt voneinander zu trennen. Da ich unsere bestehende Website durch den Einsatz von UDO nicht komplett umgestalten wollte, sondern das Layout unverändert erhalten bleiben sollte, mußte ich ein paar Kunstgriffe einbauen, die eine 1:1-Portierung einer Quelle in alle Zielformate zwar nicht unbedingt unmöglich, aber doch nicht besonders empfehlenswert macht. Um dennoch so wenig Redundanz wie möglich zu gewährleisten, sind die UDO-Sourcen sehr modular aufgebaut, wodurch sich zwangsläufig zwar die Anzahl der zu pflegenden Dateien erhöht, allerdings sind diese dann wiederum so klein, daß sie sehr einfach zu handhaben sind. Um in diese Dateien ein wenig Struktur zu bekommen, habe ich die Sourcen in mehrere Unterverzeichnisse verteilt und auch hier versucht, die Trennung von Design und Inhalt zu dokumentieren
Soviel zu den Verzeichnissen und Namenskonventionen. Ich denke, daß der Aufbau soweit nicht weiter schwierig nachzuvollziehen ist. Grundsätzlich sollte sich das Hauptaugenmerk für Änderungen an der Dokumentation auf den Ordner ./source/includes/content konzentrieren, eventuell sind auch Anpassungen an den *.udo Files notwendig, wenn neue Inhalte hingekommen sind.
Über die drei Zielformate an sich brauche ich ja auch nicht wirklich viele Worte zu verlieren. Es soll hier eigentlich auch mehr um die eventuellen Besonderheiten und Unterschiede der einzelnen Formate gehen.
Naturgemäß ist die Website das komplexeste Format.
Während sich die readmes und manpages mit reinem Textlayout
zufrieden geben, soll eine Website ja auch optisch ansprechend mit
Bildern, Farben und Hintergründen gestaltet sein. Außerdem
ist unsere Website in drei Bereiche unterteilt, die Navigationsleiste
links, den Hauptteil in der Mitte sowie die rechte Spalte mit
weiterführenden Kurzinformationen im Bezug auf den Hauptteil.
All das muß im Gegensatz zu den anderen Formaten für
die Website definiert werden. Das meiste davon habe ich in ein paar
zentrale Include-Member des Ordners Webdesign gepackt, damit der
Inhalt der Seite weitestgehend vom Layout getrennt wird. Hier die
wichtigsten dieser Includes:
Die übrigen Member des Webdesign-Orders (website_right_*.ui)
enthalten die kleinen Kurzinfos, die in der rechten Spalte angezeigt
werden.
Jede einzelne Webseite hat ihr eigenes UDO-Sourcefile, weil
ansonsten die Verwendung unserer Logografiken zu Beginn der Seite
nicht mehr funktionieren würden. Leider funktioniert dadurch
natürlich die automatische Verlinkung einzelner Abschnitte
über UDO nicht mehr, dafür finde ich den somit etwas
modulareren Aufbau der Sourcen etwas übersichtlicher.
Wenn man eine neue Seite für die Website anlegen möchte,
muß man daher folgende Schritte durchführen:
That's it.
Hier hab' ich noch nichts konkretes. Wird gefüllt, wenn ich die ersten "ernsthaften" READMEs gebaut habe.
Die manpages haben einen sehr monolithischen Aufbau, da nur sehr
wenige UDO-Objekte hier sinnvoll integriert werden können.
Allenfalls die generelle Programmbeschreibung könnte aus den
Webseiten übernommen werden, allerdings ist das nur ein sehr
geringer Teil des Umfanges der manpages.
Die Quelldateien der manpages sollten analog zu den oben genannten
Namenskonventionen angelegt werden. Für die Generierung wichtig
ist die Angabe des UDO-Befehls !man_type, in dem die Nummer des
manpage-Abschnittes angegeben wird (1 für Programmbeschreibungen,
5 für Dateibeschreibungen etc - siehe "man man"
für eine komplette Liste.
Für die Neugenerierung einer manpage gibt es ein Skeleton mit
den gebräuchlichsten manpage-Einteilungen (siehe
Verzeichnis-Struktur).
Die erzeugten manpages werden übrigens bei der Generierung
der Website mit dem Script build_website in HTML-Seiten umgewandelt
und sind anschließend auch online abrufbar. Zur Generierung
dieser Seiten wird das Tool man2html verwendet.
Um nun aus den UDO-Source die fertige Dokumentation zu erzeugen,
muß eine entsprechende Generierung durchgeführt werden. Bei
der doch etwas umfangreicheren Anzahl an Webseiten, readme und
manpages sollte diese Generierung weitestgehend automatisiert
ablaufen. Hierzu habe ich einige Scripte erstellt, die die Generierung
für die jeweiligen Zielformate übernehmen.
Die Scripte liegen im Verzeichnis "doc" und sind auch
nur lauffähig, wenn sie von dort aus aufgerufen werden, da einige
relative Pfadangaben darin enthalten sind. Benötigt werden die
Tools UDO
und man2html um die Generierung durchführen zu
können
Eine Generierung erfolgt nur dann, wenn mindestens eine der
UDO-Quelldateien neueren Datums ist als die zu generierende Zieldatei.
Geprüft wird die mit dem Script checkUDOsrc.
Folgende Scripte sind aktuell schon vorhanden:
Mit diesem Script wird geprüft, ob mindestens eine zur Erzeugung einer Zieldatei benötigte UDO-Quelldatei neuer ist als die zu generierende Seite. Die Syntax des Scripts sieht so aus:
checkUDOsrc <quelldatei> <zieldatei>
Das Script prüft zunächst, ob die <quelldatei> neuer ist als die <zieldatei>. Ist dies nicht der Fall wird in der <quelldatei> nach Includes gesucht und fr jedes gefundene Include ruft sich das Script selbst wieder rekursiv auf. Sobald eine neuere <quelldatei> gefunden wird, beendet sich das Script mit RC 1 und gibt den Namen der gefundenen Datei über /dev/stdout aus. Wird keine neuere Datei gefunden, endet das Script mit RC 0.
Der Name ist Programm. Mit diesem Script wird die gesamte udrec_suite Website generiert. Neben dem Aufruf von udo für jede einzelne Seite übernimmt das Script noch einige Spezialaufgaben
Auch hier ist die Bedeutung des Scripts relativ selbsterklärend. Aus den UDO-Sourcen man_*.udo werden die entsprechenden Manpages im Verzeichnis "man" erzeugt. Die Generierung erfolgt auch hier nur, wenn die Quelldateien neuer sind als die Zieldatei, ebenfalls wieder gesteuert über checkUDOsrc.
Wenn Ihr Änderungen an den Webseiten vornehmen oder neue
Webseiten bzw. Verweise auf manpages einfügen wollt, solltet Ihr
die unten beschriebenen Schritte durchführen. Ich gehe bei diesem
Quick-and-Dirty HowTo davon aus, daß Ihr den cvs-Tree der
udrec_suite lokal und in aktuellem Zustand auf Eurem Rechner vorliegen
habt und die CVSROOT-Variable korrekt gesetzt ist (zur Sicherheit
nochmal ein "cvs update" ausführen ;-). In diesem
lokalen cvs-Tree nehmt Ihr dann die Änderungen vor.
Wenn Ihr die Änderungen an den UDO-Sourcen (Verzeichnis
udrec_suite/doc/source) fertiggestellt habt, dann geht Ihr
folgendermaßen vor, um die Änderungen auch auf die Website
zu transportieren:
That's it. Wenn das SF-CVS keine Probleme macht und wirklich die aktuellen Stände zur Verfügung stellt, können die Änderungen jetzt unter http://udrecsuite.sf.net/v04 kontrolliert werden.
Hier bin ich mir noch nicht so ganz schlüssig, wie diese ganze Sache in's CVS eingebunden werden soll. Ein Außenstehender, der sich die udrec_suite aus dem CVS holt, soll ja nicht den gesamten Sourcecode der Website oder noch besser die UDO-Sourcen erhalten, weil ihn das vermutlich nicht die Bohne interessiert. Hier muß Kai mir mal helfen.