Entwicklerhandbuch/Man-Pages
|
Diese Seite sollte nochmals überarbeitet werden. Eine Begründung befindet sich in der Regel unter Diskussion (oben). |
Man-Pages erstellen
- hier wird zum Erstellen der Man-Pages folgender Weg gewählt: es werden pod-Dateien erstellt und diese mit
pod2manin Man-Pages konvertiert.
Erstellung der pod-Dateien
Das pod-Format (POD = plain old documentation) ist ein sehr einfaches Format und ist ähnlich HTML eine Auszeichnungssprache.
Es soll hier schrittweise für das Init-Script ... aus der Seite vom Entwicklerhandbuch ... eine pod-Datei erstellt werden.
Strukturanweisungen
POD-Strukturanweisungen beginnen mit einem Gleichheitszeichen in der ersten Spalte. Strukturanweisungen werden vom umgebenden Text durch eine Leerzeile getrennt.
=head1 Überschrift Hauptüberschrift =head2 Überschrift Unterüberschrift =over N Startet einen Aufzählungsblock, N bestimmt, wieviel Leerzeichen die einzelnen Punkte eingerückt werden =item text Einzelner Punkt einer Aufzählung. Möchte man ein Aufzählungszeichen vor dem eigentlichen Text, so stellt man diesem ein Sternchen (*) voran. Möchte man eine numerierte Aufzählung, so muß man diese manuell numerieren. =back Beendet einen Aufzählungsblock
Bei einer Man-Page werden folgende Punkte erwartet:
- NAME - dieser Abschnitt beinhaltet den Namen des Programmes gefolgt von einem Bindestrich, gefolgt von einer kurzen Beschreibung des Programmes.
- SYNOPSIS - hier wird die Aufrufsyntax des Programmes angegeben
- DESCRIPTION - hier erfolgt eine etwas ausführlichere Beschreibung des Programms
- OPTIONS - hier werden Kommandozeilenparameter und -Optionen des programms erläutert, falls das Programm solche hat.
- FILES - hier werden externe Dateien angegeben, auf die das Programm zugreift
- DIAGNOSTICS - hier werden Fehlercodes des Programms angegeben
- REQUIRES - hier werden alle vom Programm benötigten Module oder Bibliotheken angegeben
- BUGS - wenn das Programm bekannte Fehler aufweisst, dann werden diese in diesem Abschnitt angegeben.
- SEE ALSO - dieser Abschnitt dient für Querverweise zu andern Programmen
- COPYRIGHT and LICENCE - hier sollte der Author und die Lizenz des Programms angegeben werden
die Grundstruktur der pod-Datei für unser Programm sieht so aus:
=head1 NAME my_bootlog - schreibt den Zeitpunkt des Bootens in ein Logfile =head1 SYNOPSIS my_bootlog start|status =head1 DESCRIPTION my_bootlog ermittelt beim Aufruf mit dem Parameter start die aktuelle Zeit und schreibt diese im Format ... in das File ... . Wird das Script mit status aufgerufen, dann wird der letzte Zeitpunkt des Bootens ausgelesen und angezeigt. =head1 OPTIONS =over 2 =item start das Script wird aufgerufen und schreibt die aktuelle Zeit ins Logfile =item status das Script liest die letzte Bootzeit aus dem Logfile =back =head1 REQUIRES Perl, '/usr/sbin/my_bootlog' =head1 COPYRIGHT and LICENCE Copyright (c) 2008. Hans-Dietrich Kirmse Dieses Programm steht unter der GPLv3.
Textauszeichnungen
Im nächsten Schritt werden die Textauszeichnungen vorgenommen. Folgende Textauszeichnungen sind möglich:
I<text> Text wir in italic dargestellt. (Für Hervorhebungen und Variablen) B<text> Text wir fett dargestellt. Für Programmnamen und Optionen. S<text> Text soll nicht umgebrochen werden. C<text> Text wird als Quellcode formatiert. L<text> Text wir als Link dargestellt. F<text> Text wird als Dateinamen formatiert. E<Zeichen> Dient der Darstellung von Sonderzeichen (z.B. E<lt>: "<", E<gt>: ">", E<sol>: "/", E<verbar>: "|")
damit ergibt sich für unsere pod-Datei nun:
=head1 NAME B<my_bootlog> - schreibt den Zeitpunkt des Bootens in ein Logfile =head1 SYNOPSIS B<my_bootlog start|status> =head1 DESCRIPTION B<my_bootlog> ermittelt beim Aufruf mit dem Parameter B<start> die aktuelle Zeit und schreibt diese im Format ... in das File F . Wird das Script mit B<status> aufgerufen, dann wird der letzte Zeitpunkt des Bootens ausgelesen und angezeigt. =head1 OPTIONS =over 2 =item B<start> das Script wird aufgerufen und schreibt die aktuelle Zeit ins Logfile =item B<status> das Script liest die letzte Bootzeit aus dem Logfile =back =head1 REQUIRES Perl, F</usr/sbin/my_bootlog> =head1 COPYRIGHT and LICENCE Copyright (c) 2008. Hans-Dietrich Kirmse Dieses Programm steht unter der GPLv3.
Speichern Sie diese ab unter my_bootlog.pod.
Erstellung der man-Page
Das Konvertieren in eine man-Page
Sie konvertieren die pod-Datei my_bootlog.pod mit folgenden Aufruf in eine man-Page:
pod2man my_bootlog.pod > my_bootlog.8
Sie sollten noch folgende Parameter mitgeben:
pod2man --center=" " --section=8 --release="my_bootlog 0.1" my_bootlog.pod > my_bootlog.8
dabei bedeutet:
- --center zentriert den Text, der am oberen Rand (hier " ") erscheinen soll
- --release der Text, der am unteren Rand erscheinen soll
- --section bestimmt, um was für eine Man-Page es sich handeln soll
Es gibt folgende Sectionen (Abschnitte):
- Abschnitt 1: Nutzerbefehle und Kommandos
- Abschnitt 2: System-Aufrufe
- Abschnitt 3: Subroutinen und Bibliotheksaufrufe
- Abschnitt 3p: Perl-Module
- Abschnitt 3tcl: Tcl-Module (stattdessen oft auch in Abschnitt n)
- Abschnitt 4: Geräte und Spezialdateien
- Abschnitt 5: Dateiformate
- Abschnitt 6: Spiele
- Abschnitt 7: Verschiedenes, Makropakete und Konventionen
- Abschnitt 8: Systemverwaltung
- Abschnitt 9: Kernelverwaltung
- Abschnitt n: Neu
Bearbeiten der deutschen Umlaute
Da Groff (das Anzeige-Programm für die man-Pages) mit Umlauten nicht zurecht kommt, müssen diese noch codiert werden:
ä => \[char228] ö => \[char246] ü => \[char252] Ä => \[char196] Ö => \[char246] Ü => \[char220] ß => \[char223]
Das kann man so erledigen:
...