Read The Fantastic Manual: How to get the most out of Perl documentation
Tags: perl, cpan, documentation, pod
Published: 2021-10-12 15:20:49

---
title: Read The Fantastic Manual: How to get the most out of Perl documentation
published: true
date: 2021-10-12 14:00:00 UTC
tags: Perl,CPAN,documentation,POD
canonical_url: https://phoenixtrap.com/2021/10/12/read-the-fantastic-manual-how-to-get-the-most-out-of-perl-documentation/
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qh1sxv94epqte2jobimd.jpg
---

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](https://help.duckduckgo.com/duckduckgo-help-pages/results/syntax/) or cry for help on a forum like [Stack Overflow](https://stackoverflow.com/questions/tagged/perl). But look at any [guide to asking good questions](https://stackoverflow.com/help/how-to-ask) and you’ll find this commandment at the top: **do your research.** And one of the [primary sources](https://en.wikipedia.org/wiki/Primary_source) of that research is the official documentation for the language or library in question.

## The [`perldoc` command](https://perldoc.perl.org/perldoc)

Fortunately, Perl and its modules come installed with extensive documentation, also [available on the Web](https://perldoc.perl.org/). Locally, you can use the [`perldoc`](https://perldoc.perl.org/perldoc) command-line program, or if you have the documentation installed as Linux/Unix [man pages](https://en.wikipedia.org/wiki/Man_page) (short for manual pages) you can use the standard [`man`](https://man7.org/linux/man-pages/man1/man.1.html) command. Because that isn’t always the case and because it has more Perl-specific [options](https://perldoc.perl.org/perldoc#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](https://ubuntu.com/) calls this package `perl-doc`; you can install it with this command:

```shell
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](https://www.perl.com/article/downloading-and-installing-perl-in-2021/).)

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

```shell
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](https://perldoc.perl.org/perlpod)) file.

## The [Perldoc Browser website](https://perldoc.perl.org/)

You may have noticed a number of links above to the [perldoc.perl.org website](https://perldoc.perl.org/). 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](https://metacpan.org/)

Perl is more than the language and its [standard modules](https://perldoc.perl.org/modules). The [Comprehensive Perl Archive Network](https://www.cpan.org/) (CPAN) has over 200,000 open-source Perl modules [contributed](https://www.cpan.org/modules/04pause.html) by authors all over the world, solving common and not-so-common software development problems from [asynchronous programming](https://metacpan.org/pod/Task::Kensho::Async) to [XML development](https://metacpan.org/pod/Task::Kensho::XML).

In addition to using the `perldoc` command described earlier to understand locally-installed modules, you can use the [MetaCPAN web site](https://metacpan.org/)’s search engine (in both regular and [regular expression](https://grep.metacpan.org/) 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](https://perldoc.perl.org/perlsyn#PODs%3A-Embedded-Documentation) or save it in separate files. The [`perlpod`](https://perldoc.perl.org/perlpod) documentation page has all the details and the [`perlpodstyle`](https://perldoc.perl.org/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](https://perldoc.perl.org/pod2html), [LaTeX](https://metacpan.org/dist/Pod-LaTeX/view/pod2latex.PL), [PDF](https://metacpan.org/dist/Pod-Pdf/view/scripts/pod2pdf), and other formats on CPAN. You can also provide your documentation to others via a [dedicated web application](https://metacpan.org/pod/Pod::POM::Web); this is an excellent tool for teams with internal-only (“[DarkPAN](http://www.modernperlbooks.com/mt/2009/02/the-darkpan-dependency-management-and-support-problem.html)”) 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](https://perldoc.perl.org/perlsyn#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.