The second hack in the book Perl Hacks (no link; if you download it and send me $2 and Ovid $0.50 via PayPal or wherever, we get a lot more money than we would if you bought a printed copy from the publisher, grumble grumble) talks about perldoc for a good reason. If you don't take advantage of Perl 5's copious documentation, you'll struggle learning Perl 5, far more than necessary.

(The first hack in the book is to look up distributions and documentation on the CPAN. As mst says, CPAN is my language.) Note that well-behaved CPAN distributions also include copious documentation which integrates with perldoc . I miss this in other languages.

The examples here assume you use perldoc from the command line. If that's not the case -- if you have them installed on your system in HTML form or if you prefer to browse them on perldoc.perl.org, the suggestions will still work with modifications.

Start by running perldoc perltoc . You don't have to know or understand all of this, but it gives you an overview of all of the documentation included as part of a complete Perl 5 installation. If you've never read any of the documentation before -- if you're a novice to Perl 5 in general, perhaps -- then perldoc perlintro is a quick survey of what you can do with Perl. It does presume some familiarity with programming, but if you're reading this I presume the same.

Other documentation worth skimming includes perldoc perlstyle and perldoc perlglossary . The former will help you as a neophyte understand what makes decent Perl and the latter explains several of the terms of art in the Perl community. You should also read perldoc perldoc , as it includes gems many Perl gurus don't know.

Operator and Builtin Documentation

The most useful perldoc flag is -f . After eleven years with the language, syntax rarely fools me, but I still can't remember all of the return values of caller or localtime in the right order, and I can't always remember all of the arguments to splice and substr .

perldoc -f name looks through perldoc perlfunc and displays the documentation of the builtin named name. I use this regularly:

$ perldoc -f splice splice ARRAY,OFFSET,LENGTH,LIST splice ARRAY,OFFSET,LENGTH splice ARRAY,OFFSET splice ARRAY Removes the elements designated by OFFSET and LENGTH from an array, and replaces them with the elements of LIST, if any. In list context, returns the elements removed from the array. In scalar context, returns the last element removed, or "undef" if no elements are removed. The array grows or shrinks as necessary. If OFFSET is negative then it starts that far from the end of the array. If LENGTH is omitted, removes everything from OFFSET onward. If LENGTH is negative, removes the elements from OFFSET onward except for -LENGTH elements at the end of the array. If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is past the end of the array, perl issues a warning, and splices at the end of the array.

This is handy if you remember the name of the builtin, but not its exact syntax or semantics. When I can't remember what I want, I read a couple of pages into perldoc perlfunc , which categorizes builtins by their uses.

Occasionally the difference between a Perl 5 operator and builtin is significant, so you have to trawl through perldoc perlop for more details. That's rarely an issue for me, but that may be how I program. Be aware of the distinction and be willing to check the other document, if necessary.

Perl FAQs

Perl 5 also includes a copious FAQ which contains a wealth of information for novices. perldoc perlfaq is a great place to start, but when I need to look something up in the FAQ, I use the -q option to perldoc :

$ perldoc -q number Found in /usr/share/perl/5.10/pod/perlfaq4.pod Why am I getting long decimals (eg, 19.9499999999999) instead of the numbers I should be getting (eg, 19.95)? Internally, your computer represents floating-point numbers in binary. Digital (as in powers of two) computers cannot store all numbers exactly. Some real numbers lose precision in the process. This is a problem with how computers store numbers and affects all computer languages, not just Perl. perlnumber shows the gory details of number representations and conversions. To limit the number of decimal places in your numbers, you can use the printf or sprintf function. See the "Floating Point Arithmetic" for more details. printf "%.2f", 10/3; my $number = sprintf "%.2f", 10/3;

This relies on a keyword search, so you have to get a keyword in the title of a question right, but if you browse the titles of the FAQ, you'll get some idea of the questions in the FAQ and the answers you can expect.