Plain Old Documentation

Plain Old Documentation (POD) ist eine vereinfachte Auszeichnungssprache, die 1994 von Larry Wall mit Perl 5 eingeführt wurde, um Dokumentation in den Quelltext von Perl-Programmen einzufügen.

Eigenschaften von POD

POD ist eine einfache Sprache in mehrerer Hinsicht:

• einfach zu schreiben (für den Autor)
• leicht lesbarer Quellcode
• leicht zu parsen
• leicht in andere Sprachen und Formate umzuwandeln – etwa in UNIX-Manpages, LaTeX, troff oder HTML
• einfach, Quellcode darin unterzubringen

Verbreitung

POD ist die meistbenutzte Sprache, um Perlprogramme und -module zu dokumentieren, Perl selbst eingeschlossen, und ist auch Standard für die Dokumentation der Module im CPAN.

Beispiel-Dokument

Das folgende Dokument demonstriert die Verwendung aller Sprachelemente.

 =pod

 =encoding UTF-8

 =head1 TITEL

 podsample - A sample POD document

 =head1 ZUSAMMENFASSUNG

     $here->isa(Piece::Of::Code);
     print <<"END";
     Dieser eingezogene Block wird nicht nach Formatierungsanweisungen
     durchsucht und Leerzeichen bleiben erhalten.
     END

 =head1 BESCHREIBUNG

 Hier steht normaler Text, Es folgen
 B<fett>, I<kursiv>,
 S<langer Text ohne Zeilenumbruch>,
 C<$code> (formatierter Quellcode),
 E<Sonderzeichenname>, F<Dateiname>,
 L<Labeltext|Linkadresse>, X<Indexeintrag>.
 Z<Zeichen ohne Breite>

 =head2 Eine Liste

 =over 4

 =item * mit Blickfangpunkten.

 =item * noch ein Punkt.

 =back

 =begin html

 <img src="fig1.png" align="right" alt="Figure 1." />
 <p>
     Hier ist etwas eingefüger HTML-Code. Dieser Block kann
     Bilder beinhalten, und alles was du sonst noch so mit
     HTML tun kannst. POD parser die kein HTML ausgeben werden
     dies vollständig ignorieren.
 </p>

 =end html

 =head1 SIEHE AUCH

 L<perlpod>, L<perldoc>, L<Pod::Parser>.

 =head1 COPYRIGHT

 Copyright 2005 J. Random Hacker <jrh@example.org>.

 Permission is granted to copy, distribute and/or modify this
 document under the terms of the GNU Free Documentation
 License, Version 1.2 or any later version published by the
 Free Software Foundation; with no Invariant Sections, with
 no Front-Cover Texts, and with no Back-Cover Texts.

 =cut

Werkzeuge

Die folgenden Werkzeuge verarbeiten POD:

pod2html

erzeugt html aus POD

pod2latex

generiert LaTeX aus POD

pod2man

macht Manpages aus POD

pod2text

einfacher Text aus POD

pod2usage

druckt usage:-Zeile aus eingebettetem POD

pod2wiki

verwandelt POD in verschiedene Wikiformate, darunter auch mediawiki

podchecker

Syntaxchecker für POD

podselect

druckt ausgewählte Abschnitte aus POD auf stdout

Weitere Werkzeuge wie Pod

:ProjectDocs können die Dokumentation ganzer Projekte automatisiert beispielsweise nach HTML wandeln

Ähnliche Werkzeuge

• Javadoc
• Doxygen
• Natural Docs
• PhpDocumentor
• Sphinx

Literatur

• Wall, Larry; Christiansen, Tom; Orwant, Jon (2000). Programming Perl (3rd ed.). Sebastopol: O’Reilly & Associates. ISBN 978-0-596-00027-1.

Weblinks

• perlpod – Dokumentation zu POD für Autoren.
• perlpodspec – Dokumentation zu POD für Parserautoren.
• Perl-Manpages im POD-Format.
• Perl-Standardmodule mit eingebetteter Dokumentation im POD-Format.