Getting and Giving Help: A Perl Documentation Primer

[elsiddik]

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.


You can read this full article from : http://www.webreference.com/programming/perl/perldoc/


zaher el siddik
http://www.unixshells.nl/
http://elsiddik.blogspot.com/