home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


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

or:

% perldoc perlvar

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

Section Description
perl Overview (the top level)
perldelta Changes since previous version
perlfaq Frequently asked questions
perltoc Table of contents for Perl documentation
perldata Data structures
perlsyn Syntax
perlop Operators and precedence
perlre Regular expressions
perlrun Execution and options
perlfunc Builtin functions
perlvar Predefined variables
perlsub Subroutines
perlmod How modules work
perlmodlib How to write and use modules
perlmodinstall How to install modules from CPAN
perlform Formats
perllocale Locale support
perlref References
perldsc Data structures introduction
perllol Data structures: lists of lists
perltoot OO tutorial
perlobj Objects
perltie Objects hidden behind simple variables
perlbot OO tricks and examples
perlipc Interprocess communication
perldebug Debugging
perldiag Diagnostic messages
perlsec Security
perltrap Traps for the unwary
perlport Portability guide
perlstyle Style guide
perlpod Plain old documentation
perlbook Book information
perlembed Embedding Perl in your C or C++ application
perlapio Internal IO abstraction interface
perlxs XS application programming interface
perlxstut XS tutorial
perlguts Internal functions for those doing extensions
perlcall Calling conventions from C
perlhist History records