core-perl-documentation-cpan-module-documentation.tt

=title Core Perl documentation and CPAN module documentation
=timestamp 2013-01-27T10:45:56
=indexes perldoc, documentation, POD, CPAN
=status show
=books beginner_book
=author szabgab
=index 1
=archive 1
=feed 1
=comments 1
=social 1

=abstract start

Perl comes with a lot of documentation, but
it takes some time till you get used to using it. In this part of the
<a href="/perl-tutorial">Perl tutorial</a> I'll explain how
to find your way around the documentaton.

=abstract end

<h2>perldoc on the web</h2>

The most convenient way to access the documentation of core perl
is to visit the <a href="http://perldoc.perl.org/">perldoc</a> website.

It contains an HTML version of the documentation for Perl, the language,
and for the modules that come with core Perl as released by the Perl 5 Porters.

It does not contain documentation for CPAN modules.
There is an overlap though, as there are some modules that are available
from CPAN but that are also included in the standard Perl distribution.
(These are often referred to as <b>dual-lifed</b>.)

You can use the search box at the top right corner. For example you can
type in <hl>split</hl> and you'll get the documentation of <hl>split</hl>.

Unfortunately it does not know what to do with <hl>while</hl>, nor with
<hl>$_</hl> or <hl>@_</hl>. In order to get explanation of those
you'll have to flip through the documentation.

The most important page might be <a href="http://perldoc.perl.org/perlvar.html">perlvar</a>,
where you can find information about variables such as <hl>$_</hl> and <hl>@_</hl>.

<a href="http://perldoc.perl.org/perlsyn.html">perlsyn</a> explains the syntax of Perl
including that of the <a href="/while-loop">while loop</a>.

<h2>perldoc on the command line</h2>

The same documentation comes with the source code of Perl, but not
every Linux distribution installs it by default. In some cases there
is a separate package. For example in Debian and Ubuntu it is the <b>perl-doc</b>
package. You need to installed it using <hl>sudo aptitude install perl-doc</hl>
before you can use <hl>perldoc</hl>.

Once you have it installed, you can type <hl>perldoc perl</hl> on the command line
and you will get some explanation and a list of the chapters in the Perl documentation.
You can quit this using the <hl>q</hl> key, and then type the name of one of the chapters.
For example: <hl>perldoc perlsyn</hl>.

This works both on Linux and on Windows though the pager on Windows is really weak,
so I cannot recommend it. On Linux it is the regular man reader so you should be familiar
with it already.

<h2>Documentation of CPAN modules</h2>

Every module on CPAN comes with documentation and examples.
The amount and quality of this documentation varies greatly
among the authors, and even a single author can have very
well documented and very under-documented modules.

After you installed a module called Module::Name,
you can access its documentation by typing <hl>perldoc Module::Name</hl>.

There is a more convenient way though, that does not even
require the module to be installed. There are several
web interfaces to CPAN. The main ones are <a href="http://metacpan.org/">Meta CPAN</a>
and <a href="http://search.cpan.org/">search CPAN</a>.

They both are based on the same documentation, but they
provide a slightly different experience.


<h2>Keyword search on Perl 5 Maven</h2>

A recent addition to this site is the keyword search on the top menu bar.
Slowly you will find explanation for more and more parts of perl.
At one point part of the core perl documentation and the documentation of the
most important CPAN modules will be also included.

If you are missing something from there, just make a comment below,
with the keywords you will looking for and you have a good chance to
get your request fulfilled.