hi all, i said i was working on a perl metadoc and here is the first draft. it is aimed at perl newbies who need to learn how to use the extensive perl documentation. i think this is a very much needed document as newbies get lost in the doc forest all too easily. we can discuss this at this meeting if we have time after steve's talk. it needs plenty of editing and improvements so read and rip it apart. edits welcome!
thanx, uri Perl is blessed with an extensive set of accurate and informative documentation. But that means it is harder for newcomers to Perl to navigate through the forest of pages. This document aims to be a guide to the Perl documentation. Its goals are to cover where to find the documents, what are the kinds of documents, how to best read them, what tools are available, what other resources there are and more. That is why this document is called perlmetadoc as it is about the other documents. <these topics aren't in any particular order yet> Installing Perl Documentation When you install Perl or it is already installed with your OS, the documentation is almost always installed with Perl. In some OS distribution systems, the Perl executable and libraries are in a different package than the documentation so be sure to also install the documents for that version of Perl. This is usually very easily done with the package manager for your OS. When you install a module from CPAN (see below), its documentation will be installed. Then you can 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. -- Uri Guttman ------ [email protected] -------- http://www.sysarch.com -- ----- Perl Code Review , Architecture, Development, Training, Support ------ --------- Gourmet Hot Cocoa Mix ---- http://bestfriendscocoa.com --------- _______________________________________________ Boston-pm mailing list [email protected] http://mail.pm.org/mailman/listinfo/boston-pm
