30.12 Manpages erstellen

Neben einer vernünftigen Dokumentation, die als Textdatei, HTML, PDF oder als was auch immer vorliegen kann, ist es unter Unix und Linux üblich, für eigene Programme eine Manpage zu erstellen. Eine Manpage erklärt im Groben die Funktionsweise eines Programms und die Parameter, die man ihm übergeben kann.

30.12.1 groff nutzen

Zur Erstellung einer Manpage nutzt man das Tool groff. Dabei wird eine Textdatei erstellt, aus der groff anschließend eine Manpage erstellt.

Gearbeitet wird dabei ähnlich wie in \LaTeX{} oder HTML: Man verwendet verschiedene Befehle, die Formatierungsanweisungen für einen Interpreter/Compiler darstellen. Im Folgenden wollen wir Ihnen die wichtigsten Befehle vorstellen, die man zur Erstellung von Manpages mit groff verwendet.

• .TH NAME SEKTION
  Dieser Befehl legt den Namen einer Manpage (in der Regel ist das der Name des Programms) sowie die Sektion fest, der sie angehört.
• .SH NAME
  .SH leitet eine Manpage-Sektion (zum Beispiel NAME, AUTHOR oder DESCRIPTION) ein. Betrachten Sie einmal eine typische Manpage, um sich einen Überblick über häufig verwendete Sektionen zu verschaffen.
• .RS
  Dieser Befehl bewirkt einen 7-Zeichen-Einschub gegenüber der vorhergehenden Zeile. So kann eine Manpage hierarchisch gegliedert und übersichtlicher gehalten werden.
• .I
  Der .I-Befehl bewirkt, dass der Text einer Zeile unterstrichen oder kursiv gesetzt wird.
• .IP
  Zur Aufzählung einzelner Parameter für ein Programm wird in der Regel der Befehl .IP verwendet. Hinter ihn setzt man den Parameter (also etwa -r) und in die darauffolgende Zeile die entsprechende Erklärung dazu.

Eine Manpage könnte in etwa folgendermaßen aussehen:

Listing 30.67 Eine exemplarische Manpage

.TH MeinTool 1
.SH NAME
MeinTool  ein ganz prima feines Tool
.SH SYNOPSIS
.B MeinTool [-v] [-l
.I config-file
.B ]
.SH DESCRIPTION

MeinTool kann alles, was andere Tools nicht koennen.

.SH OPTIONS
.IP -v
Ausfuehrliche Meldungen ausgeben.
.IP "-l config-file"
Falls nicht die Standard-Konfigurationsdatei
verwendet werden soll, kann ueber diesen Parameter
eine Alternative (
.I config-file
) angegeben werden.
.SH BUGS
Manchmal funktioniert MeinTool, aber in der Regel
sollte man sich nicht darauf verlassen.
.SH AUTHOR
Steffen Wendzel <cdp@doomed-reality.org>
.SH "SEE ALSO"
.BR reboot (8)

Um aus diesem Textbatzen eine Manpage zu generieren, ruft man groff mit dem Parameter -man auf. Möchte man nicht gerade eine PostScript-Datei generiert haben, so verwendet man -Tascii, damit groff die Manpage im ASCII-Format ausgibt.

Listing 30.68 groff aufrufen

# PostScript-Datei:
$ groff -man mytool.1 > mytool.ps
# ASCII-Manpage:
$ groff -man -Tascii mytool.1 | less

30.12.2 Manpages installieren

Um die Manpage auch im System zu installieren, haben Sie zwei Möglichkeiten:

• Kopieren Sie die Quelldatei der Manpage (die Datei mit den Anweisungen für groff) in das entsprechende Sektionsverzeichnis des lokalen Manpage-Verzeichnisses. Die Sektionsverzeichnisse heißen man1 für Sektion 1, man2 für Sektion 2 und so weiter; sie befinden sich i.d.R. im Verzeichnis /usr/local/man/.

Listing 30.69 Kopieren

$ cp mytool.1 /usr/local/man/man1/

• Leiten Sie die ASCII-Ausgaben von groff in ein Verzeichnis einer cat-Sektion. Ein solches Verzeichnis befindet sich ebenfalls im lokalen Manpage-Verzeichnis.

Listing 30.70 Umleiten

$ groff -man -Tascii mytool.1 >/usr/local/man/cat1/mytool.0

Abbildung 30.6 Die fertige Manpage

Beide Installationsmöglichkeiten eignen sich auch hervorragend, um die Manpage über ein install-Target eines Makefiles zu installieren.

Ihre Meinung

Wie hat Ihnen das Openbook gefallen? Wir freuen uns immer über Ihre Rückmeldung. Schreiben Sie uns gerne Ihr Feedback als E-Mail an kommunikation@rheinwerk-verlag.de.