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.
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
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:
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
perldoc -q regular-expression: search the questions in the various
perldoc -v variable-name: describe a specific predefined variable from
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.
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).
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.