|
Plain Old Documentation, commonly abbreviated as POD, is a simple
platform-independent documentation tool for the computer language
Perl.
Intent
POD is designed to be a simple, clean language with just enough syntax to be useful. It purposefully does not include built-in mechanisms for fonts, images, colors or tables; instead it attempts to be just large enough to be useful. Some of its goals are:
- Easy to parse
- Easy to convert to other languages, such as HTML or TeX
- Easy to include sample code in
- Easy to read without a POD formatter (i.e. in its source-code form)
- Easy to write in--otherwise programmers won't write the documentation!
Although the author of perlpod (http://www.perldoc.com/perl5.8.0/pod/perlpod.html) notes that "The
Pod format is not necessarily sufficient for writing a book", books have in fact been written in an
extended version of POD; this special version included formatting codes for tables and footnotes,
and is used by O'Reilly & Associates to produce several Perl books, most notably
Programming Perl by Larry Wall, Tom Christiansen, and Jon Orwant.
Use
POD is the language used for most documentation in the Perl world. This includes Perl itself,
nearly all publicly-released modules, many scripts, most
design documents, many articles on Perl.com (http://www.perl.com/) and other Perl-related web sites,
and the Parrot virtual machine.
POD is rarely read in the raw, although it is designed to readable without the assistance of a
formatting tool. Instead, it is read with the perldoc tool, or converted into Unix
man pages or Web-standard HTML pages.
Pure POD files usually have the extension .pod, but POD is mostly used directly in Perl
code, which typically uses the .pl and .pm extensions. (The Perl
interpreter's parser is designed to ignore POD in Perl code.)
Sample POD Document
This document is syntactically correct POD, which attempts to follow the major conventions on
section naming as well.
=head1 TITLE
podsample - A sample POD document
=head1 SYNOPSIS
$here->isa(Piece::Of::Code);
print <<"END";
This indented block will not be scanned for formatting
codes or directives, and spacing will be preserved.
END
=head1 DESCRIPTION
Here's some normal text. It includes text that is
B<bolded>, I<italicized>, U<underlined>, and
C<$code>-formatted.
=head2 An Example List
=over 4
=item * This is a bulleted list.
=item * Here's another item.
=back 4
=begin html
<img src="fig1.png" align="right" alt="Figure 1." />
<p>
Here's some embedded HTML. In this block I can
include images, apply <span style="color: green">
styles</span>, or do anything else I can do with
HTML. POD parsers that aren't outputting HTML will
completely ignore it.
</p>
=end html
=head1 SEE ALSO
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
POD Formatting Details
POD files are written in an ASCII-compatible encoding, such as Latin-1 or Unicode.
A POD parser always assumes that the file it is parsing doesn't start with POD; it ignores all lines
until it sees a POD directive. POD directives must come at the beginning of a line, and all begin
with an equal sign. The POD parser will then assume that all following lines are POD, until it
encounters a line consisting of the "=cut" directive. Any content following that is ignored until
the parser encounters another POD directive. Thus, POD can be intermixed with executable source
code if the language's parser knows how to recognize and ignore POD.
POD content is divided into paragraphs by empty lines. Paragraphs that begin with
whitespace characters--tabs or spaces--are considered to be "verbatim paragraphs", and are left
completely unformatted; these are used for sample code, ASCII art, etc. Paragraphs that begin
with an equal sign are "command paragraphs"; the sequence of alphanumeric characters immediately
following the equal sign is treated as a POD directive, and the rest of the paragraph is formatted
according to that directive. Some directives also affect the following paragraphs. If a paragraph
starts with something besides an equal sign or whitespace, it's considered an "ordinary paragraph".
Both ordinary paragraphs and the contents of command paragraphs are parsed for formatting codes.
Formatting in POD is very plain; it's mainly limited to bold, italic, underlined, monospaced, and a
few other formats. There is also a code for linking between POD documents or to another section
within the same document. Formatting codes consist of either:
- A single uppercase letter, followed by a greater-than sign (<), the content to be formatted, and a less-than sign (>), e.g.
B<bolded text>, or
- A single uppercase letter, two or more greater-than signs (<<), a space, the content to be formatted, another space, and the same nuber of less-than signs as were used before, e.g.
B<< bolded text >>. This form is often used for code snippets containing a greater-than sign, which would otherwise end the formatting code.
Commands in POD include four levels of headings, bulleted and numbered lists, and commands to mark
sections as being in another language. The latter feature allows for special formatting to be
given to parsers that support it.
See also
References
External links
|
