1.5. Online Documentation

Fortunately, the documentation included with perl covers practically everything you could want to know about Perl. Unfortunately, practically everything you could want to know about Perl is an awful lot. Yet with a little guidance, you can very quickly learn how to navigate around it and save yourself gobs of time compared to the alternatives. The documentation is in the POD (Plain Old Documentation) format, a very simple markup language that's part of Perl.

Knowing your way around the documentation is an essential debugging tool. Because this is such an important point, we call attention to it with a device we use throughout this book for highlighting such tips, pompously called Perls of Wisdom:

Know the documentation. Be able to find anything in it.

(We have collected all these tips into a list in Appendix B for quick reference.) The most flagrant example of the consequences of ignoring this advice in recent years was the furor over the behavior of the localtime function after 1999. Many people looked at the value returned for the year and incorrectly assumed it was formed from the last two digits of the actual year, so they wrote windowing code or just tacked “19” in front of it to get the real year. Unfortunately, according to the Perl documentation,

… $year is the number of years since 1900, that is, $year is 123 in year 2023, and not simply the last two digits of the year. If you assume it is, then you create non-Y2K-compliant programs—and you wouldn't want to do that, would you?

As you can tell, some text was added by documenters who were becoming frustrated with the lack of attention this explanation was receiving.

In 1998 I was called to fix a program I had written over 10 years earlier on a VMS machine that was failing Y2K testing. I was surprised to see I had written windowing code assuming the year returned in a C tm struct contained only the last two digits, and as a result the program was printing dates in the year “19100”. After I fixed the program, I found the original VMS C manual I had used when writing it, and looked up localtime. Lo and behold, it announced that the year field contained the last two digits! (Such a bug would not survive long in Perl's documentation thanks to the open source process controlling it.)

1.5.1. Perl Documentation on Windows

If you're using the ActiveState port of perl for Microsoft Windows, the perldoc pages have been converted into pleasantly formatted hyperlinked HTML.^[7] You can reach it either through the Start button:

^[7] See the Getting Perl section in the Preface for information on how to obtain ActivePerl.

Programs -> ActivePerl -> Online Documentation

or by going to the html directory under the root of the installed ActivePerl, and opening the index.htm file there. Everything under Core Perl FAQ, Core Perl Docs, and most of the listings under Module Docs are also contained in the standard perl distribution you'll find on any other platform. If you click on Perl Documentation in the main frame, you'll be taken to the root of the core documentation for Perl itself rather than the pages created by ActiveState.

This is a good way to browse the documentation, and we quite like this interface. However, browsing isn't enough; you frequently need to pinpoint a particular section within one of the voluminous sections of documentation. Say you want to find out how to use split; you must go to the giant perlfunc page and scroll down to just the right point. To get around this problem, you can use the command line version, so let's jump into a tour of perldoc.

1.5.2. The perldoc Command

Every system with an installed perl distribution includes perldoc and the files it references. If it doesn't, ask the person who performed the installation to do it again properly. To provide a tool without the documentation to use it properly isn't technically one of the seven deadly sins, but we're lobbying to get it added in their next release.

Just typing perldoc by itself produces little output, but a tantalizing clue:

% perldoc
Usage: perldoc [-h] [-r] [-i] [-v] [-t] [-u] [-m] [-l]
[-F] [-X] PageName|ModuleName|ProgramName
       perldoc -f PerlFunc
       perldoc -q FAQKeywords

The -h option prints more help.  Also try "perldoc perldoc" to get aquainted with the system.

This is information on how perldoc itself works, useful if you're trying to find out more about the perldoc program, but not if you're looking for the Perl manuals. If you try either of the suggestions mentioned (perldoc -h or perldoc perldoc), you'll end up only with more verbose information about all the options perldoc can take.

The magic key to unlocking the door to the documents on the Perl language itself is perldoc perl:

% perldoc perl
[...]
     For ease of access, the Perl manual has been split up
     into a number of sections:
       perl             Perl overview (this section)
       perldelta        Perl changes since previous version
       perl5005delta    Perl changes in version 5.005
       perl5004delta    Perl changes in version 5.004
       perlfaq          Perl frequently asked questions
[...]

Bingo! All the different sections you can peruse with perldoc are laid out before you, which leads us to our second Perl of Wisdom:

To get started with the perl documentation, type perldoc perl.

The reason it's this way is that a behind-the-scenes equivalence exists between the perldoc sections and Unix manual pages. On Unix systems, the same sections can be read with the man command, and the master document is the one from man perl, which any Unix user would automatically use first to learn about Perl.

Now you can browse each of the different listed sections simply by typing perldoc followed by the section name:

% perldoc perldelta
NAME
     perldelta - what's new for perl5.005

DESCRIPTION
     This document describes differences between the 5.004
     release and this one.
[...]

The list of sections you see under perldoc perl has thoughtfully been arranged in a logical order for browsing. Here are our quick tips that tell you which section to use for a particular purpose:

• perlsyn: Perl programs are made up largely of variables being manipulated by function calls or operators. What's in between the variables, functions, and operators is syntax. Here you'll find all the information on, for instance, how looping statements work, and how to put an if modifier after a statement.

• perldata: This section tells you about all the different kinds of variables you can create in your programs. Don't look here for multidimensional arrays (lists of lists, in Perl parlance) though; we'll get to them.

• perlop: Here you'll learn all about Perl's vast panoply of operators, ranging from the mundane + - * / to the magical powers of applying postincrement (++) to strings. There are some entries you might not expect to find here: the use of commas to separate list members, the different ways of quoting strings and how interpolation works inside them, how the m// (match) and s/// (substitute) operators work (but the regular expressions they take as an argument are documented under perlre), the use of backticks to capture program output, reading lines from filehandles, and the mysteries of floating point numbers.

• perlre: This is where you can find out how to write regular expressions. Perl has easily the most powerful, “featureful” implementation of regular expressions anywhere. This section covers all the details from the most basic to the most advanced; read as far as you can without your head actually exploding and leave the rest for when you recover your strength.

• perllol: When you want to know how to implement multidimensional arrays, or complex data structures, this is the place to come. “lol” stands for “lists of lists,” which strictly speaking is a misnomer since it really means “arrays or hashes of references to arrays or hashes,” but is considerably more euphonious. If you've come from Pascal, Fortran, or C and are wondering where records or structs are, look no further. If you want to know all about how to make and use the references that enable lists of lists to be built, see perlref.

• perlsub: This contains everything you'd want to know about how to write your own subroutines (functions or procedures) in Perl and far, far more, including entries you might not expect to find, on the local command and typeglobs. Pick the parts you need judiciously and save the eye-glazing sections for later.

We've left out many of the sections to avoid overwhelming you at this stage. Head back to perldoc perl when you feel up to it to see the more advanced ones we omitted.

One less advanced section we failed to list is perlfunc. The reason is that only rarely in your career will you want to peruse perlfunc in linear order.^[8] That's because it consists of an alphabetical list of all Perl's myriad built-in functions, many of which you will never need. Fortunately, the -f option to perldoc allows you to name the function you're looking for:

^[8] That's an understatement. While understatement isn't a documented virtue of Perl programmers, it appears to be a virtue of Perl authors.

% perldoc -f split
split /PATTERN/,EXPR,LIMIT
split /PATTERN/,EXPR
split /PATTERN/
split

Splits a string into an array of strings, and returns it.
By default, empty leading fields are preserved, and empty
trailing ones are deleted.
[...]

One last feature of perldoc is worth explaining. The Perl documentation goes to superhuman lengths to answer frequently asked questions, so much so that the FAQ comprises nine files. Simply scanning the FAQ for a particular topic (and don't assume your question isn't there—it covers some broad ground) is a daunting task. But the alternative is to risk being scorched by a cast of thousands if you post your question to the Net. So perldoc makes it a little easier for you to tell if your question is frequently asked with the -q word option,^[9] which searches all the frequently asked questions (but not their answers) for word, and then shows you both the questions and their answers:

^[9] Actually, the argument can be a regular expression.

% perldoc -q sleep
Found in /usr/local/perl/lib/5.6.0/pod/perlfaq8.pod

How can I sleep() or alarm() for under a second?

If you want finer granularity than the 1 second that the sleep() function provides, [...]

You can see more information about the Perl FAQ (and the FAQ itself) at http://perlfaq.cpan.org/.

perldoc can also display the source of a module with the -m option, which saves you the trouble of searching @INC for it.

But what if you're looking for something in the entire set of Perl documentation? Time to use the tools your computer comes with. To find the POD files that mention “readline,”

• On Unix (using csh or a variant):

         % find `perl -e '$_="@INC";s/ .|. //;print'` 
  								-name "*.pod" -print | xargs grep -l readline
         /usr/local/perl/lib/5.00503/pod/perldebug.pod
         /usr/local/perl/lib/5.00503/pod/perlfaq5.pod
         /usr/local/perl/lib/5.00503/pod/perlfunc.pod
         /usr/local/perl/lib/5.00503/pod/perlmodlib.pod
         /usr/local/perl/lib/5.00503/pod/perlop.pod
         /usr/local/perl/lib/5.00503/pod/perltoc.pod
         /usr/local/perl/lib/5.00503/pod/perltrap.pod
  

  Explanation: We tell Perl to print the directories in which it searches for modules, remove the current directory from the list, then use the list as the argument to the find command to search for POD files whose names are printed by grep if they contain a match. These files should all be in the same directory, so once you know what it is, you can just grep in that directory and dispense with the find. (But remember that find command if later on you want to search all the .pm files for something.) To get more relevant hits for common terms, pipe the results through another grep that searches for =head; then you'll find matches only in headings.

• On Windows:

  In ActiveState Perl, navigate to the HTML directory under the root of the installation and use Tools -> Find in the Explorer to look for all files named *.html containing the text readline. If you have another build of Perl that didn't create HTML files from all the PODs, navigate to the root of the installation and find files named *.pod.

• On the Macintosh:

  Use shuck. (See the next section.)

1.5.3. Perl Documentation in MacPerl

The Perl port to the Macintosh by Matthias Neeracher includes a simple GUI utility application—shuck—to view POD files.^[10] As shown in Figure 1-1, shuck reads a POD file, then renders a properly formatted version of the file in a standard Mac floating window.

^[10] Again, refer to the Getting Perl section in the Preface for instructions on how to obtain MacPerl.