Documentation

 <  Day Day Up  >  

This point is important, so please pay close attention: With every Perl installation, you receive a full copy of the current documentation for the Perl language and the interpreter.

That's right. The entire set of documentation available for Perl comes with the installation bundle. You get it for free. The 5.8 distribution includes more than 1,700 pages of documentation. This documentation includes reference material, tutorials, FAQs, history, and even notes on Perl's internals.

You can access this documentation using a variety of methods . On Windows and Unix, a utility called perldoc is installed with Perl. You can use the perldoc program to search the documentation and provide formatted output for the manuals. To run perldoc , you need to be at a command prompt. The following example uses a Unix prompt, but a DOS command prompt is fine:

 $  perldoc perl  PERL(1)        User Contributed Perl Documentation        PERL(1)      NAME           perl - Practical Extraction and Report Language      SYNOPSIS           perl [ -sTuU ]      [ -hv ] [ -V[:configvar] ]                [ -cw ] [ -d[:debugger] ] [ -D[number/list] ]                [ -pna ] [ -Fpattern ] [ -l[octal] ] [ -0[octal] ]                [ -Idir ] [ -m[-]module ] [ -M[-]'module...' ]                [ -P ]      [ -S ]      [ -x[dir] ]                [ -i[extension] ]      [ -e 'command' ] [ ?                ] [ programfile ] [ argument ]...           For ease of access, the Perl manual has been split up into a           number of sections:    : 

The manual sections are divided into pieces with names like perlfunc (Perl Functions), perlop (Perl Operators), and perlfaq (Perl FAQ). To access the perlfunc manual page, you enter the command perldoc perlfunc . The names of all the manual sections are listed in the perldoc perl manual page.

To search the manual for a function name, you can run the perldoc utility with a -tf switch. The following example finds the manual page for Perl's print function:

 $  perldoc -tf print  

The FAQs are Frequently Asked Questions about Perl. They are questions that people learning Perl ask over and over again. To save people time and trouble, the questions have been collected into files called FAQs. To search an FAQ for a keyword, you should use the -q switch along with a word that might appear in the FAQ's title. For example, if you want to know about Perl support, you could use the following query:

 $  perldoc -q support  

In this case, the entry for the FAQ questions "Who supports Perl? Who develops it? Why is it free?" is displayed.

Some Special Documentation Cases

When Perl is installed on a Unix system, the installer is given the option to install manual pages in traditional "man" format. If the installer chooses yes, the standard Perl documentation is converted into man format and stored in an appropriate place. To access the Perl documentation, you can use either the perldoc program or the man program as you normally would with Unix:

 $  man perl  

When ActiveState's Perl distribution is installed on a Microsoft Windows system, the manual pages are converted to HTML format and can be accessed with a Web browser. If you want to read the manuals, point your frame-capable Web browser to the local directory C:\Perl\html if you used the standard installation directory; if you didn't, use your selected directory instead.

For the Macintosh (not Mac OS X), MacPerl comes with a utility called Shuck that is located in the MacPerl folder. You can use it to read and search the Perl documentation as shown in Figure 1.5.

Figure 1.5. The MacPerl Shuck documentation reader.


What If You Can't Find the Documentation?

If you can't find the documentation, only two things can be wrong. The first is you're not looking in the right places. Perhaps the perldoc utility is installed in a directory that's not in your shell's search path. Or perhaps your search path is overly restrictive . Hunt around for the perldoc utility, and add that directory to your shell's PATH environment variable.

The second reason is the documentation was removed, either by accident or malice . Perl's installation includes documentation. You can't install Perl without it. If the documentation isn't there, a good argument can be made that Perl wasn't properly installed or that it has since been corrupted. Perhaps you ”or the system administrator ”should consider reinstalling Perl. The documentation is an integral part of the Perl development environment, and without it some pieces of Perl will not function.

If all else fails, and you can't get a local copy of the documentation, you can fall back to the Web. On Perl's primary distribution site (http://www.perl.com), you can access the standard set of documentation. Having the actual documentation that came with your version of Perl would be better ”it's tailor-made to your particular version and installation ”but this online documentation will do in a pinch .

 <  Day Day Up  >  


SAMS Teach Yourself Perl in 24 Hours
Sams Teach Yourself Perl in 24 Hours (3rd Edition)
ISBN: 0672327937
EAN: 2147483647
Year: 2005
Pages: 241

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net