--- /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.
--- /dev/null
+You have a lot of popular dynamic languages to choose from including
+Ruby, Python, Java and Perl. Each one has its own style, advantages and
+quirks. This document is meant for newcomers to Perl to see why it is a
+language worth knowing by all modern programmers.
+
+CPAN
+
+The CPAN (Comprehensive Perl Archive Network) has been the crown jewel
+of Perl for decades. It is a public repository of over 10,000 modules of
+Perl that are free and easy to download and use. If there is a protocol,
+file format, algorithm, library or almost anything else, there will
+likely be a CPAN module that handles it for you. Modules range from very
+popular ones like LWP (for fetching web pages), to File::Slurp (which
+reads/writes/modifies whole files) to obscure modules that are used by a
+few developers in a niche field. CPAN isn't a dusty mausoleum
+either. Over 2/3 of the modules have been uploaded or updated in the
+past year. There are also several supporting services for automatic
+testing of modules against a matrix of Perl versions and platforms and
+for reporting bugs and making feature requests.
+
+Community
+
+One of the joys of programming in Perl is becoming a member of the
+worldwide Perl community. There are over 1 million Perl developers on
+planet earth and they work together in many ways to help each other. The
+Perl community hosts conferences (YAPC and workshops), develop and
+maintain Perl (p5P), write modules for CPAN, support developers with
+websites and mailing lists, run local user groups and much more. You can
+find someone in the Perl community in your town, country or on the net
+who can help you figure out which module to use, how to use a feature
+that is new to you, and how to contribute backto the community. To read
+much more about this and find the community area of interest to you, see
+the document perlcommunity
+
+Regular Expression Engine
+
+Regular expressions, commonly called regexes, are a very powerful and
+common way to match and extract strings from larger pieces of text. They
+used in many areas including parsing, validation and transformation. The
+ironic thing is that many other languages claim to have 'Perl compatible
+regular expressions' (PCRE). Many do use a PCRE library for that. But
+none are really compatible with Perl's as it keeps getting improvements
+and new features that keep it the king of the hill. Perl also integrates
+regexes into the language in a more concise way which reduces the amount
+of code you need to get a job done.
+
+Documentation
+
+Perl has some of the best and most useful documentation around. There
+are tutorials on many topics, solid reference manuals, documents on
+special topics for experts and more. You can read these documents on
+your system or at http://perldoc.perl.org which also has a smart search
+engine. There are also navigation documents such as 'perl', perlblurb
+and perltoc that help you quickly find the topics that interest you.
--- /dev/null
+This document gives a short blurb about each of the Perl documents and
+document groups. It is meant to make it easier to locate which document
+cover areas of interest to you. You can print any of these documents by
+running the command 'perldoc <docname> on a terminal or console
+window. <docname> is the name before each blurb. You can also read and
+search then at http://perldoc.perl.org.
+
+
+Overview
+
+These documents provide an overview of all the Perl documents and an
+introduction to Perl.
+
+perl
+
+This document has a brief description of the Perl language and has a
+list of all the Perl documents with a one line description of each
+one. perlblurb has the same list with longer descriptions.
+
+perlmetadoc
+
+This document shows how to find and use the set of Perl documents. It
+covers the installing and finding the Perl documentation, the various
+types of documents, and tips and tools on how to best read the documents.
+
+perlblurb
+
+This document is based on the 'perl' document but has longer
+descriptions for each document. You are reading it now.
+
+perltoc
+
+This is an automatically generated document and it contains all the
+document section headers. It is in outline form and it is best searched
+as it is very long. It is useful to find which features are covered in a
+Perl document.
+
+perlintro
+
+This is a introduction to the Perl language for newcomers. It covers the
+basics of syntax, variables, scoping, flow control, operators, I/O,
+regular expressions and objects. It is a very good first read for anyone
+who is learning Perl.
+
+Tutorials
+
+The documentation for Perl has a set of tutorials on a wide range of
+topics. Pretty much any topic where you would want more explanation then
+the reference documents will be covered in one of these.
+
+perlreftut
+
+Perl references are the way you build up data structures and manage
+dynamic information. This tutorial shows you how to create references
+and to access the data to which they refer. After reading this you
+should be able to do basic coding with references and build up your own
+data structures.
+
+perllol
+
+This tutorial focuses on how to build and use an array of array data
+structure. It shows several ways to build them and also how to access
+their elements and print them out. It is a companion to perlreftut and
+perldsc.
+
+perldsc
+
+This tutorial covers how to create and access Perl data structures. It
+is more in depth that perlreftut and perllol and has many code examples
+which cover all the two level structures of hashes and arrays. Examples
+show both the declaration and initialization of data structures and also
+how to build them up with code.
+
+perlrequick
+
+This is a quick start guide to Perl's regular expressions. It covers the
+basics of matching strings, regex metacharacters, character class, and
+more. It also covers the Perl operators and functions which use
+regexes. It is a very good read when you are first learning regular
+expressions.
+
+perlretut
+
+This tutorial covers how to use Perl's regular expressions. It is more
+in depth than perlrequick and covers more topics. When you are ready,
+you can then read perlre which is the full regular expression manual.
+
+
+Object Oriented Perl Tutorials
+
+These next documents are all tutorials on how to do object oriented
+programmin in Perl. They cover all the needed topics so you can create
+you own classes, methods and objects. Read the full reference manuals perlobj
+and perlmod next to get all the details. Note that there are many
+modules on CPAN that help with OO coding. Ask someone in the Perl
+community for more about that.
+
+perlboot
+
+This tutorial shows step by step how to create a class, methods in a
+class and how to call those methods. It also covers basic ways to code
+up constructors which create objects. Before reading this you should
+know how to write and call Perl subroutines, use references and know
+your basic Perl syntax and data types.
+
+perltoot
+
+This is another tutorial which covers how to code up classes and make
+object oriented code. It take a different approach than perlboot and
+makes a good companion read to that tutorial.
+
+perltooc
+
+This tutorial covers how to make class level data when coding object
+oriented Perl. This is data that is private and static to the class but
+can be accesses by all the methods of the class.
+
+perlbot
+
+This is a 'bag of tricks' to help you when coding up object oriented
+Perl. It augments what is already covered in perlboot, perltoot and
+perltooc.
+
+ perlstyle Perl style guide
+
+ perlcheat Perl cheat sheet
+ perltrap Perl traps for the unwary
+ perldebtut Perl debugging tutorial
+
+perlfaq
+
+This is an overview of the full Perl FAQ (Frequently Asked
+Questions). It covers where to find it, how to contribute to it and its
+authors. The main section is a complete list of all the questions of the
+9 sections of the FAQ. Reading and searching this will help you find
+questions related to your needs and which FAQ section has the answers.
+
+perlfaq1
+
+The first FAQ section covers general information about Perl. It covers
+how Perl came to be, who supports it now, some comparisons to other
+languages, when and when not to use Perl and other related
+topics. Newcomers to Perl should read this entire section as it will
+help them out with understanding of where Perl fits in the programming
+world.
+
+perlfaq2
+
+The second FAQ section covers how to get Perl installed on your system
+and locations where you can learn more about programming in Perl. These
+include usenet, mailing lists, periodicals, books, web sites and
+more. If you are looking to learn Perl, this is a good document to read.
+
+perlfaq3 Programming Tools
+
+
+perlfaq4 Data Manipulation
+perlfaq5 Files and Formats
+perlfaq6 Regexes
+perlfaq7 Perl Language Issues
+perlfaq8 System Interaction
+perlfaq9 Networking
+
+Reference Manuals
+
+These documents are the full reference manuals for the Perl
+language. They are divided up into topics and each one covers that topic
+completely. They are dense and full of information so if you have
+trouble with something, see if there is a related tutorial on it. Each
+blurb will link to those tutorials.
+
+ perlsyn Perl syntax
+ perldata Perl data structures
+ perlop Perl operators and precedence
+ perlsub Perl subroutines
+ perlfunc Perl built-in functions
+ perlopentut Perl open() tutorial
+ perlpacktut Perl pack() and unpack() tutorial
+ perlpod Perl plain old documentation
+ perlpodspec Perl plain old documentation format specification
+ perlrun Perl execution and options
+ perldiag Perl diagnostic messages
+ perllexwarn Perl warnings and their control
+ perldebug Perl debugging
+ perlvar Perl predefined variables
+ perlre Perl regular expressions, the rest of the story
+ perlrebackslash Perl regular expression backslash sequences
+ perlrecharclass Perl regular expression character classes
+ perlreref Perl regular expressions quick reference
+ perlref Perl references, the rest of the story
+ perlform Perl formats
+ perlobj Perl objects
+
+perltie
+
+Tying is a way to replace all or part of the behavior of a basic Perl
+variable with your own code. You can write a class that can be a scalar,
+array or hash variable and the user will just see a normal variable with
+your new logic behind it. This document covers all you need to know on
+how to tie a variable to a class.
+
+ perldbmfilter Perl DBM filters
+
+ perlipc Perl interprocess communication
+ perlfork Perl fork() information
+ perlnumber Perl number semantics
+
+ perlthrtut Perl threads tutorial
+ perlothrtut Old Perl threads tutorial
+
+ perlport Perl portability guide
+ perllocale Perl locale support
+ perluniintro Perl Unicode introduction
+ perlunicode Perl Unicode support
+ perlunifaq Perl Unicode FAQ
+ perlunitut Perl Unicode tutorial
+ perlebcdic Considerations for running Perl on EBCDIC platforms
+
+ perlsec Perl security
+
+ perlmod Perl modules: how they work
+ perlmodlib Perl modules: how to write and use
+ perlmodstyle Perl modules: how to write modules with style
+ perlmodinstall Perl modules: how to install from CPAN
+ perlnewmod Perl modules: preparing a new module for distribution
+ perlpragma Perl modules: writing a user pragma
+
+ perlutil utilities packaged with the Perl distribution
+
+ perlcompile Perl compiler suite intro
+
+ perlfilter Perl source filters
+
+ perlglossary Perl Glossary
+
+ Internals and C Language Interface
+ perlembed Perl ways to embed perl in your C or C++ application
+ perldebguts Perl debugging guts and tips
+ perlxstut Perl XS tutorial
+ perlxs Perl XS application programming interface
+ perlclib Internal replacements for standard C library functions
+ perlguts Perl internal functions for those doing extensions
+ perlcall Perl calling conventions from C
+ perlreapi Perl regular expression plugin interface
+ perlreguts Perl regular expression engine internals
+
+ perlapi Perl API listing (autogenerated)
+ perlintern Perl internal functions (autogenerated)
+ perliol C API for Perl's implementation of IO in Layers
+ perlapio Perl internal IO abstraction interface
+
+ perlhack Perl hackers guide
+
+ Miscellaneous
+ perlbook Perl book information
+ perlcommunity Perl community information
+ perltodo Perl things to do
+
+ perldoc Look up Perl documentation in Pod format
+
+
+perlhist
+
+This has listings of all the released versions of Perl with information
+on who was the 'pumpking' (the source control manager), dates, etc. It
+is of interest to those who want to see how Perl has been managed over
+its history.
+
+These 'delta' documents cover all the changes in Perl between each
+released version. It is very useful to find out in which version a new
+feature first appeared and also when some have been deprecated and/or
+removed.
+
+ perldelta Perl changes since previous version
+ perl595delta Perl changes in version 5.9.5
+ perl594delta Perl changes in version 5.9.4
+ perl593delta Perl changes in version 5.9.3
+ perl592delta Perl changes in version 5.9.2
+ perl591delta Perl changes in version 5.9.1
+ perl590delta Perl changes in version 5.9.0
+ perl588delta Perl changes in version 5.8.8
+ perl587delta Perl changes in version 5.8.7
+ perl586delta Perl changes in version 5.8.6
+ perl585delta Perl changes in version 5.8.5
+ perl584delta Perl changes in version 5.8.4
+ perl583delta Perl changes in version 5.8.3
+ perl582delta Perl changes in version 5.8.2
+ perl581delta Perl changes in version 5.8.1
+ perl58delta Perl changes in version 5.8.0
+ perl573delta Perl changes in version 5.7.3
+ perl572delta Perl changes in version 5.7.2
+ perl571delta Perl changes in version 5.7.1
+ perl570delta Perl changes in version 5.7.0
+ perl561delta Perl changes in version 5.6.1
+ perl56delta Perl changes in version 5.6
+ perl5005delta Perl changes in version 5.005
+ perl5004delta Perl changes in version 5.004
+
+ perlartistic Perl Artistic License
+ perlgpl GNU General Public License
+
+Language-Specific
+
+These documents cover the issues when coding Perl with asian character
+sets.
+
+ perlcn Perl for Simplified Chinese (in EUC-CN)
+ perljp Perl for Japanese (in EUC-JP)
+ perlko Perl for Korean (in EUC-KR)
+ perltw Perl for Traditional Chinese (in Big5)
+
+Platform-Specific
+
+These documents contain notes pertaining to specific platforms where
+Perl is supported. Each document may cover issues such as building Perl
+on that platform, file name differences, forking issues, and more. Read
+the document for your platform to find out if you need to be aware of
+special issues.
+
+ perlaix Perl notes for AIX
+ perlamiga Perl notes for AmigaOS
+ perlapollo Perl notes for Apollo DomainOS
+ perlbeos Perl notes for BeOS
+ perlbs2000 Perl notes for POSIX-BC BS2000
+ perlce Perl notes for WinCE
+ perlcygwin Perl notes for Cygwin
+ perldgux Perl notes for DG/UX
+ perldos Perl notes for DOS
+ perlepoc Perl notes for EPOC
+ perlfreebsd Perl notes for FreeBSD
+ perlhpux Perl notes for HP-UX
+ perlhurd Perl notes for Hurd
+ perlirix Perl notes for Irix
+ perllinux Perl notes for Linux
+ perlmachten Perl notes for Power MachTen
+ perlmacos Perl notes for Mac OS (Classic)
+ perlmacosx Perl notes for Mac OS X
+ perlmint Perl notes for MiNT
+ perlmpeix Perl notes for MPE/iX
+ perlnetware Perl notes for NetWare
+ perlopenbsd Perl notes for OpenBSD
+ perlos2 Perl notes for OS/2
+ perlos390 Perl notes for OS/390
+ perlos400 Perl notes for OS/400
+ perlplan9 Perl notes for Plan 9
+ perlqnx Perl notes for QNX
+ perlriscos Perl notes for RISC OS
+ perlsolaris Perl notes for Solaris
+ perlsymbian Perl notes for Symbian
+ perltru64 Perl notes for Tru64
+ perluts Perl notes for UTS
+ perlvmesa Perl notes for VM/ESA
+ perlvms Perl notes for VMS
+ perlvos Perl notes for Stratus VOS
+ perlwin32 Perl notes for Windows
projects / urisagit/Perl-Docs.git / commitdiff