| home / programming / perl / perldoc / 2 |   [previous] |
|
|
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!
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:
=cutThus, 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.
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 perlpodAnd remember, you can always learn from the POD statements in any existing module on your system by typing:
perldoc -u module nameUsing 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.
| home / programming / perl / perldoc / 2 | [previous] |
Legal Notices, Licensing, Permissions, Privacy Policy.
Advertise | Newsletters | Shopping | E-mail Offers | Freelance Jobs 
Created: February 12, 2007
Revised: March 1, 2007
URL: http://webreference.com/programming/perl/perldoc/2.html
