L | F | D | W
Eigene Programme unter Linux bereitzustellen erfordern auch eine Dokumentation zur Benutzung. Eine Möglichkeit ist eine eigene MAN-Page. Unter vielen UNIX- und Derivaten werden MAN-Pages in einem Textsatzsystem groff erstellt. Groff ist eine erweiterte Implementierung von troff, welches Zusatzpakete bereitstellt, wie Doc und Man für Manpages. Um eine solche Seite zu erstellen, ist pandoc geeignet.
Zuerst installieren wir die nötigen Pakete.
$ sudo dnf install pandoc Erstellen einer MAN-Page
Wir stellen einen Ordner, in dem wir die nötigen Files erstellen können. Dazu kann man in jedem Editor eine Textdatei erstellen, die Markdown als vereinfachte Scriptsprache verwendet. Es ist aber nicht notwendig, viel über Markdown zu wissen.
Der Dateiname entspricht einer eigenen Konvention programm_name.1.md. Die Konvention entspricht denen, die für MAN-Pages üblich ist.
Die Kategorien sind mit Nummern versehen und weitgehenst standardisiert und eine einfache Liste findet ihr hier. In welche Kategorie euer Programm gehört, müsst ihr selbst entscheiden. Für unser Testprogramm verwenden wir einmal 1. Benutzerkommandos.
- Benutzerkommandos, z.B. ls
- Systemfunktionen, z.B. flock()
- Subroutinen (von Perl, Tcl etc.)
- Geräte(treiber) z.B. von XFree86
- Dateiformate, z.B. hosts
- Spiele, z.B. gnuchess
- Verschiedenes, z.B. netlink
- Systemverwaltung (Befehle für root), z.B. ifconfig
- Kernel (bei mir leer)
- neue Kategjen
- ...
Unser Programm soll hallo heißen und in einem Editor erstellen wir die Datei hallo.1.md. Dort tragen wir nun unseren Text ein.
Eine MAN-Seite besteht aus Beschreibungen, welche in einem mit "---" abgegrenzten Bereiche am Anfang der Datei stehen, gefolgt von einigen Kategorien, die man frei wählen kann, und die Beschreibung des Programms enthält.
---
title: Hallo
section: 1
header: Benutzeranleitung
footer: hello 1.0.0
date: 11.August 2022
---
# NAME
Hallo - Programm, um die zu begrüßen.
# SYNOPSIS
**hallo** [*OPTION*]...
# DESCRIPTION
**hallo** ist ein fiktionales Programm, das dir eine Begrüßung auf deer Comm andline ausgibt.
Es ist in Markdown geschrieben und mit pandoc konvertiert worden.
# OPTIONS
**-n **
: Die Begrüßung beinhaltet deinen Namen.
# EXAMPLES
**hallo -n Franz**
Liefert "Servus, Franz".
# AUTHORS
Von Philipp
Die Kategorien sollten alle enthalten sein und entsprechen den Basisinformationen in einer MAN-Page. Zusätzlich gibt es eine Reihe frei wählbarer Kategorien. Unter man man kann man sich diese heraussuchen.
Um jetzt aus der Textdatei eine MAN-Page zu erstellen, verwenden wir pandoc.
$ pandoc hello.1.md -s -t man -o hello.1 Und um jetzt die Ergebnis zu lesen.
$ man -l hello.1 Das Ergebnis unserer Seite sieht so aussehen.
Erstellen eines GZIP-Paketes und Installation
Um die neue Seite zu installieren, erzeugen wir mit gzip ein Paket und kopieren es ins Dateisystem. Selbst erstellte Pakete sollten unter /usr/local/man/man1/ abgelegt werden. Oder auch /usr/share/man/man1/. Jedoch ist dieser Platz für über das Repository installierte Programme vorgesehen.
$ gzip ~/hello.1 $ ls -l hello.1.gz $ sudo cp hello.1.gz /usr/local/man/man1 Zum Abschluss wird noch die MAN-DB neu geladen.
$ sudo mandb Jetzt kann man wie gewohnt mit
man hello sich die Seite anzeigen lassen. Löschen einer MAN-Page
rm /usr/bin/hello> rm /usr/local/man/man1/hello.gz sudo mandb Weitere Quellen und Suchbegriffe: man, man-pages, markdown, groff, pandoc, gzip.
geändert, 18. Nov 2022, 23:52
Copyright © 2025 by Philipp