Find the Right Perl Manual Page with perltoc

You will use perltoc as a map of the Perl documentation installed on your Linux machine, search it for a topic, and then open the detailed manual page that contains the answer. The useful result is a repeatable path from a vague question such as "how does Perl read command-line options?" to a focused page such as perlrun(1).

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

1. Confirm the installed documentation

Start with ordinary, read-only checks. No elevated privileges are 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, while man -f confirms that 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. Press q to leave the viewer. The page's purpose is to point you at another document, not to explain every topic itself.

The page starts with broad groups such as basic documentation, language-specific material, platform-specific material, modules and auxiliary tools. Under those groups it lists document names and short descriptions. Read the name before reaching for a search engine: the name 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 $, keep the search from returning names that merely contain the same letters. Without them, a search for perlrun can match a longer name on systems with more pages.

Distraction trap: man -k perl can return a long list of unrelated module and library pages. Narrow the search with a distinctive word or an anchored expression, then inspect the one-line descriptions before opening anything.

4. Follow one entry to the detailed page

Suppose the question is how Perl is started 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 is safer than 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

Use 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 is installed, 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 a 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 are all commonly shown through section 1 on this installation, but the section number still matters when 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. Use man -a NAME only when you deliberately want every matching page. It can open several results and make a short investigation feel much larger than it is.

6. Keep version differences visible

perltoc is generated from the documentation shipped with Perl. Its list is therefore a snapshot, not a permanent catalogue. A newer Perl 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.

The official Perl documentation is useful for checking newer releases: perldoc.perl.org publishes the current documentation and versioned pages. 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, prefer 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 add sudo merely because a page is missing; elevated privileges do not make an uninstalled manual page appear in your user's search path.