Man-Pages für eigene Bash-Skripte generieren: pandoc, help2man und Installation

1. Warum eine echte man-Page professioneller wirkt als nur --help

Ein --help-Flag beantwortet nur die Frage, was gerade in diesem Terminal-Fenster nützlich ist, verschwindet aber wieder aus dem Sichtfeld, sobald der Bildschirm scrollt oder das Fenster geschlossen wird. Eine man-Page dagegen ist ein eigenständiges Dokument, das systemweit unter man toolname abrufbar ist, sich durchsuchen lässt und in dieselbe Kategorie fällt wie die Dokumentation von grep, tar oder ssh, was einem selbstgeschriebenen Tool sofort den Anschein eines vollwertigen Systemwerkzeugs gibt.

Für Nutzer signalisiert eine vorhandene man-Page zusätzlich, dass ein Tool ernst genommen und gepflegt wird, weil das Schreiben einer strukturierten Dokumentation Aufwand bedeutet, den ein reines --help-Flag nicht verlangt. Wer ein internes Tool an ein größeres Team oder gar als Open-Source-Projekt weitergibt, gewinnt mit einer man-Page spürbar an Glaubwürdigkeit, ohne dass die Kernfunktion des Tools sich ändert.

2. Aufbau einer man-Page: die Standard-Abschnitte

Jede man-Page folgt einer festen Konvention aus Abschnitten, angefangen mit NAME, einer einzeiligen Beschreibung, gefolgt von SYNOPSIS, der kompakten Aufrufsyntax mit eckigen Klammern für optionale Argumente. Danach folgt DESCRIPTION mit dem eigentlichen Fließtext, OPTIONS mit jedem Flag einzeln erklärt, und optional EXAMPLES, FILES, EXIT STATUS sowie SEE ALSO für verwandte Befehle.

Diese Struktur ist kein Selbstzweck, sondern eine über Jahrzehnte gewachsene Konvention, an die sich Nutzer von Unix-Systemen gewöhnt haben: Wer nach der Bedeutung einer Option sucht, blättert instinktiv zu OPTIONS, wer den korrekten Aufruf sucht, zu SYNOPSIS. Eine eigene man-Page, die sich an diese Reihenfolge hält, ist ohne Erklärung sofort navigierbar.

3. Quelle wählen: strukturierter Kommentarblock oder Markdown

Bevor die eigentliche man-Page entsteht, braucht es eine Quelle, aus der sie generiert wird, statt roh in troff-Syntax geschrieben zu werden. Zwei Ansätze haben sich etabliert: ein strukturierter Kommentarblock am Anfang des Bash-Skripts selbst, aus dem help2man zusammen mit der --help-Ausgabe eine man-Page baut, oder ein separates Markdown-Dokument, das pandoc direkt in das man-Format konvertiert.

Der Kommentarblock-Ansatz hat den Vorteil, Dokumentation und Code in derselben Datei zu halten, sodass eine Änderung an einer Option kaum vergessen werden kann, ohne auch die Doku anzupassen. Das separate Markdown-Dokument eignet sich dagegen besser für ausführlichere Dokumentation mit vielen Beispielen, weil Markdown deutlich angenehmer zu schreiben und zu versionieren ist als ein Kommentarblock voller Escape-Zeichen.

4. Mit pandoc aus Markdown eine man-Page erzeugen

pandoc konvertiert zwischen einer beeindruckenden Anzahl an Dokumentformaten, darunter auch von Markdown ins man-Format, sofern die Markdown-Datei mit einem YAML-Frontmatter beginnt, das Titel, Abschnittsnummer und Datum für den man-Header liefert. Die eigentlichen Inhaltsabschnitte werden als normale Markdown-Überschriften geschrieben, ## SYNOPSIS, ## OPTIONS und so weiter, die pandoc automatisch in die passenden troff-Makros übersetzt.

Der Aufruf pandoc mstool.1.md -s -t man -o mstool.1 erzeugt aus der Markdown-Quelle eine fertige man-Page, die sich sofort mit man ./mstool.1 lokal testen lässt, bevor sie installiert wird. Dieser Workflow eignet sich besonders für Tools, deren Dokumentation ohnehin schon als Markdown im Repository gepflegt wird, weil dieselbe Quelle dann sowohl für GitHub-Rendering als auch für die man-Page dient.

---
title: MSTOOL
section: 1
date: August 2026
---

# NAME

mstool - deploy and manage mironsoft services

# SYNOPSIS

**mstool** [**-h**|**--help**] *COMMAND* [*ARGS*...]

# DESCRIPTION

mstool automates deployment, log inspection and rollback for
mironsoft's internal services across staging and production.

# OPTIONS

**-h**, **--help**
: Show usage information and exit.

**--env** *ENVIRONMENT*
: Target environment, one of staging, production, local.

# EXAMPLES

mstool deploy --env staging
: Deploy the current build to the staging environment.

# SEE ALSO

**docker**(1), **aws**(1)

5. Mit help2man automatisch aus --help und --version generieren

help2man verfolgt einen anderen Ansatz: Statt eine separate Quelldatei zu pflegen, ruft es das Skript selbst mit --help und --version auf und baut daraus automatisch eine man-Page, geordnet in die Standard-Abschnitte. Das funktioniert erstaunlich zuverlässig, solange die --help-Ausgabe einer erkennbaren Struktur folgt, etwa einer Usage:-Zeile gefolgt von eingerückten Optionsbeschreibungen.

Der Vorteil gegenüber dem Markdown-Ansatz ist, dass Dokumentation und tatsächliches Verhalten praktisch nicht auseinanderlaufen können, weil die man-Page bei jedem Lauf frisch aus der lebenden --help-Ausgabe generiert wird. Zusätzliche Abschnitte wie ausführliche Beispiele oder ein SEE ALSO lassen sich über eine .h2m-Zusatzdatei einspeisen, die help2man an der passenden Stelle einfügt.

#!/usr/bin/env bash
set -euo pipefail

# mstool muss --help und --version sauber unterstuetzen, bevor help2man laeuft
help2man \
  --name="deploy and manage mironsoft services" \
  --section=1 \
  --no-info \
  --output=mstool.1 \
  ./mstool

man ./mstool.1  # lokal pruefen, bevor installiert wird

6. Troff/groff-Grundlagen verstehen, wenn man manuell schreibt

Sowohl pandoc als auch help2man erzeugen im Hintergrund Dateien im troff-Format mit dem man-Makropaket, in dem Abschnittsüberschriften mit .SH, fette Begriffe mit .B und kursive Begriffe mit .I markiert werden. Für die meisten Anwendungsfälle muss dieses Format nie von Hand angefasst werden, aber ein grobes Verständnis hilft, generierte Dateien bei Bedarf gezielt nachzubearbeiten, etwa um einen zusätzlichen Absatz einzufügen.

Wer eine man-Page komplett von Hand schreiben möchte, etwa weil weder pandoc noch help2man verfügbar sind, kommt um die grundlegenden troff-Makros nicht herum: .TH für den Kopfbereich mit Titel und Abschnittsnummer, .SH für jeden Hauptabschnitt und .PP für neue Absätze. Für ein einzelnes internes Tool lohnt sich dieser Aufwand aber selten, wenn pandoc oder help2man dieselbe Datei automatisiert erzeugen können.

7. Installation unter /usr/local/share/man und MANPATH

Selbst gebaute man-Pages, die nicht über ein Distributions-Paketmanagement verteilt werden, gehören konventionell nach /usr/local/share/man/man1/ für Abschnitt-1-Kommandos, benannt nach dem Muster toolname.1. Dieses Verzeichnis ist auf den meisten Linux-Distributionen bereits standardmäßig Teil des MANPATH, sodass man toolname sofort funktioniert, ohne dass Nutzer ihre Shell-Konfiguration anpassen müssen.

Ist das Verzeichnis auf einem minimalen System nicht im MANPATH enthalten, zeigt manpath die aktuell durchsuchten Verzeichnisse an, und ein Eintrag lässt sich über die Umgebungsvariable MANPATH oder die Datei /etc/man_db.conf ergänzen. Nach dem Kopieren der Datei sollte mandb beziehungsweise makewhatis aufgerufen werden, damit die neue Seite auch über man -k auffindbar wird.

#!/usr/bin/env bash
set -euo pipefail

readonly DEST_DIR="/usr/local/share/man/man1"
sudo mkdir -p "$DEST_DIR"
sudo install -m 644 mstool.1 "${DEST_DIR}/mstool.1"

# Man-Datenbank aktualisieren, damit man -k mstool findet
sudo mandb -q 2>/dev/null || sudo makewhatis "$DEST_DIR" 2>/dev/null || true

man mstool

8. In Paketierung und Makefile integrieren

Damit die man-Page nicht bei jedem Deployment manuell installiert werden muss, gehört die Generierung und Installation in dasselbe Makefile oder Build-Skript, das auch das eigentliche Tool baut und installiert. Ein make install-Target, das sowohl das ausführbare Skript nach /usr/local/bin/ als auch die man-Page nach /usr/local/share/man/man1/ kopiert, hält beide Artefakte synchron zur selben Version.

Für die Verteilung über ein echtes Paketformat wie .deb übernimmt das Paketierungswerkzeug selbst die korrekte Platzierung der man-Page und ruft nach der Installation automatisch mandb auf, sodass hier keine manuelle Nacharbeit durch den Endnutzer nötig ist.

# Makefile-Ausschnitt
PREFIX ?= /usr/local

.PHONY: install
install: mstool.1
	install -Dm755 mstool $(PREFIX)/bin/mstool
	install -Dm644 mstool.1 $(PREFIX)/share/man/man1/mstool.1
	mandb -q 2>/dev/null || true

mstool.1: mstool.1.md
	pandoc mstool.1.md -s -t man -o mstool.1

9. Pflege: die man-Page synchron zu --help halten

Eine man-Page, die beim Hinzufügen einer neuen Option vergessen wird, ist schlimmer als gar keine man-Page, weil sie aktiv falsche Informationen verbreitet und Nutzer in die Irre führt. Der help2man-Ansatz löst dieses Problem strukturell, weil die man-Page bei jedem Build frisch aus der aktuellen --help-Ausgabe entsteht und damit gar nicht veralten kann, solange der Build-Schritt Teil der Release-Pipeline ist.

Beim pandoc-Ansatz mit separater Markdown-Quelle hilft ein einfacher CI-Check, der die in --help gelisteten Optionen mit den in der Markdown-Datei dokumentierten Optionen abgleicht und den Build fehlschlagen lässt, wenn eine neue Option ohne zugehörigen Dokumentationseintrag hinzugefügt wurde. Dieser eine automatisierte Check verhindert die häufigste Ursache für veraltete Dokumentation zuverlässiger als jede manuelle Erinnerung im Pull-Request-Review.

10. Zusammenfassung

11. FAQ: Man-Pages für eigene Bash-Skripte: Das Wichtigste auf einen Blick