Entwicklerhandbuch/Man-Pages

Aus Delixs
Version vom 27. April 2008, 21:31 Uhr von Kirmse (Diskussion | Beiträge) (Ergänzen der Textauszeichnungen und Erstellung der man-Page)
Zur Navigation springen Zur Suche springen
Uberarbeiten 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