Commit | Line | Data |
cf83821d |
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. |