Ein Update zu docbook_status: es gibt eine neue Version, 0.2.1 (die Dokumentation gibt es, wie immer, hier). Neben der Kapitelhierarchie und den Wortmengen werden nun auch Kommentare verarbeitet. Kommentare, das heißt hier Anmerkungen, Korrekturen, die im Entwurfsstadium genutzt werden. Ganz traditionell also, hat nichts mit dem Leser zu tun, ist — wie das ganze Werkzeug — auf den Autor ausgerichtet.
In DocBook 5 gibt es für solche Kommentare das remark Element. Dieses ist inhaltlich sehr flexibel angelegt. Gemeint ist es aber vor allem für textliche Anmerkungen, entweder eigene, oder die eines Korrektors. Bei der Implementierung habe ich mich an die weit verbreitete Behandlung von Kommentaren in Quellcode angelehnt.
Dort wird die Art des Kommentars gern mit einem aussagekräftigen Schlüsselwort am Anfang angedeutet. Beginnt also der Kommentartext mit einem Wort in Großbuchstaben, wie zum Beispiel dem berühmten FIXME oder TODO, dann wird dies vom Programm als Kommentartyp interpretiert, der dann bei der Anzeige und Filterung genutzt wird.
Was in Ruby-Code etwa so aussehen würde:
#
# TODO look for 'role' attributes as keywords?
#
def find_remarks_in_doc(doc,source)
rems = doc.find('//db:remark')
wäre in einem DocBook-Text:
<remark>TODO Blindtext! Inhalt ergänzen</remark> <para> lorem impsum ... </para>
docbook_status würde das dann beim Aufruf mit der Option –remarks in etwa so anzeigen:
... Remarks: Type File Line Content ------------------------------------------------------ REMARK dms.xml 28 War's das? TODO dms.xml 30 Blindtext! Inhalt ergänzen |
Das Schlüsselwort TODO würde dank Großbuchstaben als solches erkannt und angezeigt. Remark-Elemente ohne solche Schlüsselworte werden einfach mit REMARK versehen. Hat man viele Anmerkungen und möchte sich auf die wichtigsten konzentrieren, kann einfach nach Anmerkungstyp gefiltert werden:
docbook_status --remarks=TODO dms.xml |
Bei dieser Art der Nutzung würden nur die TODOs angezeigt, die man noch abzuarbeiten hat. Man kann übrigens mehrere Filter angeben.
Derzeit wird eine Anmerkung mit Datei und Zeile identifiziert. Das ist ganz auf die XML-Datei bezogen. Schreibt man aber nicht direkt XML, sondern generiert die DocBook-Datei irgendwie anders, dann sind diese Informationen womöglich nicht so hilfreich. Was wäre denn die Alternative zur Identifikation einer Anmerkung? Der Abschnitt in dem sie liegt, die XML ID, oder gar die Anzeige von Kontext, also dem Inhalt davor und danach?