ubuntuusers.de

Manpage erstellen

Dieser Artikel wurde für die folgenden Ubuntu-Versionen getestet:


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

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.

./manvorlage.png
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

Diese Revision wurde am 21. August 2021 18:10 von tuxifreund erstellt.
Die folgenden Schlagworte wurden dem Artikel zugewiesen: Programmierung