Documentación básica
Perl viene con un montón de documentación incluida. Casi un millón de palabras repartidas en casi doscientos documentos.
Todo está en Inglés, pero con la distribución POD2::ES se tiene acceso a versiones en Español de los documentos más importantes (Instalación de módulos y bibliotecas en Perl).
La distribución Linux incluida en su sistema, suele venir acompañada de la documentación, que suele estar almacenada en forma de páginas de manual (en los sistemas tipo UNIX). Algunos sistemas no traen esta documentación, por lo que hay que instalarla como un paquete de software aparte. Tendrá un nombre parecido a 'perl-doc' o 'perl-documentation'.
En sistemas basados en Debian (como Ubuntu, por ejemplo), bastará con escribir sudo aptitude install perl-doc
En sistemas Windows, las distribuciones suelen crear versiones en HTML de estos documentos, así que el acceso a ellas será eligiendo la opción de ayuda o documentación desde el botón de Inicio (ver final de la guía de Instalación y uso de PPM)
Línea de comandos
Basta con escribir lo siguiente en una terminal de línea de comandos (solo si estamos en sistemas de la familia UNIX):
man perl
y saldrá la página de manual de perl, que contiene simplemente una tabla de contenidos con los nombres y descripciones del resto de documentos. También podemos usar el comando perldoc:
perldoc perldata
y se mostrará el documento perldata, que explica lo relacionado con las distintas estructuras de datos y variables que dispone perl.
Para salir del paginador que nos muestra la documentación, pulsamos sobre 'q' (generalmente).
Ayuda del comando: perldoc -h
Si hemos instalado la distribución POD2-ES, podemos acceder así:
perldoc -L ES perldata
Para no tener que escribir continuamente la opción '-L ES', podemos modificar el archivo ~/.bashrc (o aquel que se ejecuta cuando arrancamos la terminal de línea de comandos) y le añadimos una línea así:
export PERLDOC_POD2=es
en donde indicamos qué idioma preferimos en la presentación de la documentación. O también de forma automática
export PERLDOC_POD2=1
que le indica a perldoc que tome el idioma a partir de la variable de entorno $LANG.
Más opciones interesantes del comando perldoc:
- -f : para sacar la información de una función o de un operador. Ejemplo: perldoc -f chr
- -q : para buscar información en las FAQ (documentos de preguntas más frecuentes). Ejemplo: perldoc -q unique
- -v : para sacar la información de una variable especial. Ejemplo: perldoc -v $/
Documentación en web
Toda la documentación de Perl también se puede consultar vía web, en la dirección http://perldoc.perl.org
Existe un complemento para Firefox que permite hacer búsquedas desde la barra de dirección de Firefox (ver sección Forma de uso, más abajo).
Naturalmente, también se puede acceder a los documentos en CPAN y en MetaCPAN.
La versión en Español de la documentación se puede consultar en Github (archivos revisados, sin revisar), CPAN y MetaCPAN.
Documentación extra. Módulos
Los módulos suelen venir acompañados de su propia documentación. En casos excepcionales, esa documentación estará solo vía web.
Línea de comandos
Igual que antes, podemos usar los comandos man y perldoc para acceder a la documentación de cada módulo. Ejemplos:
$ man File::Find
$ perldoc DateTime
Documentación en HTML
Los usuarios de Perl en Windows, como es el caso de ActiveState, tendrán una versión en HTML de las páginas de manual, tanto de la documentación básica como de los módulos. Para acceder a ellas, habrá que seleccionar la opción Páginas de ayuda (o alguna parecida) colgando de Inicio -> Programas -> ActiveState (ver enlace anterior en la sección Documentación básica)
Para otras distribuciones, lo más seguro es que solo se disponga de la documentación a través del comando perldoc.
perldoc suele venir acompañado de una serie de utilidades que permiten convertir la documentación a varios formatos: pod2html, pod2latex, pod2man, pod2text.
Documentación web
Tanto en CPAN como en MetaCPAN podemos acceder a la documentación de los módulos y distribuciones.
Una herramienta muy útil para buscar información, o para buscar módulos que respondan a nuestras necesidades, es la caja de búsqueda de Firefox, a la derecha de la caja de direcciones. Ahí se pueden instalar una serie de motores de búsqueda relacionados con Perl:
Una vez instalados, podemos reordenarlos dentro del listado general de motores de búsqueda.
Forma de uso: o con el ratón, o con el teclado.
Supongamos que estamos trabajando en un código, en nuestro editor de códigos favorito, y queremos buscar un módulo que tenga que ver con algo relacionado con lo que estamos haciendo. Estos son los pasos a realizar desde el teclado (con el ratón es lo mismo, pero mucho más lento)
- Alt + tabulador : lo pulsamos una o más veces hasta tener el Firefox en primer plano (se supone que lo tenemos arrancado, claro)
- Control + t : creamos una pestaña nueva en Firefox
- Control + k : el cursor se coloca en la caja de búsqueda
- Control + [Arriba] o [Abajo] : usando las teclas del cursor seleccionamos el motor de búsqueda (CPAN, CPAN módulos, MetaCPAN o perldoc)
- escribimos el término a buscar y pulsamos la tecla Entrar. Y ya está.
- pasamos a Firefox y creamos una pestaña nueva, como antes
- Control + l : el cursor se coloca en la barra de dirección
- escribimos el atajo más la palabra a buscar. Si queremos buscar la información sobre DBI, escribiremos: cpan dbi
(Si hay algún error, o falta algún detalle, por favor, envíame un mensaje privado. Gracias)
