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
=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
Ähnliche Werkzeuge
Literatur
- Wall, Larry; Christiansen, Tom; Orwant, Jon (2000). Programming Perl (3rd ed.). Sebastopol: O'Reilly & Associates. ISBN 978-0-596-00027-1.
Einzelnachweise
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.