Perl/Pod::Usage

Módulo	Pod::Usage
Versión	Debian rama estable
Uso	Programas de consola
Propósito	Genera textos de ayuda desde la documentación en formato POD presente en el fuente del programa desde el que se le llama.

Referencia rápida

Los parámetros más empleados son los siguientes:

Mensaje

Texto a enviar antes que la ayuda.

Nivel de verbosidad

Según su valor numérico las secciones de documentación empleadas en la ayuda generada son:

• Cero (0) emplea sólo la sección SYNOPSIS.
• Uno (1) utiliza las secciones SYNOPSIS, OPTIONS, ARGUMENTS y OPTIONS AND ARGUMENTS.
• Dos (2) utilizará toda la documentación que encuentre.

Valor de salida del programa

Número que usar como parámetro para la función exit().

Si se usa un único parámetro este puede ser:

• pod2usage( $mensaje )
• pod2usage( $codigo_de_salida )
• pod2usage( \%params ) donde la lista indexada puede contener:
  • -message|-msg: para indicar el mensaje
  • -exitval: para el valor de salida de programa
  • -verbose: para el nivel de verbosidad

Ejemplos

#!/usr/bin/perl

use strict;
use warnings;
use Getopts::Long;
use Pod::Usage;

my $help = 0;
my $man  = 0;
GetOptions( 'help|h' => \$help,
            'man'    => \$man
) or pod2usage(0);
pod2usage(1) if $help;
pod2usage(2) if $man;

Plantillas

Los siguientes textos sirven como plantillas para documentar programas o módulos. Basta con incluir el texto en el fuente, rellenar con valores aquellas partes encerradas entre signos "menor que" y "mayor que" (como <application name> y retocar aquellas otras que no interesen o no se ajusten a lo necesario, como la licencia de uso asignada.

Los títulos de las secciones están en inglés porque después van a ser tratados con programas de uso general (como gettext). Algunos otros, como las licencias, porque si no hay una traducción muy correcta de las mismas estaremos indicando otra cosa distinta.

Genérica para un programa

__END__

=pod

=encoding utf-8 

=head1 NAME

nombre - descripción breve 

=head1 SYNOPSIS

nobmre [options] [file ...]

=head1 OPTIONS

=over 

=item B<-param1>

Descripción del parámetro ''-param1''.

=item B<-param2>

Descripción del parámetro ''-param2''.

=back

=head1 DESCRIPTION

Descripción más completa del programa.

=cut

Diagnósticos, dependencias y errores

=head1 DIAGNOSTICS

Una lista de cada uno de los mensajes de advertencia y error que el programa puede mostrar 
junto a una explicación del problema, causas probables y alguna sugerencia 
sobre cómo evitarlo. Se deben indicar también los códigos de salida del 
programa si los produce alguno de los errores.

=head1 CONFIGURATION AND ENVIRONMENT

Una completa explicación de cualquier mecanismo de configuración usado por el programa, 
incluyendo nombres y localizaciones de archivos de configuración, variables de entorno 
o propiedades que puedan emplearse. En resumen, cualquier información externa 
que pueda condicionar o modificar el funcionamiento del programa. 

=head1 DEPENDENCIES

Lista de todos los módulos Perl y otros programas que éste requiere para funcionar,
incluyendo versiones mínimas, e indicaciones sobre si dichas dependencias forman 
parte de la distribución estándar del lenguaje Perl, se instalan con el propio 
programa o deben ser instaladas por separado.

=over

=item * modulo|programa

=back 

=head1 INCOMPATIBILITIES

Relación de cualquier módulo Perl que no pueda ser empleado junto a éste, 
bien por conflictos en nombres en el interfaz, bien porque compiten por 
los mismos recursos del sistema, o bien debido a limitaciones del propio 
lenguaje en mecanismos como los filtros de códigos fuente. 

=head1 BUGS AND LIMITATIONS

No hay errores conocidos en este programa. Si los encuentra, por favor, 
informe a <NOMBRE> (<EMAIL>).

Derechos de copia y licencia Perl

=head1 AUTHOR

NOMBRE <EMAIL>

=head1 LICENCE AND COPYRIGHT

Copyright (c) YEAR <NOMBRE>. All rights reserved.

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See L<perlartistic>.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

=cut

Otros casos de uso

Elegir las secciones a mostrar

En el caso de que deseemos que se empleen únicamente unas secciones concretas tendremos que emplear un nivel de locuacidad de 99 y proporcionarle la lista de secciones que queremos usar. Esta última puede ser

• en forma de texto con los nombres de secciones separados por barras verticales ("NAME|VERSION|CAVEATS")
• o una lista de dichos nombres pasados por referencia ([ qw( NAME VERSION CAVEATS ) ])

Ejemplo:

GetOptions( 'version' => \$version, 'license' => \$license );
pod2usage( -verbose => 99, -sections => "NAME|VERSION" ) if $version;
pod2usage( -verbose => 99, -sections => [qw( NAME VERSION LICENSE COPYRIGHT )] )
  if $license;