update

[urisagit/Perl-Docs.git] / metadoc

Perl is blessed with an extensive set of accurate and informative
documentation. As there are so many resources it is useful to have
an overview of what is available, where it is and how best to read it.
This document is called perlmetadoc reflecting that it is about the
other documents.

<these topics aren't in any particular order yet>

Installing Perl Documentation

The core Perl documentation is usually installed along with Perl, but
some OS's may have it as a separate package (usually called perl-doc).
To see if you have the documentation installed or not type 'perldoc
perldoc' on the command line, otherwise use your OS's package manager to
install the documentation.

When you install a module from CPAN (see below), its documentation
will also be installed. You can then use the 'perldoc' command (see below)
to read the module's documentation.




How do you find the Perl Documentation?

When you have a properly installed Perl, you can find documents by
running the 'perldoc' command (see below). This command knows where the
documents are installed on your system and will print them out. It is
smart enough to search for the Perl core documents including those of
core modules as well as the documents for modules you install. Another
method of printing the documents is the 'man' command (if you have a
UNIX/Linux flavor OS). Perl documents are also installed where man can
find and print them.

What are the kinds of Documents?

Perl comes with a large number of documents but they are generally
grouped into several categories. You can see the categories and which
documents are in them by running the command 'perldoc perl'. Overview
documents have indexes of the documents and an introduction to
Perl. Tutorials are meant to to teach and explain a particular topic
such as regular expressions or Perl objects. The FAQ documents are also
considered tutorials. The reference documents are the description of the
Perl language and are packed full of information. The next category
covers the internals of the perl program and how to embed C code. These
are generally for those who need special knowledge and are rarely read
by beginners. The miscellaneous category has various documents that
don't fit other categories and include the delta documents which cover
the changes made to Perl from version to version. Then there are human
language specific documents and platform specific documents.

How best to read Perl Documentation

Reading language documentation can be difficult, especially when you are
first learning a language and when there is a large amount of
documentation. But there are ways to make it easier and more
effective. First off you can use the site http://perldoc.perl.org (see
below) to read the Perl documents if that make it easier for you. Then
you can do what is called skim reading to start. When you read one of
the documents, try to read the entire text of it. If you don't
understand some section or it isn't important to you, it is ok to skip
or skim it. The goal is to let you see the scope of that document and
for you to discover new things each time you read it all. As you get
more proficient you can fully read sections you skimmed earlier and
learn them. And later on you can just go to the part you want to read
and find out what you need to know. Even experts will skim read some
documents as new features are added to Perl and they can discover them
when reading the whole document. Skim reading is especially helpful when
reading the FAQ (see below), perlop (about the Perl operators) and
perlfunc (all about Perl's functions) as they are divided up into many
sections. Another tip is a classic when reading documentation - follow
the see also references and links to other documents. Some documents are
closely related to others and will have information which will help you
even though they weren't the initial document you read.

Searching the Perl documents

Knowing where something is covered in a document can be tricky when
there is so much documentation. The overview documents can help (see
below) but there are several other ways to improve your searching. The
perldoc command (see below) can search the FAQ for you. It can also
print out the documentation for any Perl builtin function. The
perldoc.perl.org site has a very good search engine which can help you
find the document and section you are seeking. On platforms which have
the grep command, you can search the document text directly by going to
the directory where it is installed. 

The perldoc command

The primary way to read Perl documents is with the perldoc command. You
just need to run the command 'perldoc <docname>' and it will be
displayed for you. In most systems it will send the document through a
paging program so you can read it page by page, search for strings and
even go backwards as desired. This command has several useful options
among which the most commonly used are -q which does a keyword query
against the Perl FAQ documents and -f which prints out a single function
from the perlfunc document. Of course, you can read more about this
command by running 'perldoc perldoc'!

Overview Perl Documents

There are several Perl documents that are useful for navigating around
the rest of the documents. They are perl, perltoc and perlblurb (to be
written). The perl document (yes, its name is just 'perl') is a listing
of all the Perl documents with a one line description of each one. The
documents are grouped by their type such as tutorial, reference, etc. It
is useful to get a quick look at all the document titles and their short
descriptions.  The perltoc (Table of Contents) document is automatically
generated and contains all the section headings found in all the
documents. This is very long and it is bested used for searching for
topics of interest. You can do that on http://perldoc.perl.org (see
below), or with the grep command, or when you display it with perldoc
(see how to use perldoc). The perlblurb document (new, to be written) is
an expanded version of the 'perl' document but instead of a short
description for each document, it has a short paragraph describing
it. It is good for browsing for topics of interest and seeing which
documents are related to others.

The perldoc.perl.org site

Another popular way to read and search the Perl documents is
http://perldoc.perl.org. This web site has HTML versions of all the Perl
documents in a framed design with the types and document names along
side the document you selected. It has many advantages over the local
version of the documentation including full searching, recently viewed
pages, syntax highlighting of code examples and more. One very useful
feature is that you can select which version of Perl's documents you see
(going back to 5.8.8). The perldoc.perl.org site has only a couple of
downsides. One is that you need web access and a browser to get to this
site and if you are off the net, you always have the local
documentation. The other is that it doesn't cover the modules you
installed from CPAN (see below). This means you have to use the locally
installed documentation for those modules or read the documentation from
CPAN (http://search.cpan.org).

The Perl FAQ

Perl being as popular as it is and with so many developers learning and
using it, you would expect many questions will be asked. So, of course
Perl has an extensive set of Frequently Asked Questions (FAQ) with
answers and code examples. The FAQ is divided up into 9 chapters (and
one on Unicode). You can see the topics covered in each chapter in the
'perl' document or at http://perldoc.perl.org/index-faq.html. We
recommend that if you are learning Perl that you skim read the entire
FAQ (as mentioned above). The first two chapters are general questions
about Perl and installing it. The rest cover various technical areas. It
is important to skim read it all so you know the scope and type of
questions and answers in the FAQ. Later on you can reread chapters and
more of it will be of use to you. At some point you can just query the
FAQ and find out answers to specific questions you have. You can search
the FAQ with the perldoc -q <keys> command or on http://perldoc.perl.org.

Module documentation

Perl has two collections of modules, those that come with Perl when you
install it and those on the CPAN (a large public archive of Perl
modules). When a module is installed on your system, its documentation
(also written in POD as are the documents) will be installed too. The
perldoc command can find and print out module documents as it does the
main Perl documents - just type perldoc <Module::Name>. Also on systems
that support it, man style versions of the documents will be installed
and you can get the documents by running the man command with the module
name.