Perl Documentation Primer: Getting and Giving Perl Help (2/2)
Perl Documentation Primer
Plain Old Documentation Basics
As mentioned on the previous page, you can embed POD statements
directly into your Perl scripts and modules, and can
elucidate the finer points of your code's functions. For modules,
this is particularly important; since the documentation you provide
is the only way the end user will know how to use your module, what functions are available, how
they're used, accessed (which ones are exported or
exportable), and so forth. POD documentation should also be used
to describe the basic intent and usage of the module in question,
and often also includes simple or extensive (or both) examples of
actual interface code. The POD documentation is nearly always the
first stop--and often the only stop--made by a Perl coder who is
interested in learning more about what your partricular module
has to offer. Indeed, the documentation entries on CPAN,
such as this one
CGI module, are taken straight from the
module's POD statements!
Each module on your system has (or most likely has) POD documentation
embedded within it; and that means that you can learn just about
everything you need to know about POD documentation by just examining
the actual module files (the
.pm files) that are in
your libraries. For example, here's a cut from the
module on one of my test systems (you can get just the POD
documentation for a module by using the
-u switch of
perldoc -u XML::Simple):
package XML::Simple; =head1 NAME XML::Simple - Easy API to maintain XML (esp config files) =head1 SYNOPSIS use XML::Simple; my $ref = XMLin([<xml file or string>] [, <options>]); ...
Even in this short example, we see some of the main POD statements and formats at work:
POD commands (or Command Paragraphs) are prefaced by an
=sign as the first character on a line, and they tell the POD formatter (such as
perldoc) to do something specific with the text that follows the command. In the example above, we created two top level header lines (via the
=head1command): NAME, and SYNOPSIS. By convention, top level headers are typically written in CAPITAL LETTERS.
A section of code is assumed to be POD formatting from the first instance of a POD command paragraph (via the
=sign) to a line with this command:
Thus, you can include POD statements anywhere in your Perl script or module; just be sure to bracket all of your POD formatting in each chunk with some type of POD command--usually starting with a
=itemcommand, and then ending with
=cut. For example:
=head1 NAME podex - a do nothing example script with POD =head1 SYNOPSIS perldoc podex =cut # actual perl code here use strict; use warnings; my %hashvar = (); # and now some more POD =head1 DESCRIPTION This is podex, a simple script that demonstrates POD statements, but otherwise does nothing at all useful.
In POD formatting blocks, Oridinary Paragraphs are those that begin in the far left column of the page. i.e., those that do not start with an
=. In the
XML::Simpleexample give above, this text:
XML::Simple - Easy API to maintain XML (esp config files)
will be displayed as an ordinary paragraph. Ordinary paragraphs are typically displayed by formatters exactly as you would expect them to be; as ordinary text, line wrapped at the edge of the terminal screen or browser window.
In POD formatting blocks, paragraphs that do not start with a
=and do not start in the far left column of the document are known as Verbatim Paragraphs. Verbatim paragraphs are intended to be displayed exactly as is; with no automated line wrapping or extraneous formatting. They are usually used for coding examples; and every line of a verbatim paragraph must begin with either a space or a tab. Again, from the
XML::Simpleexample above, these lines:
use XML::Simple; my $ref = XMLin([<xml file or string>] [, <options>]); ...
represent the beginning of a verbatim paragraph.
Thus, POD blocks in Perl scripts and modules consist of a mixture of command paragraphs, oridinary paragraphs and verbatim paragraphs. Several types of command paragraphs are available, each of which indicates a different type of formatting to the POD formatter. Some of the most useful are:
These commands produce headings, with
=head1being the highest level heading and
=head4being the lowest (somewhat like
<h4>in HTML). Of course, how the headings will be displayed in the resulting output will depend on the particular POD formatter. A text formatter (at least in its default use) like
perldocwill typically display headings as indented based on their level. Many PODs use only two header levels; and in fact older POD formatters may not recognize
=head4, so you may wish to avoid these.
Use these for the creation of indented lists.
=oversignifies the beginning of the list, and can optionally be followed by an
indentlevelthat signifies how far over the individual items should be (default is 4 ems).
=itemis used at the beginning of each item definition, follow it with either the item to be described (i.e., literal text), a
*for bulleted lists, or numbers for an ordered list. Finally, follow your item list with the
=backcommand to indicate to the formatter that you are finished with the list. You can nest
=overcommands within one another, but note that
=itemcommands should appear only within
=backblocks (and in fact the first thing in an
=backblock should be an
=item, unless there are no items in the block). You can use any amount of ordinary or verbatim paragraphs within your list, but you shouldn't use
=headcommands within a list.
Other command paragraphs that I won't go into detail here include
=cut, which I've already mentioned;
allows for the beginning of a POD block in the code but without any actual
formatting (so you can start a POD block in Perl code without having to
declare a new
=head command); and the
=for format commands that allow the
application a specific type of formatting to a block of text. Some of the
formats recognized by POD formatters include
In addition to the above commands and paragraph designations (which typically apply to blocks of text), specific control characters can be applied to smaller blocks of text within paragraphs, header and item labels. These allow for the automatic application of bolding, italics, and links, among other possibilities. For example:
This text will be B<bold>. This text will be I<italicized>. This text will be displayed as C<code>. This text will be a L<link|/Examples> to the Examples section of this document (the word "link" would actually be displayed as a link to Examples.
Many other formatting options and possibilities exist for the creation of POD text in your scripts and modules, but the above instructions represent the most common uses and should be plenty for you to get started with. If you'd like a more complete reference for POD documentation, then you'll find it in the same place as the rest of your Perl documentation:
And remember, you can always learn from the POD statements in any existing module on your system by typing:
perldoc -u module name
perldoc, you can learn about the specifics
of modules and many of the
finer points of Perl programming via the Plain Old
Documentation format. By adding POD statements to your code,
you'll enable others to leverage
utilities--to learn more about your scripts or modules.
Created: February 12, 2007
Revised: March 1, 2007