metadoc

   1
   2 Perl is blessed with an extensive set of accurate and informative
   3 documentation. As there are so many resources it is useful to have
   4 an overview of what is available, where it is and how best to read it.
   5 This document is called perlmetadoc reflecting that it is about the
   6 other documents.
   7
   8 <these topics aren't in any particular order yet>
   9
  10 Installing Perl Documentation
  11
  12 The core Perl documentation is usually installed along with Perl, but
  13 some OS's may have it as a separate package (usually called perl-doc).
  14 To see if you have the documentation installed or not type 'perldoc
  15 perldoc' on the command line, otherwise use your OS's package manager to
  16 install the documentation.
  17
  18 When you install a module from CPAN (see below), its documentation
  19 will also be installed. You can then use the 'perldoc' command (see below)
  20 to read the module's documentation.
  21
  22
  23
  24
  25 How do you find the Perl Documentation?
  26
  27 When you have a properly installed Perl, you can find documents by
  28 running the 'perldoc' command (see below). This command knows where the
  29 documents are installed on your system and will print them out. It is
  30 smart enough to search for the Perl core documents including those of
  31 core modules as well as the documents for modules you install. Another
  32 method of printing the documents is the 'man' command (if you have a
  33 UNIX/Linux flavor OS). Perl documents are also installed where man can
  34 find and print them.
  35
  36 What are the kinds of Documents?
  37
  38 Perl comes with a large number of documents but they are generally
  39 grouped into several categories. You can see the categories and which
  40 documents are in them by running the command 'perldoc perl'. Overview
  41 documents have indexes of the documents and an introduction to
  42 Perl. Tutorials are meant to to teach and explain a particular topic
  43 such as regular expressions or Perl objects. The FAQ documents are also
  44 considered tutorials. The reference documents are the description of the
  45 Perl language and are packed full of information. The next category
  46 covers the internals of the perl program and how to embed C code. These
  47 are generally for those who need special knowledge and are rarely read
  48 by beginners. The miscellaneous category has various documents that
  49 don't fit other categories and include the delta documents which cover
  50 the changes made to Perl from version to version. Then there are human
  51 language specific documents and platform specific documents.
  52
  53 How best to read Perl Documentation
  54
  55 Reading language documentation can be difficult, especially when you are
  56 first learning a language and when there is a large amount of
  57 documentation. But there are ways to make it easier and more
  58 effective. First off you can use the site http://perldoc.perl.org (see
  59 below) to read the Perl documents if that make it easier for you. Then
  60 you can do what is called skim reading to start. When you read one of
  61 the documents, try to read the entire text of it. If you don't
  62 understand some section or it isn't important to you, it is ok to skip
  63 or skim it. The goal is to let you see the scope of that document and
  64 for you to discover new things each time you read it all. As you get
  65 more proficient you can fully read sections you skimmed earlier and
  66 learn them. And later on you can just go to the part you want to read
  67 and find out what you need to know. Even experts will skim read some
  68 documents as new features are added to Perl and they can discover them
  69 when reading the whole document. Skim reading is especially helpful when
  70 reading the FAQ (see below), perlop (about the Perl operators) and
  71 perlfunc (all about Perl's functions) as they are divided up into many
  72 sections. Another tip is a classic when reading documentation - follow
  73 the see also references and links to other documents. Some documents are
  74 closely related to others and will have information which will help you
  75 even though they weren't the initial document you read.
  76
  77 Searching the Perl documents
  78
  79 Knowing where something is covered in a document can be tricky when
  80 there is so much documentation. The overview documents can help (see
  81 below) but there are several other ways to improve your searching. The
  82 perldoc command (see below) can search the FAQ for you. It can also
  83 print out the documentation for any Perl builtin function. The
  84 perldoc.perl.org site has a very good search engine which can help you
  85 find the document and section you are seeking. On platforms which have
  86 the grep command, you can search the document text directly by going to
  87 the directory where it is installed.
  88
  89 The perldoc command
  90
  91 The primary way to read Perl documents is with the perldoc command. You
  92 just need to run the command 'perldoc <docname>' and it will be
  93 displayed for you. In most systems it will send the document through a
  94 paging program so you can read it page by page, search for strings and
  95 even go backwards as desired. This command has several useful options
  96 among which the most commonly used are -q which does a keyword query
  97 against the Perl FAQ documents and -f which prints out a single function
  98 from the perlfunc document. Of course, you can read more about this
  99 command by running 'perldoc perldoc'!
 100
 101 Overview Perl Documents
 102
 103 There are several Perl documents that are useful for navigating around
 104 the rest of the documents. They are perl, perltoc and perlblurb (to be
 105 written). The perl document (yes, its name is just 'perl') is a listing
 106 of all the Perl documents with a one line description of each one. The
 107 documents are grouped by their type such as tutorial, reference, etc. It
 108 is useful to get a quick look at all the document titles and their short
 109 descriptions.  The perltoc (Table of Contents) document is automatically
 110 generated and contains all the section headings found in all the
 111 documents. This is very long and it is bested used for searching for
 112 topics of interest. You can do that on http://perldoc.perl.org (see
 113 below), or with the grep command, or when you display it with perldoc
 114 (see how to use perldoc). The perlblurb document (new, to be written) is
 115 an expanded version of the 'perl' document but instead of a short
 116 description for each document, it has a short paragraph describing
 117 it. It is good for browsing for topics of interest and seeing which
 118 documents are related to others.
 119
 120 The perldoc.perl.org site
 121
 122 Another popular way to read and search the Perl documents is
 123 http://perldoc.perl.org. This web site has HTML versions of all the Perl
 124 documents in a framed design with the types and document names along
 125 side the document you selected. It has many advantages over the local
 126 version of the documentation including full searching, recently viewed
 127 pages, syntax highlighting of code examples and more. One very useful
 128 feature is that you can select which version of Perl's documents you see
 129 (going back to 5.8.8). The perldoc.perl.org site has only a couple of
 130 downsides. One is that you need web access and a browser to get to this
 131 site and if you are off the net, you always have the local
 132 documentation. The other is that it doesn't cover the modules you
 133 installed from CPAN (see below). This means you have to use the locally
 134 installed documentation for those modules or read the documentation from
 135 CPAN (http://search.cpan.org).
 136
 137 The Perl FAQ
 138
 139 Perl being as popular as it is and with so many developers learning and
 140 using it, you would expect many questions will be asked. So, of course
 141 Perl has an extensive set of Frequently Asked Questions (FAQ) with
 142 answers and code examples. The FAQ is divided up into 9 chapters (and
 143 one on Unicode). You can see the topics covered in each chapter in the
 144 'perl' document or at http://perldoc.perl.org/index-faq.html. We
 145 recommend that if you are learning Perl that you skim read the entire
 146 FAQ (as mentioned above). The first two chapters are general questions
 147 about Perl and installing it. The rest cover various technical areas. It
 148 is important to skim read it all so you know the scope and type of
 149 questions and answers in the FAQ. Later on you can reread chapters and
 150 more of it will be of use to you. At some point you can just query the
 151 FAQ and find out answers to specific questions you have. You can search
 152 the FAQ with the perldoc -q <keys> command or on http://perldoc.perl.org.
 153
 154 Module documentation
 155
 156 Perl has two collections of modules, those that come with Perl when you
 157 install it and those on the CPAN (a large public archive of Perl
 158 modules). When a module is installed on your system, its documentation
 159 (also written in POD as are the documents) will be installed too. The
 160 perldoc command can find and print out module documents as it does the
 161 main Perl documents - just type perldoc <Module::Name>. Also on systems
 162 that support it, man style versions of the documents will be installed
 163 and you can get the documents by running the man command with the module
 164 name.