Use perlboot to Find Perl's Current Object-Oriented Guides

You will finish with the right local command for opening Perl's object-oriented programming documentation, plus a way to confirm which installed files you are reading. The key result is simple: perlboot is a signpost, not the tutorial itself. On this machine it points to perlootut and perlobj, which replace the older tutorial that used to live in perlboot.

Allow about ten minutes. You need Perl and the perl-doc package installed. The checks below are read-only and do not need sudo. The examples were checked with Perl 5.38.2 and perl-doc package version 5.38.2-3.2ubuntu0.6; other Perl releases can ship different documentation wording or paths.

1. Confirm that perlboot is a documentation entry point

Ask the installed manual page what it covers:

$ man perlboot

The local page describes perlboot as links to information about object-oriented programming in Perl. Its description names two destinations, perlootut and perlobj, and says that they supersede the former tutorial. There is no Perl program called by this command and no project setting to enable.

Checkpoint: if your terminal opens a different page, or reports that the manual is missing, check the package and manual path before following advice copied from another system.

$ dpkg-query -W -f='${Package} ${Version}\n' perl-doc
perl-doc 5.38.2-3.2ubuntu0.6
$ man -w perlboot
/usr/share/man/man1/perlboot.1.gz

2. Open the practical tutorial

Use perldoc to read perlootut from the installed documentation:

$ perldoc perlootut

perldoc normally chooses a readable formatter and may start a pager. Press q to leave the pager. For a command that writes directly to standard output, use the documented -T option:

$ perldoc -T perlootut | sed -n '1,40p'

This is the useful starting point when you know Perl's basic syntax and want an introduction to classes, objects, methods and related terminology. Piping the output through sed only limits what is displayed; it does not alter the installed documentation.

3. Use perlobj for the detailed reference

Read perlobj when you need the language's object model and the details behind the tutorial:

$ perldoc perlobj

Keep the two documents separate in your notes. perlootut is the guided introduction named by perlboot; perlobj is the deeper reference. If you are debugging a real module, the module's own documentation and tests still take priority over a generic example.

Checkpoint: both names should resolve locally. A missing perlootut or perlobj usually means the documentation package is absent or your Perl installation is incomplete, not that an object-oriented feature needs to be enabled.

$ perldoc -l perlootut
/usr/share/perl/5.38/pod/perlootut.pod
$ perldoc -l perlobj
/usr/share/perl/5.38/pod/perlobj.pod

4. Check the exact documentation files

Use -l when you need to record which copy a script, bug report or review used:

$ perldoc -l perlboot
/usr/share/perl/5.38/pod/perlboot.pod
$ perldoc -V | sed -n '1,3p'
Perldoc v3.2801, under perl v5.038002 for linux

The displayed path is an implementation detail of this installation, not a path you should hard-code into a program. Package upgrades can move it. Prefer the document name, such as perlootut, when invoking perldoc.

You can also ask perldoc for its own option list:

$ perldoc -h | sed -n '1,18p'
perldoc [options] PageName|ModuleName|ProgramName|URL...

Do not confuse -l, which prints a file name, with -m, which displays a module file in its entirety. For normal reading, give the page name without either option. Do not add -U just to make a lookup work: that option changes how perldoc handles privilege dropping and is not needed for ordinary installed documentation.

5. Read an upstream copy only when you need it

The installed pages are the reproducible reference for this host. Perl also publishes the documentation at perldoc.perl.org/perlootut.html and perldoc.perl.org/perlobj.html. Use those pages when comparing releases or linking a review to a stable web reference, but check the Perl version before assuming that an example matches your interpreter.

If you need the version-specific answer, run perl -v and record it beside the documentation name. Avoid copying a newer language feature into an older deployment merely because the online page shows it. The local perlboot page is deliberately brief, so it cannot by itself establish that every feature described by the linked pages exists in your installed Perl.

6. Recover from the common wrong turn

If you type perlboot at a shell prompt, the shell will look for an executable with that name. That is not the workflow described by the manual page. Use man perlboot or perldoc perlboot instead:

$ perldoc -T perlboot | sed -n '1,24p'
NAME
    perlboot - Links to information on object-oriented programming in Perl

DESCRIPTION
    For information on OO programming with Perl, please see perlootut and
    perlobj.

If perldoc says it cannot find a page, inspect command -v perldoc and the perl-doc package. Do not repair a documentation lookup by changing PERL5LIB, installing files into system directories or running the reader as root. Those changes can hide a packaging problem and make later diagnostics harder.