Perl Documentation Primer: Getting and Giving Perl Help (1/2)
Getting and Giving Help:
A Perl Documentation Primer
From time to time, even the most experienced programmers get stuck.
Whether the source of the blockage is a function call or included module that the programmer isn't fully acquainted with, problems related to the deployment of a working script on a new operating system (possibly with a different version of the Perl interpreter), or the never ending hunt for better, more efficient ways to do things, both beginning and seasoned Perl developers share the common need for documentation that will help them understand why their scripts are behaving the way they are; and how they can be altered to behave the way they should.
Many novice Perl coders, when they first begin the process of troubleshooting their Perl scripts, don't realize how much documentation is readily available. They assume that in order to get an answer to their specific dilemma, they must post a lengthy description of the issue in their favorite forum (and wait for the answer), or pore through pages and pages of O'Reilly's "Programming Perl"--also known as the "Camel Book" in the Perl community--hoping that their particular problem is mentioned. While there's nothing wrong with either of these approaches (and in some cases they might offer the best solutions), there's another source of Perl documentation often overlooked by Perl beginners that provides tutorials, detailed references, as well as frequently asked question lists and example coding constructs for specific Perl modules and scenarios. This is the "Plain Old Documentation" (POD) included with the Perl distribution and embedded in practically all publically available Perl modules. This Perl Primer explores both the use and creation of this vital Perl documentation.
When you (or your administrator) installed Perl on your system,
they more than likely1 also installed
perldoc, a Perl or
shell script that provides for the viewing of POD documentation on your
particular operating system platform. This script is typically placed
somewhere on your default search path (such as
in *NIX systems, or in the Perl bin directory on Windows).To access it, type
perldoc from your system's command
prompt, followed by the documentation file or module that you wish
to inquire about. As an example, let's start by having a look at what
perldoc says about itself. Go to your command prompt,
perldoc script was installed properly on your
machine, then you should see a page of documentation that looks
something like this:
NAME perldoc - Look up Perl documentation in Pod format. SYNOPSIS perldoc [-h] [-v] [-t] [-u] [-m] [-l] [-F] [-i] [-V] [-T] [-r] [-ddes- tination_file] [-oformatname] [-MFormatterClassName] ....
How it looks on your specific system may be slightly different from
above; since perldoc may behave slightly differently to accommodate the
idiosyncracies of individual platforms and displays. But it should still
perldoc automatically displays its output a
"page" (view screen) at a time. To advance to the next line of the
documentation press the
Enter key; and to advance to the
next page of documentation press the
Space bar. Simple, right?
If you want to leave the script before the documentation is complete,
just press the letter
Q on your keyboard, and you'll be
back at your command prompt. We'll come back specifically to the usage
perldoc in a moment; but for now, try experimenting with
perldoc requests on your own system:
perldoc CGI perldoc LWP::Simple perldoc URI::Escape perldoc perlfunc
On the first request, we bring up the documentation for the
CGI module, providing interface functions and
objects that help with the writing of CGI scripts. The second and third
requests pull up the documentation for the
URI::Escape modules, respectively. Notice that you can
specify the module exactly the way you would when you
it in your code, complete with double colons (you can also use a slash
between the module levels, if you like; i.e.,
but the double colon notation seems more intuitive to me).
automatically locates the documentation in question on your system; a
feature that I'll come back to in a moment.
The last request wasn't for a module at all. What exactly is
perlfunc, and where does it come from? It turns out that
in addition to documentation for each of the modules installed on your
perldoc can retrieve topical information about
Perl programming in general; and in fact, a great amount (if not all)
of the Camel book mentioned above can be found in POD formatted files
right on your own system!
perlfunc, for example, lists
all of the Perl built-in functions, just like chapter 3 of the Camel.
perldoc perlsec echoes a good chunk of chapter 6,
the parts specifically describing Perl's Taint Mode.
So how do you find out what general Perl documentation is available on your system? Again, it's simple:
perltoc includes the documentation Table of
Contents, with all of the possible general documentation pages. Feel free to explore this documentation at your
leisure, but a few that I specifically recommend include:
perldoc perlfaq perldoc perlcheat perldoc perlrun perldoc perlretut
Use that last one especially if you're trying to get your head around regular expressions for the first time.
Where Are the Docs?
In our examples above, we were able to retrieve documentation from
both modules that we've installed on our system as well as general
documentation pertaining to the Perl language. We also noted that
perldoc is able to find this information for us
automatically. But where does
perldoc look for the
For modules, the answer is easy: It locates the module by searching
through the directories listed in
to how a regular Perl script would find them. The documentation
is actually embedded within the modules; thus, if
can find the module, it can find its documentation. We'll talk a little
bit about how to embed POD statements in modules on the next page; but for
now, note that if you've not yet installed a module
on your system, you won't have direct access to its documentation.
And if you're unfamiliar with the
@INC array or modules
in general, you may want to review our earlier
primer on the subject.
In addition to modules,
perldoc will also search for
regular Perl scripts (which can also have embedded POD statements). To
perldoc adds the
standard search path directories on your system to those it examines;
i.e., it will look in the directories of your
environment variable for the named scripts.
But that's not all
perldoc looks for. To find generic
documentation, such as
perldoc also looks for files ending with a
suffix; either in any of the directories listed above, or in
pod subdirectories of those directories. To
see the exact file that
perldoc finds when you look
for a specific document, just add the
-l switch to the
# perldoc -l CGI /usr/share/perl/5.8/CGI.pm # perldoc -l perlfunc /usr/share/perl/5.8/pod/perlfunc.pod
Note, however, that the
-l switch will only locate those files that actually have some documentation within them, so you can't use it to find any potential file (i.e., it's possible that
perldoc actually found the file you were looking for; but if the file did not contain any POD statements then
perldoc just responds:
No documentation found for "foobar").
This search mechanism allows the Perl community to add documentation
for literally any topic that they can come up with; by just creating the
.pod file. Again, you can get a listing of
what's available on your system with
Glance through the
perldoc documentation again:
For most of your research needs, you'll only need to
perldoc followed by the name of the file
or module you're curious about to get the answers you need.
There are several command line switches available for
perldoc that will help you to refine--or even
broaden--your queries. Here's a few in particular
that I would like to draw your attention to:
perldoc -f funcname
You can use this to pull up the docs for a specific function in
perlfunc, to avoid having to scroll through the entire
perlfuncdocument. For example:
perldoc -f tell
perldoc -q faq expression
Specifically searches the
perlfaq2, etc.) for the existence of the
faq expressionin the question heading. For example:
perldoc -q "compare two dates"
perldoc -m module name
Displays the entire module, code, POD statements, and all. I sometimes use this if I want to look up something specific in a module quickly but can't remember exactly where on my system the module is physically located.
Of course, there are several other command line switches available to you. Be sure to experiment.
If for some reason you can't get to
perldoc on your system
(and you can't install it), there are other options.
http://perldoc.perl.org/ has the whole
thing formatted as HTML pages; as does
However, the documentation actually
on your system
is more likely to match the functionality of your actual Perl
distribution. Perl is a constantly growing and evolving language, and
it's possible that the version of the Perl interpreter you're using doesn't have a particular feature that's described in one of
the online repositories I mentioned above. Using your own copy of the
documentation--and perhaps even comparing your copy to the online copy--might
help you locate these discrepancies more readily.
Having learned the basics about
perldoc, you might now
want to include some Plain Old Documentation in your own scripts and
modules. On the next page, we'll have a look at
some of the basic commands you can use to do so.
1. I say "more than likely" because there is the chance that perldoc, or the complete documentation that it provides access to, was not included by default in your particular implementation's
perldistribution. For example, Debian installs require the installation of the
perl-docpackage to access the script; a package that is recommended for use with the
perlpackage but not required--and therefore not installed automatically.
Created: February 12, 2007
Revised: March 1, 2007