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

---

zurück | Hauptseite