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

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

current pageTo page 2
[next]

Getting and Giving Help:

A Perl Documentation Primer

By Dan Ragle

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.

Introducing perldoc

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 /usr/bin 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, and type:

perldoc perldoc

If the 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 be legible. 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 of perldoc in a moment; but for now, try experimenting with some different 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 well known 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 LWP::Simple and URI::Escape modules, respectively. Notice that you can specify the module exactly the way you would when you use it in your code, complete with double colons (you can also use a slash between the module levels, if you like; i.e., perldoc URI/Escape, but the double colon notation seems more intuitive to me). perldoc 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 system, 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. And 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:

perldoc perltoc

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 documentation?

For modules, the answer is easy: It locates the module by searching through the directories listed in @INC, similar to how a regular Perl script would find them. The documentation is actually embedded within the modules; thus, if perldoc 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 facilitate this, perldoc adds the standard search path directories on your system to those it examines; i.e., it will look in the directories of your PATH environment variable for the named scripts.

But that's not all perldoc looks for. To find generic documentation, such as perlfaq and perlre, perldoc also looks for files ending with a .pod 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 command:

# 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 appropriate .pod file. Again, you can get a listing of what's available on your system with perldoc perltoc.

More perldoc Tricks

Glance through the perldoc documentation again:

perldoc perldoc

For most of your research needs, you'll only need to type 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:

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. https://perldoc.perl.org/ has the whole thing formatted as HTML pages; as does ActiveState. 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 perl distribution. For example, Debian installs require the installation of the perl-doc package to access the script; a package that is recommended for use with the perl package but not required--and therefore not installed automatically.


current pageTo page 2
[next]

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

URL: https://webreference.com/programming/perl/perldoc/index.html