Anleitung: Eine Manpage für ein Bash-Skript erstellen

Manpages (Manual Pages) sind die traditionelle Form der Dokumentation für Kommandozeilen-Programme unter Unix-ähnlichen Betriebssystemen. Eine gut geschriebene Manpage bietet eine standardisierte und leicht zugängliche Referenz für die Benutzer Ihres Skripts.

Manpages werden mit dem roff-Textformatierungssystem geschrieben. Diese Anleitung zeigt die Grundlagen zur Erstellung einer eigenen Manpage.

1. Die Manpage-Quelldatei erstellen

Manpage-Dateien haben eine numerische Endung, die die Sektion angibt. Für benutzerdefinierte Skripte ist Sektion 1 üblich. Erstellen Sie eine Datei namens mein-skript.1.

Minimalbeispiel (mein-skript.1)

.\" Dies ist ein Kommentar
.TH MEIN-SKRIPT 1 "2025-01-01" "1.0" "User Commands"
.SH NAME
mein-skript \- eine kurze, einzeilige Beschreibung des Skripts
.SH SYNOPSIS
.B mein-skript
[\-f|--file FILE] [\-v|--verbose] [\-h|--help]
.SH DESCRIPTION
Eine ausführlichere Beschreibung, was das Skript tut, wofür es gedacht ist und wie es funktioniert. Hier können mehrere Absätze stehen.
.SH OPTIONS
.TP
\fB\-f, --file\fR \fIFILE\fR
Gibt die zu verarbeitende Eingabedatei an. Dies ist eine obligatorische Option.
.TP
\fB\-v, --verbose\fR
Aktiviert die ausführliche Ausgabe (verbose mode).
.TP
\fB\-h, --help\fR
Zeigt diese Hilfeseite an und beendet das Skript.
.SH AUTHOR
Ihr Name <ihre@email.com>

Wichtige groff-Makros

• .TH: Titel und Kopfzeile. Format: .TH <Titel> <Sektion> <Datum> <Version> <Manual-Name>
• .SH: Section Heading (Abschnittsüberschrift), z.B. NAME, SYNOPSIS.
• .B: Bold (fettgedruckter Text).
• .I: Italic (kursiver Text).
• \fB...\fR: Schaltet Fettdruck für einen Teil des Textes an (\fB) und wieder aus (\fR).
• \fI...\fR: Schaltet Kursivdruck an und aus.
• .TP: Beginnt einen eingerückten Absatz für die Beschreibung einer Option.

2. Manpage anzeigen und installieren

Vorschau anzeigen

Sie können die formatierte Manpage direkt aus der Quelldatei anzeigen:

man ./mein-skript.1

Systemweit installieren

Um die Manpage mit man mein-skript aufrufen zu können, muss sie an den richtigen Ort kopiert und die Manpage-Datenbank aktualisiert werden.

# Kopiert die Datei in das lokale Manpage-Verzeichnis
sudo install -g 0 -o 0 -m 644 mein-skript.1 /usr/local/share/man/man1/

# Aktualisiert den Manpage-Cache (kann je nach System variieren)
sudo mandb

Danach können Sie die Seite mit man mein-skript aufrufen.

3. Alternative: help2man verwenden

Wenn Ihr Skript bereits Standard-Flags wie --help und --version unterstützt und deren Ausgabe POSIX-konform ist, kann das Werkzeug help2man automatisch eine grundlegende Manpage-Struktur generieren.

1. help2man installieren:

   code[ copy ]

   # Debian/Ubuntu
   sudo apt install -y help2man
   

2. Manpage generieren:

   code[ copy ]

   help2man -n "eine kurze Beschreibung" -o mein-skript.1 ./mein-skript.sh
   

   • -n: Die Beschreibung für den NAME-Abschnitt.
   • -o: Die Ausgabedatei.

Die generierte Datei kann anschließend manuell verfeinert werden.

Fazit

Obwohl das roff-Format zunächst abschreckend wirken kann, ist die Erstellung einer einfachen Manpage unkompliziert. Sie verleiht Ihrem Skript ein professionelles Erscheinungsbild und ist die erwartete Form der Dokumentation in der Unix-Welt. Für einfache Skripte ist help2man eine hervorragende Möglichkeit, den Prozess zu beschleunigen.