Entwicklerhandbuch/Man-Pages: Unterschied zwischen den Versionen

Version vom 27. April 2008, 21:31 Uhr

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 pod2man in 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:

...

zurück | Hauptseite