Perl Documentation Primer: Getting and Giving Perl Help (2/2) | WebReference

Perl Documentation Primer: Getting and Giving Perl Help (2/2)

To page 1current page
[previous]

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:

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:

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.


To page 1current page
[previous]

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

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