Find the Right Perl Manual Page with perltoc

perltoc is the fix for typing man perlrun when you actually meant something else. It is a map of every Perl manual page installed on this machine, so a vague question such as "how does Perl read command-line options?" turns into a quick trip to the page that actually answers it, in this case perlrun(1).

Allow about ten minutes. You need a shell, the perl-doc package, and a terminal manual-page viewer. These examples were checked on Ubuntu's perl-doc 5.38.2-3.2ubuntu0.6, with Perl 5.38.2. Page names and contents can differ on another release, so treat your installed output as the authority.

1. Confirm the installed documentation

Start with ordinary, read-only checks. No elevated privileges needed:

$ dpkg-query -W -f='${Package} ${Version}\n' perl-doc
perl-doc 5.38.2-3.2ubuntu0.6
$ perldoc -V 2>&1 | head -1
Perldoc v3.2801, under perl v5.038002 for linux
$ man -f perltoc
perltoc (1)          - perl documentation table of contents

The package version identifies the local documentation set. The perldoc line is a second check on the Perl installation, and man -f confirms the page database can find the name.

2. Open perltoc without treating it as a command

perltoc is a manual page, not a normal executable with options to run. Open it through man:

$ man perltoc

Use the manual viewer's search key, usually /, followed by a word such as perlrun or regular expressions. Press n to move to the next match, q to leave the viewer. The page's job is to point you at another document, not to explain every topic itself.

It opens with broad groups: basic documentation, language-specific material, platform-specific material, modules and auxiliary tools. Under each group sits a list of document names and short descriptions. Read the name before reaching for a search engine: it is normally the argument you pass to man or perldoc.

3. Search the table of contents from the shell

For a quick search, send the page through a pager and use its search function:

$ man perltoc | less
/regular expressions
n

If you already know the likely document name, use the manual database instead:

$ man -k '^perl(run|intro)$'
perlintro (1)        - a brief introduction and overview of Perl
perlrun (1)          - how to execute the Perl interpreter

The pattern is a regular expression. The anchors, ^ and $, stop the search returning names that merely contain the same letters. Without them, a search for perlrun can match a longer name on systems with more pages.

4. Follow one entry to the detailed page

Say the question is how Perl starts and how its command-line switches work. The table of contents points to perlrun. Open that page directly:

$ man perlrun

Inside the page, search for Command Switches or a specific switch such as -I. This two-stage lookup beats guessing a page name: perltoc shows the documentation structure, and the detailed page supplies the actual syntax and behaviour.

You can also ask perldoc to display the same document in Pod form:

$ perldoc perlrun

Reach for perldoc when you want Perl's own documentation tool, or when a page is installed as Pod rather than a formatted man page. To see where the source file lives, use the location query:

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

The path is version-specific. Do not edit that file to customise your notes: package upgrades can replace it. Copy the relevant command or section into your own documentation instead.

5. Choose the right section when names collide

Manual pages use sections because one name can describe different kinds of documentation. perltoc(1), perlfunc(1) and module pages all sit under section 1 on this installation, but the section number still matters once a name exists more than once. Ask man what it found:

$ man -w perltoc
/usr/share/man/man1/perltoc.1.gz
$ man -w perlrun
/usr/share/man/man1/perlrun.1.gz

If a lookup gives an unexpected page, request the section explicitly, for example man 1 perltoc. Save man -a NAME for when you deliberately want every matching page: it can open several results and turn a short check into a much longer one.

6. Keep version differences visible

perltoc is generated from the documentation shipped with Perl, so its list is a snapshot, not a permanent catalogue. A newer release may add, rename or remove entries, and a distribution may package the pages differently. Compare the heading and version before copying a claim from an online page.

perldoc.perl.org publishes the current documentation and versioned pages, which is useful for checking newer releases. It is not a replacement for the local check when you need to know what a script can use on this host. For an operational answer, trust the local man page and confirm the command or module version that will actually run.

No command in this guide changes files, services, Perl configuration or system policy, so there is nothing to undo. Do not reach for sudo merely because a page is missing; elevated privileges do not make an uninstalled manual page appear in your search path.