Item 44: Use perldoc to extract documentation for installed modules.


Item 44: Use perldoc to extract documentation for installed modules.

Perl comes with a large quantity of documentationa very large quantity. The man pages included with early distributions of Perl 5 ran to over 500 pages. The page count for the newest versions is much higher. The standard distribution also includes many modules, each of them with its own man page. There is a huge amount of useful information in the man pages, so it pays to be able to read them. There are two simple ways to read on-line documentation for Perl: perldoc and man . Of these two ways, perldoc is generally the bestread on to find out why.

Your site may also have documentation in HTML form. Ask the person who installed Perl whether it is available, and if so, how to get to it.

Why man can't find man pages

For some operating systems, getting to the Perl man pages is not as simple as typing man perl . The problem is that the man command cannot always find the files containing the man pages.

Older versions of the Unix man command rely on explicit searches of the filesystem. There is a built-in "man path " that can be changed using the MANPATH environment variable. The man command searches through the directories and subdirectories that are accessible from the man path until it finds the right file.

This is a time-consuming and resource- intensive way to find a man page. As a result, most versions of Unix now ship with versions of man that do not perform exhaustive searches, at least not by default. Instead, they consult a " whatis" database to find out which man pages are installed and where they are located. The problem with the whatis database is that it must be kept up-to-date by a system administrator (usually with something like the catman command). If the database is not up-to-date, recently installed man pages will not be found by the man command. [4]

[4] If you are an administrator trying to get the Perl man pages working, bear in mind that the man pages for modules are installed beneath the private library directorysomething like /usr/local/lib/perl5/man rather than /usr/local/man . The man pages for locally-installed modules will be in a different site library directory.

There are various workarounds involving man . Most versions of the man command allow you to force an explicit search (ignoring any whatis database) and/or list directories that you want to search for man pages. This takes a lot of typing, though; furthermore, man is different from machine to machine.

Enter perldoc .

Why perldoc can find man pages

The perldoc command is a Perl script that is installed along with the Perl executable and other utilities like s2p and h2xs .

The perldoc command does not search for man pages. Instead, it searches the Perl tree for perl modules ( .pm ) with embedded documentation, as well as documentation-only .pod files (see Item 46). This means that perldoc will search places that man often doesn't. When a matching file is found, perldoc formats the contents into a man page and displays it. For example:

 %  perldoc perldoc  PERLDOC(1)  User Contributed Perl Documentation  PERLDOC(1)  NAME       perldoc - Look up Perl documentation in pod format.  SYNOPSIS       perldoc [-h] [-v] [-t] [-u] [-m] [-l] 

. . . etc.

To get documentation on a module, supply the module name as the argument to perldoc :

 %  perldoc File::Basename  

You can omit all but the last part of the module name. The perldoc command also will perform case-insensitive searches:

 %  perldoc basename  

Same as using File::Basename .

You can also get documentation on a single Perl function by using the -f option:

 %  perldoc -f length  

Document the length function .

Of course, in order for perldoc to work, it must be properly installed. The directory that perl is installed in should contain all the various Perl utilities perldoc , pod2man , h2xs , and so on. The Perl installer does this automatically, but if you are using a machine onto which an administrator "manually" installed Perl by copying or linking the Perl executable from another directory, you may have problems. If perldoc seems broken or is inaccessible, see your administrator.



Effective Perl Programming. Writing Better Programs with Perl
Effective Perl Programming: Writing Better Programs with Perl
ISBN: 0201419750
EAN: 2147483647
Year: 1996
Pages: 116

Similar book on Amazon

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net