Meistens schreibe ich nicht direkt in XML-Formaten, sondern generiere zum Beispiel das DocBook-Format aus reinen Textformaten und diversen anderen Quellen – wie Dokumentations-Generatoren für Code. Die bekannten Auszeichnungssprachen wie Textile, Markdown und Asciidoc machen es einem ja einfach, strukturiert Texte in beliebigen Editoren zu schreiben, und diese dann in das jeweilige Zielformat, HTML oder DocBook, zu konvertieren.
Ein kleines Problem dabei ist, dass ich bei größeren Anstrengungen, deren Bestandteile auf viele kleine und größere Dateien verteilt sein können, die geschrieben oder generiert sind, die Übersicht über das große Ganze verliere. Wo sind welche Abschnitte in der Struktur? Ist die Schachtelungstiefe überall ähnlich? Wie groß sind die einzelnen Abschnitte? Wie groß ist der gesamte Text? Das sind so die Fragen, die sich mir beim Schreiben oder Durchsehen stellen.
Bei einfachen Texten in einer Datei gibt es immer die Notlösung “wc -w” um die Textgröße zu ermitteln, wenn der Editor nicht schon selbst die Worte zählt. Bei den erwähnten, etwas komplizierter aufgebauten Projekten war dann schon immer ein kleines Skript nötig, um die benötigten Infos zu erhalten. Um das in Zukunft zu vermeiden gibt es nun docbook_status.
Hilfsprogramm docbook_status
Docbook_status ist ein kleines Hilfsprogramm, das zur Zeit nichts anderes tut, als eine DocBook-Datei auf Struktur und Wortzahl hin auszuwerten. Warum die DocBook-Datei und nicht die Quelldateien? Aus praktischen Gründen: DocBook ist ein XML-Format und das lässt sich somit gut parsen. Außerdem ist die DocBook-Datei bei mir die Vorstufe für die Auslieferungsversion. Sie enthält den gesamten Inhalt, der dann nur noch in das Zielformat transformiert wird. Somit zeigt docbook_status nur die Werte an, die auch wirklich im auszuliefernden Resultat vorhanden sind. Entwürfe, alternative Fassungen usw., die vielleicht als Dateien im selben Verzeichnis vorhanden sind, werden so automatisch außen vor gelassen.
Docbook_status analysiert immer nur eine DocBook-Datei. Bei größeren Projekten, die fast immer aus mehreren Dateien für Kapitel oder ähnliches bestehen, gehe ich davon aus, dass diese via XInclude oder ähnliche Mechanismen in die Hauptdatei integriert werden (siehe http://docbook.org/tdg5/en/html/ch02.html#ch02-physdiv).
Output?
Lange Rede, kurzer Sinn: was produziert diese Ding denn? Eine einfache Aufstellung, so sieht zum Beispiel die Anzeige für diesen Artikel, an dieser Stelle aus:
Angezeigt werden:
- der Dateiname
- das Änderungsdatum der Datei
- die Dateistruktur
- der Titel des jeweiligen Abschnitts, eingerückt
- der DocBook-Tag des Abschnitts
- die Wortzahl des Abschnittstexts (ermittelt aus den Elementen: para, formalpara, simpara)
Die Anwendung kann manuell, einmal aufgerufen werden, oder auch als Dämon mitlaufen, um bei jeder Dateiänderung die Auswertung neu durchzuführen.
Wo und wie?
docbook_status ist als Ruby Gem implementiert, kann also einfach per
gem install docbook_status |
heruntergeladen werden. Die – recht kurze – Dokumentation ist in den Projektseiten zu finden.