Perl has copious documentation in Plain Old Documentation (POD) format. Knowing where to look for this documentation will benefit anyone doing Perl programming. Try perlmeme.org or PerlMonks for Perl code examples.
Note that online versions of the documentation may not match the version of Perl or the module installed locally. This could cause bugs due to the wrong documentation being read. I strongly recommend that local documentation be used in preference to online resources.
Perldoc Overview
Use the perldoc command to access the Perl documentation. For instance, for general information about perl and an index of other documentation, run:
$ perldoc perl
If perldoc(1) is not available, access the Perl documentation on the web (with the usual caveat that this documentation may not match the version installed locally). Some Unix vendors do not install the documentation with perl. On Debian, install the perl-doc package:
# apt-get install perl-doc
On Mac OS X, install Xcode (formerly known as Developer’s Tools). Recent Mac OS X (10.6) ship with multiple versions of perl. This may require appending a version number to find the appropriate documentation:
$ perldoc perl
…
$ perldoc perl5.8.9
…
$ perldoc perl5.10.0
…
Functions & Frequently Asked Question (FAQ)s
Until all the functions, their arguments, and return values are memorized (that is, never), either peruse the perlfunc page, or use the -f argument to perldoc:
$ perldoc perlfunc
…
$ perldoc -f abs
abs VALUE
abs Returns the absolute value of its argument. If
VALUE is omitted, uses $_.
Lookup questions in the perlfaq documents with the -q option to perldoc:
$ perldoc -q lock
…
However, the FAQ Keyword lookup often requires one to know what the title of the FAQ entry is before being able to craft an appropriate keyword lookup. podgrep from the pmtools suite may offer better search results, or consider the Perl Cookbook.
Modules
To read the documentation for a specific perl module (e.g. Digest::SHA1), run:
$ perldoc Digest::SHA1
If the module is not installed on the system, the following URL can be used to search for module documentation on the Comprehensive Perl Archive Network (CPAN):
http://search.cpan.org/perldoc/Digest::MD5
Use the ow script to expand URL on the command line, or create a “Quick Search” location bar expansion http://search.cpan.org/perldoc/%s, as supported by many web browsers. ow will pass the URL to a browser by default, or display the URL for manual copying:
$ ow -l perldoc SOAP::Lite
http://search.cpan.org/perldoc/SOAP::Lite
However, note that online versions of the documentation may not match the version of the module installed on the system. This could lead to errors or bugs. I strongly recommend that the local documentation be used.
Converting POD
To render POD into other formats, consider the Pod::Simple perl module.
