Plain Old Documentation
Plain Old Documentation ( POD ) is a simplified markup language that Larry Wall introduced with Perl 5 in 1994 to insert documentation into the source code of Perl programs.
Properties of POD
POD is a simple language in several ways:
- easy to write (for the author)
- easy to read source code
- easy to parse
- easily convert into other languages and formats - such as UNIX - man pages , LaTeX , troff or HTML
- easy to put source code in
distribution
POD is the most widely used language for documenting Perl programs and modules, including Perl itself, and is also the standard for documenting modules in the CPAN .
Example document
The following document demonstrates the use of all language elements.
=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
Tools
The following tools process POD:
- pod2html
- creates html from POD
- pod2latex
- generates LaTeX from POD
- pod2man
- turns POD into man pages
- pod2text
- simple text from POD
- pod2usage
- prints usage: line from embedded POD
- pod2wiki
- converts POD into various wiki formats, including mediawiki
- podchecker
- Syntax checker for POD
- podselect
- prints selected sections from POD to stdout
- Other tools like pod
- : ProjectDocs can automatically convert the documentation of entire projects to HTML, for example
Similar tools
literature
- Wall, Larry; Christiansen, Tom; Orwant, Jon (2000). Programming Perl (3rd ed.). Sebastopol: O'Reilly & Associates. ISBN 978-0-596-00027-1 .
Web links
- perlpod - POD documentation for authors.
- perlpodspec - POD documentation for parser authors.
- Perl man pages in POD format.
- Standard Perl modules with embedded documentation in POD format.