Plain Old Documentation

Eine gesichtete Version dieser Seite, die am 10. August 2017 freigegeben wurde, basiert auf dieser Version.

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

=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@cpan.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^[1]
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

Literatur

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

Einzelnachweise

↑ Pod::Simple::Wiki auf CPAN.org

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.

[1] Pod::Simple::Wiki auf CPAN.org

[1]