Online Documentation

Perl comes with about 15,000 pages of online documentation. This book doesn’t reproduce all this documentation, but instead tells you how to access it. (Sets of books are available for purchase that contain a paper copy of most of the online documentation, but they are expensive, out-of-date, and more difficult to access than the stuff that comes with Perl.) Why use your own money when there is a book 15,000 pages long right on your hard drive?

Perl’s online documentation makes a reference manual unnecessary if you know how to tickle Perl in such a way that it gives you the information you want. In the next few sections, you learn how to do just that.

perldoc

The main way to access Perl’s documentation is through the perldoc command. For example, to find out about Perl itself, use the following command:

$ perldoc perl

This example uses $ as the command prompt. That’s the default UNIX/Linux prompt. If you are using Microsoft Windows, the prompt may look like C:WINDOWS>.

The perldoc perl command prints the top-level Perl document. This document contains a list of the other documentation that gives details on the various parts of Perl. For example, the command perldoc perlvar discusses the built-in Perl variables, and perldoc perlrun tells you how to run Perl.

Suppose that while looking at a program you see that the code uses the operator !~. If you don’t know what this operator does, you can use the online documentation to find out. First stop is the main Perl documentation page, which is obtained with the command

$ perldoc perl

Looking through the list of documentation, you see the lines

... 
perlsyn             Perl syntax 
perlop              Perl operators and precedence 
perlre              Perl regular expressions 
...

It looks like the perlop document might be of use, so you take a look at that with the command

$ perldoc perlop

Looking through this document, you find the definition of the operator !~. (It compares a string against a regular expression and returns true if the result is false—more on this in Chapter 4, “Regular Expressions.”)

Function Definitions

Perl comes with many built-in functions. If you want to find out what a particular function does, you can read the perlfunc documentation—all 7,000 lines of it. Or you can ask perldoc to give you information on a specific function.

For example, if you want to find out what the function join does, use the following command:

$ perldoc –t –f join

The result looks like

join EXPR,LIST 

Joins the separate strings of LIST into a single string with fields 
separated by the value of EXPR, and returns that new string. 
Example: 

    $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell); 

See split

From this, you can see that this function has something to do with joining together the items of a LIST. In this case, the documentation uses uppercase words such as LIST to indicate a variable. In this case, EXPR is a string expression such as ':', and LIST is a list of items such as $login, $password, and so on.

In this example, perldoc has two options. The –t option tells perldoc to use its internal formatter to format the text. If this option is not present, it tries to use the nroff command. The other option, –f, tells perldoc that you want information on a built-in function, in this case join.

Module Documentation

Perl not only consists of a core language, but also many modules. To find out about a module, use the command

$ perldoc module-name

That’s if you know the name of the module. If you don’t, you can find out which modules are installed on your system by looking through the Perl library directory. The actual search commands are system-dependent.

Finding Modules (UNIX/Linux)

To search for modules on UNIX or Linux, use the command

$ find /usr/lib/perl5 –name "*.pm" –print

(If your Perl is installed in some other directory, say /usr/local, you’ll need to adjust the directory used in the find command.)

For example, a typical run might look like

$ find /usr/lib/perl5 –name "*.pm" –print 
/usr/lib/perl5/5.00503/AnyDBM_File.pm 
/usr/lib/perl5/5.00503/AutoLoader.pm 
/usr/lib/perl5/5.00503/AutoSplit.pm 
/usr/lib/perl5/5.00503/Benchmark.pm 
/usr/lib/perl5/5.00503/CPAN/FirstTime.pm 
/usr/lib/perl5/5.00503/CPAN/Nox.pm 
/usr/lib/perl5/5.00503/CPAN.pm 
....

The Perl modules end in .pm. From the preceding code example, you can see that a module called AnyDBM_File is installed. To find out what this module does, use the command

$ perldoc AnyDBM_File 
AnyDBM_File(3) User Contributed Perl Documentation AnyDBM_File(3) 


NAME 
       AnyDBM_File – provide framework for multiple DBMs 

       NDBM_File, DB_File, GDBM_File, SDBM_File, ODBM_File – 
       various DBM implementations 

SYNOPSIS 
           use AnyDBM_File; 


DESCRIPTION 
       This module is a "pure virtual base class"––it has nothing

In the directory listing, you can see that the directory CPAN holds a couple files (Nox.pm and FirstTime.pm). These are submodules. To find the documentation for these files, you need a slightly different perldoc command. For example, to find information on the Nox.pm module (in the CPAN directory), you need the following command:

$ perldoc CPAN::Nox

Searching for Modules (Microsoft Windows)

To search for module files under Microsoft Windows, open an MS-DOS command session. You’ll need to know in which directory your Perl package is installed. (If you forget which directory it is, you can execute the command PATH to display your path settings. The Perl program should be in your path.) This example assumes that you installed it in the default directory C:PERL. To find the modules, execute the command

C:WINDOWS> dir/s/p C:PERL*.pm

All your Perl modules will be listed. Now you can use the perldoc command to extract the information from them as described in the previous section.

How to Print Nice-Looking Documentation

Perl keeps its documentation in a format called POD (Plain Old Documentation). It’s easily converted into a wide variety of formats such as HTML, LaTeX, man, and text.

By default, the perldoc command turns POD into text for display on a terminal. You can turn it into HTML by using the command

$ perldoc –u subject | pod2html >file.html

Next, you can use your web browser (Netscape, Internet Explorer, or other browser) to view and print the file.

For example, if you are on UNIX or Linux, you can view the results using the command

$ netscape file.html

On Microsoft Windows, you can double-click on the Internet Explorer icon and then use the File, Open command to open the file.