Perldoc

[ Perl tips index ]
[ Subscribe to Perl tips ]

Perldoc

While opinions vary about the elegance and beauty of Perl, many people agree that Perl is one of the most well documented programming language in use today. Better still, much of that documentation is freely available and comes standard with Perl.

Most of Perl's documentation is accessible through the perldoc utility. Perldoc reads POD (plain old documentation) out of .pod files or from within the source of modules and programs themselves. This Perl tip is going to discuss some of the documents and perldoc switches that we find invaluable.

To learn more about how to write your own POD documentation read perldoc perlpod.

Module documentation

Individual module documentation

To read the documentation from any installed module we can write:

        perldoc <module_name>

for example:

        perldoc CGI

For multi-part module names, such as Scalar::Util, we can type either of the following:

        perldoc Scalar::Util;
        perldoc Scalar/Util;

although the first form is more regularly seen.

Module source

Sometimes we want to browse the source of a module without having to find out where the module is installed. To do this, we can use the -m switch to Perldoc:

        perldoc -m CGI

Be aware that under older versions of perldoc this will display the source of the file containing the POD. For modules that separate code and pod, perldoc -m may not do what you expect.

Standard installed modules

To find out which modules were installed with Perl by default read:

        perldoc perlmodlib
Non-standard installed modules

To see a list of the modules you've installed since Perl was installed read:

	perldoc perllocal

Note that this page may not always be accurate. Modules installed into user directories are not typically added to the perllocal list. Further, the perllocal list may not writable by the user at the time of module installation. Finally, modules installed using your operating system's packaging system (eg, RedHat RPM files, or Debian .deb files) rarely appear in perllocal.

Function documentation

Perhaps the most used switch to Perldoc is -f. This provides a full description of any Perl function. Thus, to find out all we could ever want to know about print, we'd type:

        perldoc -f print

These pages provide information about what arguments our functions take, what they return, example uses, caveats and more.

To find the documentation for the file test operations type:

 
        perldoc -f -x

The -f switch pulls its data from the perlfunc page. Thus if you wish to browse Perl's functions you may wish to start there.

Questions and answers

Perl has a number of FAQ files. These range from general questions through to quite specific topics.

Frequently asked questions
To find out all the topics covered in the FAQs you can read:
        perldoc perlfaq
Searching the FAQs

Perl has a great focus on laziness. As a result you can search the FAQs with a regular expression, from the command line. To do this, provide a regular expression (or a string of interest) to perldoc with the -q flag:

        perldoc -q 'CGI script'
        perldoc -q 'CGI script.*browser'

This then searches the headings (questions) of the entries in the FAQs for your matches. You can also pass in keywords which interest you:

        perldoc -q CGI script

which returns more results than the previous search.

General pages

Well beyond the few uses above, Perl has a great many more pages. To find a list of all of these read:

        perldoc perl

or (to find these broken into more meaningful sections):

        perldoc perltoc

Tutorials

In particular, the tutorials are well written and a great place to start to learn about new topics. Popular tutorials include:

        perldoc perlreftut          (References)
        perldoc perlopentut         (Open)
        perldoc perldebtut          (Debugging)
        perldoc perlretut           (Regular expressions)
        perldoc perlboot            (OO for beginners)
        perldoc perltoot            (OO part 1)
        perldoc perltootc           (OO part 2)
        perldoc perlthrtut          (Threads)
        perldoc perlxstut           (XS)

[ Perl tips index ]
[ Subscribe to Perl tips ]


This Perl tip and associated text is copyright Perl Training Australia. You may freely distribute this text so long as it is distributed in full with this Copyright noticed attached.

If you have any questions please don't hesitate to contact us:

Email: contact@perltraining.com.au
Phone: 03 9354 6001 (Australia)
International: +61 3 9354 6001

Valid XHTML 1.0 Valid CSS