Manpage erstellen
Dieser Artikel wurde für die folgenden Ubuntu-Versionen getestet:
Ubuntu 20.04 Focal Fossa
Du möchtest den Artikel für eine weitere Ubuntu-Version testen? Mitarbeit im Wiki ist immer willkommen! Dazu sind die Hinweise zum Testen von Artikeln zu beachten.
Zum Verständnis dieses Artikels sind folgende Seiten hilfreich:
Die Handbuchseite ("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.
Programme¶
Texteditor¶
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].
Gmanedit¶
Folgendes Paket muss installiert [4] werden:
gmanedit (universe)
Befehl zum Installieren der Pakete:
sudo apt-get install gmanedit
Oder mit apturl installieren, Link: apt://gmanedit
Benutzung/Konfiguration¶
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.
Struktur einer Manpage¶
Header¶
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" |
Sektionen¶
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.
Speicherorte¶
Üblicherweise werden englische Hilfeseiten unter /usr/share/man/man1 (aus Debian-Paket) bzw. /usr/local/share/man/man1 (andere Installations-Methoden) abgelegt. Die deutschen Seiten liegen analog unter /usr/share/man/de/man1 bzw. /usr/local/share/man/de/man1.
Markup¶
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" |
\fP | Beendet die Textformatierung "fettdruck" |
\fR | Beendet die Textformatierung "unterstrichen" |
.LP | Linksbündiger Absatz |
.RP | Rechtsbündiger Absatz |
.IP | Zentrierter Absatz |
.TH | Header |
.SH | Sektion |
.SS | Unter-Sektion |
.TP | Listenpunkt |
Links¶
dpkg-www - Manual Pages auf einem Webserver bereitstellen