La Documentación en Perl

Para obtener información sobre un tópico o un módulo Perl utilize perldoc . Si tiene instalado el módulo Tk::Pod entonces puede utilizar el visualizador gráfico tkpod . Otra posibilidad es arrancar el programa podwebserver disponible en la distribución del módulo Pod::Webserver. Este programa arranca un servidor HTTP que sirve la documentación de los módulos instalados en la máquina:

$ podwebserver &
[2] 4069
$ I am process 4069 = perl Pod::Webserver v3.05
 Indexing all of @INC -- this might take a minute.
@INC = [ /soft/perl5lib/share/perl/5.8.8/ /soft/perl5lib/lib/perl/5.8.8 /soft/perl5lib/lib/perl/5.8 /soft/perl5lib/share/perl/5.8/ /etc/perl /usr/local/lib/perl/5.8.8 /usr/local/share/perl/5.8.8 /usr/lib/perl5 /usr/share/perl5 /usr/lib/perl/5.8 /usr/share/perl/5.8 /usr/local/lib/site_perl . ]
 Done scanning @INC
You can now open your browser to http://localhost:8020/

La documentación puede ahora ser accedida usando nuestro navegador favorito:

$ firefox  http://localhost:8020/ &

La fuente de información sobre el lenguaje Perl mas fiable es la que se encuentra en la documentación .pod adjunta con su distribución. Veamos algunos de los parámetros que admite perldoc:

lhp@nereida:~$ perldoc -h
perldoc [options] PageName|ModuleName|ProgramName...
perldoc [options] -f BuiltinFunction
perldoc [options] -q FAQRegex

Options:
    -h   Display this help message
    -V   report version
    -r   Recursive search (slow)
    -i   Ignore case
    -t   Display pod using pod2text instead of pod2man and nroff
             (-t is the default on win32 unless -n is specified)
    -u   Display unformatted pod text
    -m   Display module's file in its entirety
    -n   Specify replacement for nroff
    -l   Display the module's file name
    -F   Arguments are file names, not modules
    -v   Verbosely describe what's going on
    -T   Send output to STDOUT without any pager
    -d output_filename_to_send_to
    -o output_format_name
    -M FormatterModuleNameToUse
    -w formatter_option:option_value
    -X   use index if present (looks for pod.idx at /usr/lib/perl/5.8)
    -q   Search the text of questions (not answers) in perlfaq[1-9]

PageName|ModuleName...
         is the name of a piece of documentation that you want to look at. You
         may either give a descriptive name of the page (as in the case of
         `perlfunc') the name of a module, either like `Term::Info' or like
         `Term/Info', or the name of a program, like `perldoc'.

BuiltinFunction
         is the name of a perl function.  Will extract documentation from
         `perlfunc'.

FAQRegex
         is a regex. Will search perlfaq[1-9] for and extract any
         questions that match.

Any switches in the PERLDOC environment variable will be used before the
command line arguments.  The optional pod index file contains a list of
filenames, one per line.
                                                       [Perldoc v3.14]

Hay una serie de documentos que pueden consultarse con perldoc o tkpod. Los mas básicos son:

• perlintro Perl introduction for beginners
• perltoc Perl documentation table of contents

Hay un conjunto extenso de tutoriales:

• Tutorials
  • perlreftut Perl references short introduction
  • perldsc Perl data structures intro
  • perllol Perl data structures: arrays of arrays

  • perlrequick Perl regular expressions quick start
  • perlretut Perl regular expressions tutorial

  • perlboot Perl OO tutorial for beginners
  • perltoot Perl OO tutorial, part 1
  • perltooc Perl OO tutorial, part 2
  • perlbot Perl OO tricks and examples

  • perlstyle Perl style guide

  • perlcheat Perl cheat sheet
  • perltrap Perl traps for the unwary
  • perldebtut Perl debugging tutorial

• perlfaq
  • perlfaq Perl frequently asked questions
  • perlfaq1 General Questions About Perl
  • perlfaq2 Obtaining and Learning about Perl
  • perlfaq3 Programming Tools
  • perlfaq4 Data Manipulation
  • perlfaq5 Files and Formats
  • perlfaq6 Regexes
  • perlfaq7 Perl Language Issues
  • perlfaq8 System Interaction
  • perlfaq9 Networking

Los manuales de referencia se dividen por tópicos:

• 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
• perlreref Perl regular expressions quick reference
• perlref Perl references, the rest of the story
• perlform Perl formats
• perlobj Perl objects
• perltie Perl objects hidden behind simple variables
• 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
• 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

• perlutil utilities packaged with the Perl distribution

• perlcompile Perl compiler suite intro

• perlfilter Perl source filters

Por último - solo para gurus - estan los documentos que describen las partes internas de Perl:

• 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

• 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

La opción -l de perldoc permite ver en que directorio se encuentra la documentación:

$ perldoc -l perlintro
/usr/share/perl/5.8/pod/perlintro.pod

Si se desea convertir desde pod a algún formato específico, por ejemplo a L^ATEX basta con usar el conversor adecuado:

$ pod2latex -full `perldoc -l perlintro`
$ ls -l perlintro.tex
-rw-r--r-- 1 pp2 pp2 24333 2008-02-21 13:22 perlintro.tex
$ pdflatex perlintro.tex
This is pdfeTeX, Version 3.141592-1.30.5-2.2 (Web2C 7.5.5)
entering extended mode
....................................................................
$ ls -ltr *.pdf | tail -1
-rw-r--r-- 1 pp2 pp2 191367 2008-02-21 13:22 perlintro.pdf

En este caso hemos usado pod2latex. Para poder ejecutar la conversión de .pod a L^ATEX asegúrese de tener instalado el módulo Pod::LaTeX (puede obtenerlo desde CPAN).