From Novice to Adept: Embrace the Copious Documentation

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.

I tend to use the -f and -q switches when I know I need something in the Perl 5 documentation but I can't remember its details.