Book Home Programming PerlSearch this book

0.4. 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.

[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.)

0.4.1. 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, "Portable Perl", and the CPAN ports directory described earlier for porting information.)

0.4.2. 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, "Pattern Matching") 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.

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

0.4.3. 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.

[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.

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".



Library Navigation Links

Copyright © 2001 O'Reilly & Associates. All rights reserved.