Programming Perl, 3rd Edition

Online Documentation

Perl's extensive online documentation comes as part of the standard Perl distribution. (See the next section for offline documentation.) Additional documentation shows up whenever you install a module from CPAN.

When we refer to a "Perl manpage" in this book, we're talking about this set of online Perl manual pages, sitting on your computer. The term manpage is purely a convention meaning a file containing documentation--you don't need a Unix-style man program to read one. You may even have the Perl manpages installed as HTML pages, especially on non-Unix systems.

The online manpages for Perl have been divided into separate sections, so you can easily find what you are looking for without wading through hundreds of pages of text. Since the top-level manpage is simply called perl, the Unix command man perl should take you to it.^[1] That page in turn directs you to more specific pages. For example, man perlre will display the manpage for Perl's regular expressions. The perldoc command often works on systems when the man command won't. On Macs, you need to use the Shuck program. Your port may also provide the Perl manpages in HTML format or your system's native help format. Check with your local sysadmin--unless you're the local sysadmin.

Navigating the Standard Manpages

In the Beginning (of Perl, that is, back in 1987), the perl manpage was a terse document, filling about 24 pages when typeset and printed. For example, its section on regular expressions was only two paragraphs long. (That was enough, if you knew egrep.) In some ways, nearly everything has changed since then. Counting the standard documentation, the various utilities, the per-platform porting information, and the scads of standard modules, we're now up over 1,500 typeset pages of documentation spread across many separate manpages. (And that's not even counting any CPAN modules you install, which is likely to be quite a few.)

But in other ways, nothing has changed: there's still a perl manpage kicking around. And it's still the right place to start when you don't know where to start. The difference is that once you arrive, you can't just stop there. Perl documentation is no longer a cottage industry; it's a supermall with hundreds of stores. When you walk in the door, you need to find the YOU ARE HERE to figure out which shop or department store sells what you're shopping for. Of course, once you get familiar with the mall, you'll usually know right where to go.

Here are a few of the store signs you'll see:

Manpage	Covers
perl	What Perl manpages are available
perldata	Data types
perlsyn	Syntax
perlop	Operators and precedence
perlre	Regular expressions
perlvar	Predefined variables
perlsub	Subroutines
perlfunc	Built-in functions
perlmod	How to make Perl modules work
perlref	References
perlobj	Objects
perlipc	Interprocess communication
perlrun	How to run Perl commands, plus switches
perldebug	Debugging
perldiag	Diagnostic messages

That's just a small excerpt, but it has the important parts. You can tell that if you want to learn about an operator, perlop is apt to have what you're looking for. And if you want to find something out about predefined variables, you'd check in perlvar. If you got a diagnostic message you didn't understand, you'd go to perldiag. And so on.

Part of the standard Perl manual is the frequently asked questions (FAQ) list. It's split up into these nine different pages:

Manpage	Covers
perlfaq1	General questions about Perl
perlfaq2	Obtaining and learning about Perl
perlfaq3	Programming tools
perlfaq4	Data manipulation
perlfaq5	Files and formats
perlfaq6	Regular expressions
perlfaq7	General Perl language issues
perlfaq8	System interaction
perlfaq9	Networking

Some manpages contain platform-specific notes:

Manpage	Covers
perlamiga	The Amiga port
perlcygwin	The Cygwin port
perldos	The MS-DOS port
perlhpux	The HP-UX port
perlmachten	The Power MachTen port
perlos2	The OS/2 port
perlos390	The OS/390 port
perlvms	The DEC VMS port
perlwin32	The MS-Windows port

(See also Chapter 25, and the CPAN ports directory described earlier for porting information.)

Searching the Manpages

Nobody expects you to read through all 1,500 typeset pages just to find a needle in a haystack. There's an old saying that you can't grep^[2] dead trees. Besides the customary search capabilities inherent in most document-viewing programs, as of the 5.6.1 release of Perl, each main Perl manpage has its own search and display capability. You can search individual pages by using the name of the manpage as the command and passing a Perl regular expression (see Chapter 5) as the search pattern:

% perlop comma

% perlfunc split

% perlvar ARGV

% perldiag 'assigned to typeglob'

When you don't quite know where something is in the documentation, you can expand your search. For example, to search all the FAQs, use the perlfaq command (which is also a manpage):

% perlfaq round

The perltoc command (which is also a manpage) searches all the manpages' collective tables of contents:

% perltoc typeglob
perl5005delta: Undefined value assigned to typeglob
perldata: Typeglobs and Filehandles
perldiag: Undefined value assigned to typeglob

Or to search the complete online Perl manual, including all headers, descriptions, and examples, for any instances of the string, use the perlhelp command:

% perlhelp CORE::GLOBAL

See the perldoc manpage for details.

Non-Perl Manpages

When we refer to non-Perl documentation, as in getitimer (2), this refers to the getitimer manpage from section 2 of the Unix Programmer's Manual.^[3] Manpages for syscalls such as getitimer may not be available on non-Unix systems, but that's probably okay, because you couldn't use the Unix syscall there anyway. If you really do need the documentation for a Unix command, syscall, or library function, many organizations have put their manpages on the web--a quick search of AltaVista for “+crypt(3) +manual” will find many copies.

Although the top-level Perl manpages are typically installed in section 1 of the standard man directories, we will omit appending a (1) to those manpage names in this book. You can recognize them anyway because they are all of the form "perlmumble".

---

^[1] If you still get a truly humongous page when you do that, you're probably picking up the ancient release 4 manpage. Check your MANPATH for archeological sites. (Say perldoc perl to find out how to configure your MANPATH based on the output of perl -V:man.dir.)

^[2] Don't forget there's a Glossary if you need it.

^[3] Section 2 is only supposed to contain direct calls into the operating system. (These are often called "system calls", but we'll consistently call them syscalls in this book to avoid confusion with the system function, which has nothing to do with syscalls). However, systems vary somewhat in which calls are implemented as syscalls and which are implemented as C library calls, so you could conceivably find getitimer (2) in section 3 instead.