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:

ManpageCovers
perlWhat Perl manpages are available
perldataData types
perlsynSyntax
perlopOperators and precedence
perlreRegular expressions
perlvarPredefined variables
perlsubSubroutines
perlfuncBuilt-in functions
perlmodHow to make Perl modules work
perlrefReferences
perlobjObjects
perlipcInterprocess communication
perlrunHow to run Perl commands, plus switches
perldebugDebugging
perldiagDiagnostic 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:

ManpageCovers
perlfaq1General questions about Perl
perlfaq2Obtaining and learning about Perl
perlfaq3Programming tools
perlfaq4Data manipulation
perlfaq5Files and formats
perlfaq6Regular expressions
perlfaq7General Perl language issues
perlfaq8System interaction
perlfaq9Networking

Some manpages contain platform-specific notes:

ManpageCovers
perlamigaThe Amiga port
perlcygwinThe Cygwin port
perldosThe MS-DOS port
perlhpuxThe HP-UX port
perlmachtenThe Power MachTen port
perlos2The OS/2 port
perlos390The OS/390 port
perlvmsThe DEC VMS port
perlwin32The 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.

Get Programming Perl, 3rd Edition now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.