Find Perl Answers Quickly with perldoc and perlfaq

You will finish with a repeatable way to read the Perl FAQ installed on a Linux machine and jump to questions by their headings. The examples use Perl 5.38.2, package perl-doc 5.38.2-3.2ubuntu0.6, and the locally installed FAQ version 5.20210520. Allow about ten minutes. You need a shell and the perl-doc package; no elevated privileges are needed.

1. Confirm that the documentation is installed

Start by checking which perldoc will run and which Perl release it belongs to:

$ command -v perldoc
/usr/bin/perldoc
$ perl -v | sed -n '2,3p'
This is perl 5, version 38, subversion 2 (v5.38.2)
$ dpkg-query -W -f='${Package} ${Version}\n' perl-doc
perl-doc 5.38.2-3.2ubuntu0.6

Package versions vary by distribution. The version line in the FAQ itself is separate from the interpreter version, so record both when you need to reproduce an answer later.

2. Read the FAQ as one document

The short form opens the FAQ in the program selected by perldoc for paging:

$ perldoc perlfaq

The document is divided into nine topic sections, from general Perl questions through files, regular expressions, system interaction, and web or networking topics. Press the pager's quit key when you have found the relevant section.

For a command that can be piped into another tool, use -T. It sends formatted text to standard output rather than relying on an interactive pager:

$ perldoc -T perlfaq | sed -n '1,14p'
NAME
    perlfaq - Frequently asked questions about Perl

VERSION
    version 5.20210520

Use -u when you specifically need the unformatted POD source. That is useful for examining markup, but it is usually harder to scan than the normal text output.

3. Search question headings before searching the answers

Use -q followed by a regular expression. The search is across the questions in perlfaq1 through perlfaq9, not just the top-level perlfaq index:

$ perldoc -T -q open | sed -n '1,16p'
Found in /usr/share/perl/5.38/pod/perlfaq5.pod
  How can I open a filehandle to a string?
    (contributed by Peter J. Holzer, [email protected])

The pattern is case-sensitive unless you add -i. For example, this finds questions mentioning either form of the word:

$ perldoc -T -i -q 'module|cpan' | sed -n '1,24p'

A search may return several questions and then print each answer. Keep the first Found in path: it tells you which topic file contains the result. A broad pattern can produce a lot of output, so pipe it to less, sed, or a file in a temporary working directory.

4. Open the section that matched

Once the result identifies a section, read that section directly. For the filehandle example above, use:

$ perldoc perlfaq5

You can also send it through a non-interactive pipeline:

$ perldoc -T perlfaq5 | sed -n '1,36p'

Use perldoc -l perlfaq if you need the installed source path rather than its rendered text:

$ perldoc -l perlfaq
/usr/share/perl/5.38/pod/perlfaq.pod

Do not edit files under /usr/share/perl. They belong to the package manager and an upgrade can replace them. If you need a local note, copy only the small excerpt you need into your own documentation.

5. Avoid the common interpretation traps

• perlfaq is an index and guide to the FAQ collection. It is not a complete reference for every Perl builtin or module.
• -q searches question headings. Use a direct page such as perlfaq5 after it identifies the likely topic.
• perldoc uses a pager in an interactive terminal. Add -T in scripts and verification commands so output does not wait for a pager.
• The local FAQ version and Perl interpreter version are different values. Include both in bug reports or operational notes.
• Documentation examples describe Perl behaviour, but they do not validate the assumptions of your own script. Test a copied example in a temporary directory before changing a real file or service.

Most reads are ordinary user commands. Only package installation or access to a protected working directory may require elevated privileges, and neither is required by perldoc itself.