Perlprogramme inline mit POD dokumentieren

Was ist POD und wozu wird es verwendet?

• POD ist eine Abkürzung für "Plain Old Documentation".
• POD ermöglicht Dokumentation in den Quelltext von Perl-Programmen einzufügen.
• POD vermeidet die Suche nach der Dokumentation (Source und Dokumentation sind in einer Datei).
• POD ist einfach und schnell (es gibt nur sehr wenige Kommandos).
• POD senkt die Kosten für die technische Dokumentation ( mehrere Ausgabeformate sind möglich).

Werkzeuge zur Umwandlung von POD in andere Formate

• pod2html - erzeugt html aus POD
• pod2latex - generiert LaTeX aus POD
• pod2man - erzeugt Manpages aus POD
• pod2text - erzeugt einfachen Text aus POD

Allgemeines

Die Anzahl der Kommandos ist bewusst klein gehalten.

POD-Kommandos müssen am Anfang einer Zeile stehen, um als Kommandos erkannt zu werden.

Sie können POD-Kommandos überall im Source-Code verwenden, d.h. Sie können Dokumentation und Programm mischen.

Sie sollten eine Leerzeile zwischen den einzelnen Kommandos einfügen, damit die verschiedenen Interpreter mit Ihrer Dokumentation zurechtkommen.

Leerzeilen werden als Abschnittsende interpretiert.

Der Formatierer (Filter) setzt nicht gekennzeichneten Text in Abschnitte. Das Format der Abschnitte hängt vom Filter ab.

Eingerückter Text wird als Programmcode interpretiert und automatisch ohne Zeilenumbruch im bewährten Schreibmaschinenstil gesetzt.

Start und Ende

=pod

Beginn der Dokumentation. Optional, Sie können auch irgendein POD-Kommando verwenden.

=cut

Ende der Dokumentation. Zurück zu Perl. Sinnvoll, wenn Sie Code und Dokumentation mischen.

Hinweis: Häufig beginnt die Dokumentation nach dem Ende des Sourcecodes, z.B.:

__END__

=pod

=head1 Name
......

Lassen Sie eine Leerzeile zwischen der __END__-Anweisung und dem darauffolgenden POD-Kommando. Ansonsten erkennt der Filter das erste POD-Kommando häufig nicht.

Überschriften

=head1

Überschrift der Ebene 1

=head2

Überschrift der Ebene 2

Beispiel

=head1 Eine Überschrift der ersten Ebene

=head2 Eine Überschrift der zweiten Ebene

=head2 Eine Überschrift der zweiten Ebene

=head1 Eine Überschrift der ersten Ebene

Listeneinträge

=over N

Um N Spalten einrücken

=item Text

Listeneintrag

=back

Einrücken aufheben

Beispiel:

=over 4

=item  Listenpunkt
Text, der zu diesem Listeneintrag gehört.

=item Nächster Listenpunkt
Text, der zu diesem Listeneintrag gehört.

=back

Textformatierungen

I<TEXT>

Kursivdruck zum Hervorheben von Variablen

B<TEXT>

Fettdruck zum Hervorheben von Programmen und Aufzählungspunkten.

S<TEXT>

Text ohne Zeilenumbrüche

C<TEXT>

Code

L<name>

Link zu manpage
Das Literal manpage wird von den meisten Filtern automatisch angehängt. Es reicht also, wenn Sie L<foo(1)> schreiben.

F<File>

Dateinamen

X<Index>

Indexeintrag

E<Escape>

1. E<ISO-Latin-1-Entities>
Beispiele:
E<gt> = >, E<lt> = <, E<Otilde> = Õ

2. E<ASCII>
Beispiel: E<186> = º

Siehe auch

Werfen Sie einen Blick in den Source-Code verschiedener Perl-Module und legen Sie einfach los: so lernen Sie es am schnellsten.

• Wikipedia: Plain Old Documentation
• perldoc: perlpod