Ubuntu 12.04 „Precise Pangolin“
Ubuntu 10.04 „Lucid Lynx“
Ubuntu 8.04 „Hardy Heron“
Die Manual Page (kurz: Manpage) ist eine weit verbreitete Form der Dokumentation auf Unix-artigen Systemen. Sie wird als Textdatei im GNU roff-Format erstellt und als komprimierte .gz-Datei dem Benutzer zur Verfügung gestellt.
Manpages können aus anderen Formaten, wie beispielsweise Info-Seiten erzeugt werden, was in diesem Artikel aber nicht beschrieben ist. Dieser Artikel beschreibt die Grundlagen zum direkten Erstellen von Manpages, also die nötigen Werkzeuge, die Struktur und das Markup.
Manpages können in einem beliebigen Texteditor erstellt werden [1]. Es genügt die Struktur und die grundlegenden Regeln zur Formatierung einer manpage zu kennen. Die Archivierung erfolgt dann beispielsweise mit gzip (bzw. das Entpacken mit gunzip) [2] im Terminal [3].
Folgende Pakete müssen installiert [4] werden:
gmanedit (universe)
mit apturl
Paketliste zum Kopieren:
sudo apt-get install gmanedit
sudo aptitude install gmanedit
Manedit ist ein grafischer Editor speziell für manpages. Mit im Paket ist Manview zum Betrachten der Manpages.
Folgende Pakete müssen installiert [4] werden:
manedit (universe, nur für Hardy)
mit apturl
Paketliste zum Kopieren:
sudo apt-get install manedit
sudo aptitude install manedit
Sollte man Probleme mit dem fertigen Paket aus den Quellen haben, kann es helfen das Paket selbst zu kompilieren [6] und bei der Konfiguration andere Parameter anzugeben, als bei der Paketerstellung verwendet wurden. Dabei kann direkt Debugging und bz2-Komprimierung erlaubt werden, was das Debian-Paket unterbindet.
Dazu installiert man die Abhängigkeiten, bezieht den Quellcode, entpackt ihn, kompiliert und installiert das neue Paket. Bei der Konfiguration unterbindet man die Unterstützung verschiedener Architekturen, nicht jedoch die der eigenen. Das folgende Beispiel geht von einem i686-Prozessor aus, weshalb der Parameter --disable="arch-i686"
nicht aufgeführt ist.
Befehl zum Installieren der Build-Abhängigkeiten:
sudo apt-get build-dep manedit
sudo aptitude build-depends manedit
Anschließend kann der Quellcode heruntergeladen und kompiliert werden:
apt-get source manedit cd manedit*/ ./configure Linux --enable="debug" --disable="arch-i486" --disable="arch-i586" --disable="arch-pentiumpro" make all sudo checkinstall -y --pkgrelease 4
Die Releasenummer 4 ist nötig, da die Version in den Quellen bereits Releasenummer 3 (Ubuntu 8.04 Hardy Heron) hat.
Die Bedienung von gmanedit
kann über die Menü- oder Werkzeug-Leiste erfolgen und ist selbsterklärend, wenn man die grundsätzliche Struktur einer Manpage verstanden hat.
Gewöhnlich beginnt eine Manpage mit Kommentaren, beispielsweise einem Lizenzhinweis. Darauf folgt der Header.
Allgemein sieht der Header wie folgt aus:
1 | .TH "Befehl" "Manpage-Bereich" "Version" "Autor" "section" |
im konkreten Fall ergibt das beispielsweise:
1 | .TH "manvorlage" "1" "23. Mai 2008" "Max Mustermann" "documentation" |
Auf den Header folgen die einzelnen Sektionen. Je ausführlicher eine Hilfeseite ist bzw. je umfangreicher das beschriebene Programm ist, um so mehr Sektionen und Untersektionen werden sinnvollerweise genutzt.
Der übliche Aufbau einer Sektion sieht wie folgt aus:
1 2 3 | .SH
NAME
manvorlage
|
Übliche Sektionen sind u.a. NAME
, SYNTAX
, BESCHREIBUNG
, OPTIONEN
, DATEIEN
, SIEHE AUCH
, FEHLER
, und AUTOR
(im Englischen NAME
, SYNOPSYS
, DESCRIPTION
, OPTIONS
, FILES
, SEE ALSO
, BUGS
und AUTHOR
).
Um die vollständige Struktur einer Manpage zu betrachten, bietet es sich an verschiedene auf dem eigenen System bereits vorhandene Seiten im Quelltext zu betrachten, ein guter Ausgangspunkt ist sicherlich die Manpage zu man.
Üblicherweise werden englische Hilfeseiten unter usr/share/man/man1 (aus Debian-Paket) bzw. usr/local/share/man/man1 (andere Installtions-Methoden) abgelegt. Die deutschen Seiten liegen analog unter usr/share/man/de/man1 bzw. usr/local/share/man/de/man1.
Hier wird nur das nötigste Markup vorgestellt, um eine Manpage zu erstellen. Die vollständigen Formatierungs-Möglichkeiten des groff-Format sind in der Manual Page man(7) enthalten.
Beispiel |
![]() |
manvorlage.1.gz ![]() |
Markup | Zweck |
\fB | Anfang Textformatierung "fettdruck" |
\fI | Anfang Textformatierung "unterstrichen" |
\fR | Beendet die Textformatierung |
<br> | Zeilenumbruch |
& | Kaufmännisches Und (&) |
< | Kleiner-Als (<) |
> | Größer-Als (>) |
.LP | Linksbündiger Absatz |
.RP | Rechtsbündiger Absatz |
.IP | Zentrierter Absatz |
.TH | Header |
.SH | Sektion |
.SS | Unter-Sektion |
.TP | Listenpunkt |