21.12 Manpages erstellen 
Neben einer vernünftigen Dokumentation, die als Textdatei, HTML-Datei, pdf-Datei oder als was auch immer vorliegen kann, ist es unter Unix und Linux üblich, für seine Programme eine Manpage zu erstellen. Eine Manpage erklärt im Groben die Funktionsweise eines Programms und die Parameter, die man dem Programm übergeben kann.
21.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 letztlich 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 Manpage-Sektion fest, der diese Manpage angehört.
- .SH NAME
- .SH leitet eine Manpage-Sektion (etwa »NAME«, »AUTHOR«, »DESCRIPTION« usw.) ein. Betrachten Sie einmal eine typische Manpage, um sich einen Überblick über die häufig verwendeten 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 wird.
- .IP
- Zur Aufzählung einzelner Parameter für ein Programm wird in der Regel der Befehl .IP verwendet. Hinter diesen Befehl setzt man den Parameter (also etwa -r) und in die darauffolgende Zeile die entsprechende Erklärung zu diesem Parameter. Eine Manpage könnte in etwa folgendermaßen aussehen:
.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)Listing 21.68 Eine Beispiel-Manpage
- Um aus diesem Textbatzen nun eine vernünftige Manpage zu generieren, ruft man groff mit dem Parameter -man auf. Möchte man nicht gerade eine Postscript-Datei generiert haben, verwendet man -Tascii, damit groff die Manpage im ASCII-Format ausgibt.
# Postscript-Datei: $ groff -man mytool.1 > mytool.ps $ gv mytool.ps # ASCII-Manpage: $ groff -man -Tascii mytool.1 | lessListing 21.69 groff aufrufen
21.12.2 Die Manpage installieren
Um die Manpage auch im System zu installieren, gibt es zwei Möglichkeiten:
- Man kopiert die Quelldatei der Manpage (das ist die Datei mit den groff-Anweisungen) in das entsprechende Sektionsverzeichnis des lokalen Manpage-Verzeichnisses. Die Sektionsverzeichnisse heißen dabei man1 für Sektion1, man2 für Sektion 2 und so weiter und befinden sich in der Regel in /usr/local/man/.
$ cp mytool.1 /usr/local/man/man1/Listing 21.70 Kopieren
- Man (oder frau) leitet die ASCII-Ausgaben von groff in ein Verzeichnis einer cat-Sektion. Ein solches Verzeichnis befindet sich ebenfalls im lokalen Manpage-Verzeichnis.
$ groff -man -Tascii mytool.1 \ >/usr/local/man/cat1/mytool.0Listing 21.71 Umleiten
Beide Installationsmöglichkeiten eignen sich auch hervorragend, um die Manpage über ein install-Target einer Makefile zu installieren.
Abbildung 21.5 Die fertige Manpage
