Abb. 1 - manuals zu rot13(1)
Das »größte Leid« der meisten Programmierer ist die Dokumentation der eigenen Programme. Ab Perl 5 wird mit POD (Plain Old Documentation) ein Verfahren angeboten, mit dem sich Programme bereits während der Entwicklung dokumentieren lassen. POD ist eine einfach, strukturierte Markup-Sprache die nicht allein auf die Dokumentation von Perl-Code beschränkt ist.
Die POD-Kommandos können überall im Quell-Code genutzt werden, das bedeutet Programm und Dokumentation lassen sich beliebig mischen. Aus dem so gefertigten »dokumentierten Programm« lassen sich dann verschiedene Ausgabeformate wie beispielsweise HTML, LaTeX, ASCII oder »Manualseiten« generieren.
Wie bei anderen Markup-Sprachen auch, benutzt POD Tags zur Formatierung des Textes.
Alle POD-Strukturanweisungen beginnen mit dem Zeichen »=«, die Dokumentation wird mit =pod eingeleitet und mit =cut wird deren Ende angezeigt. Handelt es sich um eine »reine Dokumentation« (also ohne Quelltext), müssen diese Anweisungen nicht angegeben werden.
Der Umfang der Strukturanweisungen wurde bewusst klein gehalten.
| =head1 | Überschrift der ersten Ebene, (»Hauptüberschrift«) |
| =head2 | Überschrift der zweiten Ebene, (»Unterüberschrift«) |
| =over n | Aufzählung die um n Stellen eingerückt ist. |
| =item | Einzelner Punkt einer Aufzählung. |
| =back | Beendet den Aufzählungsblock. |
Die einzelnen Strukturanweisungen müssen am Anfang einer Zeile stehen, um als solche erkannt zu werden.
Ausserdem kann die Dokumentation mit den folgenden Anweisungen formatiert werden:
| I<text> | Text wird kursiv dargestellt, für Hervorhebungen und Variablen |
| B<text> | Text wird 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 Dateiname formatiert. |
| E<zeichen> | Dient der Darstellung von Sonderzeichen, beispielsweise, |
E<lt> < |
|
E<gt> > |
|
E<sol> / |
|
E<verbar> | |
|
| Weitere Zeichen lassen sich durch die entsprechende ASCII-Nummer darstellen, also beispielsweise | |
E<187> |
Das folgende Listing rot13.pl zeigt ein einfaches Perl-Skript, welches eine bei Aufruf übergebenene Zeichenkette verschlüsselt. Der zugrunde liegende Algorithmus ist relativ einfach, jedes Zeichen der übergebenen Zeichenkette wird um eine bestimmte Anzahl von Buchstaben im Alphabet nach vorne verschoben. Dieser Wert kann optional bei Aufruf des Skriptes angegeben werden, sonst beträgt er 13.
#!/usr/pkg/bin/perl -w
#
use Getopt::Long;
use Crypt::Rot13;
GetOptions(
"key=i" => \$key,
"string=s" => \$string
);
$default_key = 13;
die "Aufruf: $0 --string <text> [--key <int>]\n"
unless defined $string;
$length = $key ? $key : $default_key;
$cipher_str = new Crypt::Rot13;
$cipher_str->charge($string);
print $cipher_str->rot13($length), "\n";
=pod
=head1 NAME
B<rot13.pl> - Programm zur Verschluesselung von Daten
nach der Caesar-Addition
=head1 SYNOPSIS
B<rot13.pl> [B<--string> I<text>] [B<--key> I<int>]
=head1 DESCRIPTION
Das Skript B<rot13.pl> gibt den per B<--string>-Option
angegebenen Text verschluesselt aus. Ueber die Option
B<--key> kann eine bestimmte Schluessellaenge angegeben
werden, andernfalls wird von einer Laenge von I<13>
ausgegangen. Das betreffende Resultat wird auf dem
Terminal ausgegeben.
=head1 OPTIONS
=over 4
=item [B<--string> I<text>]
Angabe eines Textes der verschluesselt werden soll.
Besteht der Text aus mehreren Woertern, sind diese
in Hochkommata anzugeben.
=item [B<--key> I<int>]
Optionale Angabe der Schluessellaenge, unterbleibt die
Angabe, wird die Laenge auf I<13> festgelegt. Dieser Wert
kann ueber die Variable I<$default_key> angepasst werden.
=back
=head1 EXAMPLES
Verschluesselung des Strings I<hallo> mit der vorgegebenen
Schluessellaenge
$ rot13.pl --string hallo
Verschluesselung des Strings I<hallo dolly> mit der
vorgegebenen Schluessellaenge
$ rot13.pl --string "hallo dolly"
Verschluesselung des Strings I<hallo dolly> mit einer
Schluessellaenge von I<8>
$ rot13.pl --string "hallo dolly" --key 8
=head1 REQUIRES
Perl 5, Getopt::Long, Crypt::Rot13
=head1 AUTHOR
Thomas Lingmann E<lt>tl@noatun.netE<gt>
=cut
Das Resultat kann über den Aufruf perldoc rot13.pl angezeigt werden.
Die Konvertierung des POD-Textes in das entsprechende Ausgabeformat kann mit folgenden Kommandos vorgenommen werden<:
| pod2html | HTML-Seiten |
| pod2latex | LaTeX-Dokumente |
| pod2man | Manualseiten im nroff/troff-Format |
| pod2text | ASCII-Datei |
| pod2usage | Kurzhilfe |
Den jeweiligen Programmen können bei Aufruf unterschiedliche Parameter übergeben werden. Eine Manualseite kann beispielsweise durch folgenden Aufruf generiert werden:
$ pod2man --center=" " --section=1 rot13.pl > rot13.1
Bei diesem Aufruf wird mit -center die Überschrift des manuals »geändert«. Normalerweise wir hier der Text User Contributed Perl Documentation ausgegeben. Über -section wird angegeben welchem Bereich das manual zugeordnet werden soll. Das manual zu man(1) erläutert die Einteilung der einzelnen Bereiche. So gehören Benutzerprogramme in Abschnitt 1, Systemaufrufe in Abschnitt 2 bzw.3, Informationen zu Gerätetreibern und -dateien in Abschnitt 4, Dateiformate in Abschnitt 5, Spiele in Abschnitt 6, Administrationsprogramme und -aufrufe in Abschnitt 8 und alle anderen, die sich anderswo nicht einordnen lassen, in Abschnitt 7.
Das Resultat lässt sich durch folgenden Aufruf anzeigen
$ nroff -man rot13.1 | less
und sieht beispielsweise wie folgt aus:
Abb. 1 - manuals zu rot13(1)
Damit die Manualseite auch über das Programm man gefunden wird ist sie in das entsprechende Unterverzeichnis von ~/man/ (auf das Beispiel bezogen also ~/man/man1/) zu kopieren.
Damit das manual auch über das Programm apropos bzw. whatis gefunden wird, ist zunächst noch ein weiterer Schritt auszuführen. Beide Programme greifen nicht direkt auf die manuals zu, sondern benutzen eine daraus generierte Indexdatei (whatis.db). Wurden durch den Systemadministrator neue Manualseiten installiert, muss der Index neu generiert werden. Dazu ist von root das Programm /usr/libexec/makewhatis auszuführen, mit dem die Indexdatei aktualisiert wird.
Die weiteren Ausgabeformate können unter Aufruf des entsprechenden Programmes analog erzeugt werden. Um die »Besonderheiten« unterschiedlicher Ausgabeformate besser berücksichtigen zu können, können einzelne Abschnitte der Dokumentation über die Anweisung for sowie über begin und end unterschiedlich ausgegeben werden.
Auf diese Weise kann beispielsweise ein unterschiedliches Format für Graphiken bei HTML-
=begin html
<p>
<img src="images/graph.png">
</p>
=end html
und LaTeX-Dokumenten berücksichtigt werden.
=begin latex
\includegraphics{images/graph.eps}
=end latex
Soll dagegen eine Manualseite oder ein ASCII-Datei generiert werden, werden beide Anweisungen von dem Filterprogramm ignoriert.
Das Programm pod2usage generiert keine Dokumentation »im eigentlichen Sinne«, sondern gibt den Aufruf des Programmes einschliesslich der betreffenden Parameter aus.
$ pod2usage rot13.pl
Usage:
rot13.pl [--string *text*] [--key *int*]
$