From: Uri Guttman Date: Tue, 8 May 2012 05:18:08 +0000 (-0400) Subject: cleanup X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=cf83821d2b095a464d353ea98e41bfa8b262caef;p=urisagit%2FPerl-Docs.git cleanup --- diff --git a/metadoc b/metadoc new file mode 100644 index 0000000..0a0eb87 --- /dev/null +++ b/metadoc @@ -0,0 +1,164 @@ + +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. + + + +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 ' 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 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 . 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. diff --git a/perladvantages b/perladvantages new file mode 100644 index 0000000..e9841ba --- /dev/null +++ b/perladvantages @@ -0,0 +1,54 @@ +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. diff --git a/perlblurb b/perlblurb new file mode 100644 index 0000000..76880da --- /dev/null +++ b/perlblurb @@ -0,0 +1,355 @@ +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 on a terminal or console +window. 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 diff --git a/perlresources b/perlresources new file mode 100644 index 0000000..e8d19b3 --- /dev/null +++ b/perlresources @@ -0,0 +1,20 @@ + +CPAN + +mailing lists + +web sites (perlmonks, learn.perl.org,) + +low cost conferences + +perl mongers + +documentation + +perl foundation + +irc + +books + +perl community