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ügter 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 <[email protected]>.

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 mediawikiPod::Simple::Wiki auf CPAN.org 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.

Einzelnachweise

Kategorie:Vereinfachte Auszeichnungssprache Kategorie:Perl (Programmiersprache)