ndoc - Norbert's documentation generator
SYNOPSIS
ndoc man | html | usage [ <ifile ] [ >ofile ]
DESCRIPTION
Mit diesem Filter kann aus einem Quellfile (relativ) einfacher Syntax (NDML 1.0, ndoc Markup Language)
wahlweise eine Man-Page,
ein HTML-File oder C++ Quellcode für eine Funktion usage(ostream &o) erzeugt werden.
Alle Schlüsselworte sind in Großbuchstaben zu schreiben. Da diese Man-Page ebenfalls mit
ndoc erstellt wurde, sind die Schlüsselworte im folgenden klein dargestellt :(
Als Trenner einzelner Bereiche innerhalb einer Zeile fungiert immer das "Hashmark"
(Raute, Käsekästchenm, Gartenzaun, Nummernzeichen), für das aus dem gleichen Grund
im folgenden stellvertretend % benutzt wird.
NDML 1.0
Ein NDML File besteht aus einzelnen Sektionen, die jeweils mit einem der
Schlüsselworte name , synopsis , description , options , text und list am Zeilenanfang beginnen.
Dem Schlüsselwort folgen teilweise noch Parameter, stets getrennt durch %.
name und synopsis müssen immer am Fileanfang stehen, auf sie folgen jeweils einige
Parameter. Alle anderen Sektionen sind optional und enthalten neben den Schlüsselwortparametern
auch noch Text in den folgenden Zeilen. Der Text einer Sektion wird durch Schlüsselwort mit vorangestellter
Tilde ~ beendet.
Innerhalb des Textes sind noch ein paar kleinere Textformatierungskommandos zugelassen,
von zu wilden Kombinationen dieser Features wird aber abgeraten. Textformatierungskommandos beginnen mit
einem Paragraphen als Escape-Zeichen direkt gefolgt von einem Buchstaben und enden mit "Paragraph+Tilde+Buchstaben".
Bedeutung der Schlüsselworte
- name
- 2 Parameter, Name der Manpage und Kurzbeschreibung für apropos, z.B.: name % ndoc % Norbert's documentation generator
- synopsis
- 2 Parameter, Programmname und Komandozeilenparameter, z.B.: synopsis % ndoc % man | html | usage [ <ifile ] [ >ofile ]
- description
- kein Parameter, Sektion für das einführende blabla
- options
- kein Parameter. In dieser Sektion dokumentiert jede Zeile eine Programmoption, der Name der Option wird immer durch % von der Beschreibung getrennt. Reicht eine Zeile nicht aus kann ähnlich wie beim cpp nach einem Backslash am Zeilenende in der nächsten Zeile weitergemacht werden.
- list
- ein Parameter: Sektionsüberschrift. Eigentlich sehr ähnlich wie options, pro Zeile ein zu dokumentierender Begriff, nach einem % folgt die Beschreibung. Einziger Unterschied: options wird für usage verwendet und erzeugt auch den führenden "-" selbständig. Bsp: list % Bedeutung der Schlüsselworte
- clist
- wie list, aber Schlüsselworte im C-Code Style
- text
- ein Parameter: Sektionsüberschrift. Danach beliebige Prosa.
Beispiel für eine Sektion:
- description
-
- bla bla bla
-
- ~description
-
Textformatierung
- B
- Bold
- C
- C-Code Style, wird in Manpages ebenfalls Bold, in html Courier
Desweiteren existiert noch das Kommando link(adresse,anker) aus dem in html ein Hyperlink, auf einer Manpage
Boldfont erzeugt wird
CONCLUSION
Alles in allem ist das ganze noch recht rudimentär und eher für den Heimgebrauch
geeignet (wegen einiger verborgener Features die sich durch die Implementierung mit langen awk & sed Pipes
ergeben), dafür kann man einfache Dokus parallel für Manpages und WWW erzeugen, and remember: ndoc is better than no doc :)
stoffler