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 for the CGI module, are taken straight from the module's POD statements!

POD Paragraphs

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 XML::Simple module on one of my test systems (you can get just the POD documentation for a module by using the -u switch of perldoc; i.e., 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 =head1 command): 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:
```
=cut
```
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 =head or =item command, 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::Simple example 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::Simple example 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:

=head1 through =head4

These commands produce headings, with =head1 being the highest level heading and =head4 being the lowest (somewhat like <h1> through <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 perldoc will 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 =head3 or =head4, so you may wish to avoid these.
=over, =item, and =back

Use these for the creation of indented lists. =over signifies the beginning of the list, and can optionally be followed by an indentlevel that signifies how far over the individual items should be (default is 4 ems). =item is 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 =back command to indicate to the formatter that you are finished with the list. You can nest =over commands within one another, but note that =item commands should appear only within =over and =back blocks (and in fact the first thing in an =over and =back block 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 =head commands within a list.

Other command paragraphs that I won't go into detail here include =cut, which I've already mentioned; =pod which 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 =begin, =end, and =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 html, text, and man.

POD Formatting

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:

perldoc perlpod

And remember, you can always learn from the POD statements in any existing module on your system by typing:

perldoc -u module name

Conclusion

Using 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 perldoc--or similar utilities--to learn more about your scripts or modules.

[previous]

Created: February 12, 2007
Revised: March 1, 2007

URL: http://webreference.com/programming/perl/perldoc/2.html