--- /dev/null
+
+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.
projects / urisagit/Perl-Docs.git / blobdiff