Read The Fantastic Manual: How to get the most out of Perl documentation

Whether learning a programming language, working through a problem, or trying to understand a new library, it may be tempting to flail around crafting just the right search engine query or cry for help on a forum like Stack Overflow. But look at any guide to asking good questions and you’ll find this commandment at the top: do your research. And one of the primary sources of that research is the official documentation for the language or library in question.

The perldoc command

Fortunately, Perl and its modules come installed with extensive documentation, also available on the Web. Locally, you can use the perldoc command-line program, or if you have the documentation installed as Linux/Unix man pages (short for manual pages) you can use the standard man command. Because that isn’t always the case and because it has more Perl-specific options, I recommend perldoc.

Note that if you’re using the Perl provided by your operating system distribution you may not have any documentation installed at all without a separate package. For example, Ubuntu Linux calls this package perl-doc; you can install it with this command:

sudo apt-get install perl-doc

(Splitting Perl across several packages is a common operating system distribution tactic; it’s one of the reasons I recommend installing your own Perl.)

Once you’re sure you have the command available, run the following command to get an introduction to the Perl programming language:

perldoc perlintro

All of the built-in documentation begins with “perl” as above, so you can say perldoc perlrun to find out how to execute Perl, perldoc perlfaq to get a directory of frequently asked questions, or perldoc perltoc for a table of contents listing everything available.

As I mentioned above, the perldoc command has several useful options. You can run perldoc perldoc for a full description, but here are some highlights:

• perldoc -h: a brief help message
• perldoc -f function: describe a specific function from perlfunc
• perldoc -q regular-expression: search the questions in the various perlfaq documents
• perldoc -v variable-name: describe a specific predefined variable from perlvar

The last argument to perldoc can be a documentation page as described earlier, an installed module, a Perl program name in your path, or the URL to a Perl module or Plain Old Documentation (POD) file.

The Perldoc Browser website

You may have noticed a number of links above to the perldoc.perl.org website. This is a great friendly resource if you prefer reading in a web browser, and you can use features like bookmarks/favorites and sending hyperlinks to others. It has a search engine and you can even switch between different Perl versions (including development).

MetaCPAN

Perl is more than the language and its standard modules. The Comprehensive Perl Archive Network (CPAN) has over 200,000 open-source Perl modules contributed by authors all over the world, solving common and not-so-common software development problems from asynchronous programming to XML development.

In addition to using the perldoc command described earlier to understand locally-installed modules, you can use the MetaCPAN web site’s search engine (in both regular and regular expression flavors) to discover and learn how to save time piecing together programs instead of reinventing the wheel. I always check MetaCPAN first when I need to write some Perl.

Writing your own

Perl has its own markup language called Plain Old Documentation (POD), and you can either interleave it with your own program source code or save it in separate files. The perlpod documentation page has all the details and the perlpodstyle page will guide you in writing in a style consistent with other documentation. And if you need to publish elsewhere, there are translators for HTML, LaTeX, PDF, and other formats on CPAN. You can also provide your documentation to others via a dedicated web application; this is an excellent tool for teams with internal-only (“DarkPAN”) code.

Documentation is like a present you give to both your later self and anybody else that needs to use your work. I highly recommend you spend time writing it in addition to the usual developer-level source code comments. This is especially important if you plan to release open source on CPAN; otherwise, no one will understand what it does or why they should care. I’m incredibly grateful to every developer who has put in the effort.