Perl in a Nutshell

Perl in a NutshellSearch this book
Previous: 2.4 Getting and Installing ModulesChapter 2
Installing Perl
Next: II. Language Basics

2.5 Documentation

Perl documentation is written in a language known as pod (plain old documentation). Pod is a set of simple tags that can be processed to produce documentation in the style of Unix manpages. There are also several utility programs available that process pod text and generate output in different formats. Pod tags can be intermixed with Perl commands, or they can be saved in a separate file, which usually has a .pod extension. The pod tags and the utility programs that are included in the Perl distribution are described in Chapter 4, The Perl Language.

2.5.1 Installing the Documentation

On Unix, the standard Perl installation procedure generates manpages for the Perl documentation from their pod format, although your system administrator might also choose to install the documentation as HTML files. You can also use this procedure to generate manpages for CPAN modules when you install them. You might need to modify your MANPATH environment variable to include the path to the Perl manpages, but then you should be able to read the documentation with the man command. In addition, Perl comes with its own command, perldoc, which formats the pod documentation and displays it. perldoc is particularly useful for reading module documentation, which might not be installed as manpages; you can also use it for reading the core Perl documentation.

The ActiveState Win32 port comes with documentation in HTML format; you can find it in the /docs subdirectory of the distribution. Documentation specific to ActiveState's Perl for Win32 is installed in the /docs/Perl-Win32 subdirectory.

The native Win32 port installs the perldoc command for formatting and reading Perl documentation; it also provides an option during installation for the documentation to be formatted and saved as HTML files.

2.5.2 The Perl Manpages

Perl comes with lots of online documentation. To make life easier, the manpages have been divided into separate sections so you don't have to wade through hundreds of pages of text to find what you are looking for. You can read them with either the man command or with perldoc. Run man perl or perldoc perl to read the top-level page. That page in turn directs you to more specific pages. Or, if you know which page you want, you can go directly there by using:

% man perlvar


% perldoc perlvar

The following table lists the sections in a logical order for reading through them:

perlOverview (the top level)
perldeltaChanges since previous version
perlfaqFrequently asked questions
perltocTable of contents for Perl documentation
perldataData structures
perlopOperators and precedence
perlreRegular expressions
perlrunExecution and options
perlfuncBuiltin functions
perlvarPredefined variables
perlmodHow modules work
perlmodlibHow to write and use modules
perlmodinstallHow to install modules from CPAN
perllocaleLocale support
perldscData structures introduction
perllolData structures: lists of lists
perltootOO tutorial
perltieObjects hidden behind simple variables
perlbotOO tricks and examples
perlipcInterprocess communication
perldiagDiagnostic messages
perltrapTraps for the unwary
perlportPortability guide
perlstyleStyle guide
perlpodPlain old documentation
perlbookBook information
perlembedEmbedding Perl in your C or C++ application
perlapioInternal IO abstraction interface
perlxsXS application programming interface
perlxstutXS tutorial
perlgutsInternal functions for those doing extensions
perlcallCalling conventions from C
perlhistHistory records

Previous: 2.4 Getting and Installing ModulesPerl in a NutshellNext: II. Language Basics
2.4 Getting and Installing ModulesBook IndexII. Language Basics