Find Perl Documentation and Choose a Learning Path with perlfaq2

You will finish with a local, repeatable way to find Perl's built-in documentation, inspect the interpreter and its library search path, locate modules, and choose a sensible place to ask for help. The examples use Perl v5.38.2 and the perl-doc package version 5.38.2-3.2ubuntu0.6 installed on this machine. The FAQ itself reports version 5.20210520, so treat it as a useful map of the documentation ecosystem rather than a complete description of every current service.

Allow about fifteen minutes. You need a shell and a working Perl installation. The checks below are read-only and do not need sudo. Do not install a module or rebuild Perl just because a lookup fails; first establish which part of the documentation or installation is missing.

1. Check the installed Perl and FAQ package

Start by recording the interpreter and documentation package versions. This makes later advice reproducible and exposes a common trap: Perl can be installed while its separate documentation package is absent.

$ perl -v
This is perl 5, version 38, subversion 2 (v5.38.2) built for x86_64-linux-gnu-thread-multi

$ dpkg-query -W -f='${Package} ${Version}\n' perl-doc perl-base
perl-doc 5.38.2-3.2ubuntu0.6
perl-base 5.38.2-3.2ubuntu0.6

Your architecture and package revision may differ. If dpkg-query reports that perl-doc is not installed, use your normal distribution package workflow to add it. That is an administrative change, so review the package transaction before accepting it. On Debian and Ubuntu, the FAQ specifically identifies perl-doc as the package that supplies documentation.

2. Open the FAQ locally

Use perldoc when you want the installed documentation, not a search result that may describe another Perl release. The name perlfaq2 selects the FAQ section about obtaining and learning Perl.

$ perldoc perlfaq2
NAME
    perlfaq2 - Obtaining and Learning about Perl

VERSION
    version 5.20210520

For a script, note the file that was selected instead of opening it in a pager:

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

Checkpoint: if perldoc perlfaq2 cannot find the page, check command -v perldoc, confirm that perl-doc is installed, and retry. Do not copy a POD file from another host as a quick fix; its version and search paths may not match your interpreter.

3. Find the right kind of Perl page

perldoc accepts different names for different kinds of help. Use a page name for general documentation, -f for a built-in function, -v for a predefined variable, and -q to search the FAQ questions.

$ perldoc -f open
open FILEHANDLE,MODE,EXPR
open FILEHANDLE,MODE,EXPR,LIST
open FILEHANDLE,MODE,REFERENCE

$ perldoc -q "library directory"
How do I keep my own module/library directory?

The exact answer text can change with the installed documentation. The useful distinction is stable in this interface: -f searches Perl's function documentation, while -q searches FAQ questions. If you only know a module name, try its documentation directly:

$ perldoc File::Basename

Keep the first lookup narrow. A broad search produces a lot of reading and makes it easy to follow an answer for a different Perl feature or release.

4. Inspect where this Perl looks for libraries

When a script says that a module cannot be found, inspect @INC before changing environment variables or copying files. This is a read-only check of the directories Perl searches.

$ perl -le 'print for @INC'
/etc/perl
/usr/local/lib/x86_64-linux-gnu/perl/5.38.2
/usr/local/share/perl/5.38.2
/usr/lib/x86_64-linux-gnu/perl5/5.38

$ perl -V | sed -n '1,14p'
Summary of my perl5 (revision 5 version 38 subversion 2)
Platform:
  osname=linux
  archname=x86_64-linux-gnu-thread-multi

Compare the failing module's expected location with the actual list. A directory that is present in @INC but does not exist is a useful clue, not a reason to create it blindly. If you maintain a private module directory, read the perlfaq8 entry named by perlfaq2 and choose one deliberate installation method. Avoid mixing root-owned vendor files with ad hoc files in a user's home directory.

5. Use CPAN and official references deliberately

The FAQ points to CPAN as the archive for Perl modules and extensions, and to MetaCPAN as a search interface. Start with the module's documentation and release information before installing anything. A module name in a blog post is not proof that it is present on your host, compatible with your Perl, or still maintained.

• The online perlfaq2 page mirrors the topic of the local FAQ.
• MetaCPAN is useful for locating module documentation and distributions.
• CPAN provides the archive and release infrastructure described by the FAQ.
• Perl.org collects language, learning and community resources.

These are reference and discovery steps. Installing a distribution changes the machine and may run build or test code. Read its metadata, check its dependencies, and use the package or deployment process appropriate for the host. Do not run an unfamiliar installer as root simply to make a documentation example work.

6. Choose a support route and report the right thing

For a normal usage question, read the relevant perldoc page first, then use a Perl community resource such as the beginners mailing list, PerlMonks or a Perl-tagged question site. For an interpreter or core-module bug, reproduce it on the installed version and use the Perl issue tracker named by the FAQ. A CPAN module may have its own tracker, so read that module's documentation instead of assuming the core tracker is correct.

Before asking, collect the command, the smallest input that reproduces the problem, the complete error, and the output of perl -V. Remove passwords, tokens, private paths and customer data. Never paste a whole production configuration when a short isolated example will do.

Checkpoint: you should now know whether your problem is missing documentation, a missing module, an installation path issue, a usage question or a suspected bug. That classification usually determines the next useful page or support channel.