Perlprogramme inline mit POD dokumentieren

Veröffentlicht von Thomas Fahle am (Permalink)

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

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.

Weitere Posts