Aus LinuxUser 12/2004

groff (Seite 2)

Das Grundgerüst erstellen

Learning by doing – am schnellsten lernen Sie die groff-Befehle, indem Sie eine eigene Manpage schreiben. Mehr als einen einfachen Text-Editor brauchen Sie dazu nicht. Legen Sie eine neue Datei an und geben Sie dieser beispielsweise die Endung .1, wenn es sich um ein Benutzerkommando handelt, das später in der ersten Manpage-Abteilung liegen soll. Die erste Zeile einer Manpage enthält traditionell den Titel, die Manpage-Sektion und das Datum der letzten Bearbeitung; tragen Sie also ein:

.TH HUHN 1 "22. Oktober 2004"

Als Nächstes legen Sie die einzelnen Kapitel an. Welche der schon genannten Sektionen Sie verwenden wollen, bleibt Ihnen selbst überlassen – es handelt sich lediglich um eine Konvention, nicht um eine feste Vorgabe; Sie können auch eigene Abschnitte definieren. Die einzelnen Sektionen fangen jeweils mit dem Befehl .SH an und stehen in einer neuen Zeile, danach folgt der Name der Sektion:

.SH NAME
.SH SYNOPSIS
.SH DESCRIPTION
.SH SEE ALSO
.SH BUGS
.SH AUTHOR

Ein Unterkapitel namens Options soll im Abschnitt DESCRIPTION die einzelnen Befehlsparameter erklären. Fügen Sie dazu ein strukturierendes Element ein:

.SH DESCRIPTION
.SS Options
…

Mehr Inhalt bitte!

Diese grundlegende Struktur füllen Sie nun nur noch mit Leben. Damit die Manpage von Kommandos wie apropos oder man -k nach Stichworten durchsucht werden kann, sollten Sie in der dritten Zeile (also direkt hinter dem Eintrag .SH NAME) den Namen und eine durch einen Bindestrich davon abgetrennte kurze Beschreibung des Befehls einfügen. Achten Sie darauf, dass vor dem Bindestrich ein Backslash steht:

.SH NAME
huhn \- Das sensationelle Henne-Ei-Skript

Im Abschnitt SYNOPSIS folgt die Kurzbeschreibung der Befehlssyntax mit einer Auflistung aller Optionen. Der Programmname soll hier fett (\fB...\fP) gesetzt sein, Parameterzusätze kursiv (\fI...\fP). Optionale Parameter stehen in eckigen Klammern:

.SH SYNOPSIS
\fBhuhn\fP [ -ei | -poak | -picken ] [ -t \fItyp\fP ] [ -escape \fIfarm\fP ]

Danach folgen ein Zeilenumbruch und in einem neuen Paragraph – optisch übersichtlich gestaltet – der Hinweis, wie die Befehlshilfe aufzurufen ist. Der Eintrag zur Versionsnummernabfrage kommt ebenfalls in eine eigene Zeile:

.PP
\fBhuhn\fP -h | --help
.PP
\fBhuhn\fP -v | --version

Im Abschnitt DESCRIPTION beschreiben Sie das Kommando nach Herzenslust in einem Fließtext. Mit den schon bekannten Formatanweisungen setzen Sie Befehle, Dateinamen und Optionen wieder kursiv oder fett, um sie besser kenntlich zu machen. Im Unterabschnitt Options notieren Sie in einer Liste die einzelnen Parameter und fügen eine Erklärung hinzu. Dazu verwenden Sie eine der in Tabelle 1 vorgestellten Listen, z. B. die Liste ohne Aufzählungszeichen: Zuerst steht in einer Zeile die Anweisung .TP, in der folgenden Zeile der Parameter und in der dritten Zeile die Erklärung. Ebenso gehen Sie für die restlichen Abschnitte vor – Listing 1 zeigt den Quelltext der huhn-Manpage zum Vergleich.

Listing 1

Manpage zu

huhn (1)

.TH HUHN 1 "22. Oktober 2004"
.SH NAME
huhn \- Das sensationelle Henne-Ei-Skript
.SH SYNOPSIS
\fBhuhn\fP [ -ei | -poak | -picken] [ -t \fItyp\fP ] [ -escape
\fIfarm\fP ]
.PP
\fBhuhn\fP -h | --help
.PP
\fBhuhn\fP -v | --version
.SH DESCRIPTION
Das sensationelle Henne-Ei-Skript kann viele tolle Dinge. Das Huhn kann
gackern, Koerner picken, Eier legen und von der Farm weglaufen. Die
einzelnen Parameter lauten:
.SS Options
.TP
\fB-ei\fP
Fordert das Huhn auf, ein Ei zu legen. Die Frage, ob die Henne oder das
Ei zuerst kommt, ist dabei unerheblich. Es bleibt abzuwarten, ob zu
diesem Problem jemals eine Loesung gefunden wird.
.TP
\fB-escape \fIfarm\fP
Da kein Huhn auf einer Huehnerfarm gefangen sein sollte, befreien Sie
die Hennen mit diesem Befehl, z. B. durch den Aufruf: \fB-escape
tweedie\fP.
.TP
\fB-h, --help\fP
Zeigt die vollstaendige Liste aller Parameter an.
.TP
\fB-poak\fP
Bringt das Huhn zum Gackern.
.TP
\fB-picken\fP
Zwingt das Huhn zur Nahrungsaufnahme.
.TP
\fB-t \fItyp\fP
Definiert den Huehnertyp, moegliche Werte:
.IP \(bu
\fIfrei\fP Freiland
.IP \(bu
\fIkaefig\fP Kaefig
.IP \(bu
\fIbatterie\fP Legebatterie
.TP
\fB-v, --version\fP
Zeigt die Versionsnummer des Skriptes an.
.SH SEE ALSO
Weitere Tipps zu Huehnern finden Sie im Internet. Fuer die Erstellung
von Handbuchseiten empfehlen wir die Manpages zu:
\fBgroff_man\fP(7), \fBgroff\fP(1), \fBman\fP(7)
.SH BUGS
Keine bekannten 🙂
.SH AUTHOR
Petronella, das Chefhuhn

Wandlungsfähig

Einen ersten Test, ob die Manpage Ihren optischen Vorstellungen entspricht, führen Sie auf der Kommandozeile durch. Wandeln Sie die gerade erstellte Handbuchseite mit den Manpage-Makros ins ASCII-Format um. Damit die Ausgabe nicht aus dem Terminal heraus scrollt, leiten Sie alles in den Pager less um:

groff -man -Tascii huhn.1 | less

Wer statt dessen lieber eine HTML- oder PostScript-Datei erstellt, setzt hinter den Parameter -T das entsprechende Format. Anstelle einer Ausgabe am Bildschirm empfiehlt sich hier, die Ausgabe in eine Datei umzuleiten, also

groff -man -Thtml huhn.1 > huhn.html

oder

groff -man -Tps huhn.1 > huhn.ps
Abbildung 3: Auf der Kommandozeile wandeln Sie die Manpage mit nur einem Befehl in eine Web-Seite um.
Abbildung 3: Auf der Kommandozeile wandeln Sie die Manpage mit nur einem Befehl in eine Web-Seite um.

An Ort und Stelle

Bleibt noch die Frage, was zu tun ist, damit andere Benutzer im System die Manpage mit dem Kommando man huhn lesen können. Kopieren Sie als Administrator die Datei huhn.1 an die richtige Stelle:

LinuxUser 12/2004 KAUFEN
EINZELNE AUSGABE Print-Ausgaben Digitale Ausgaben
ABONNEMENTS Print-Abos Digitales Abo
TABLET & SMARTPHONE APPS
Deutschland

Hinterlasse einen Kommentar

  E-Mail Benachrichtigung  
Benachrichtige mich zu: