Crear páginas para man usando perlpod

Jaime E. Villate

10 de enero de 2001

Perl viene con un utilitario llamado pod2man (además de pod2html, pod2tex y pod2text) que permite crear páginas de manual fácilmente. "pod" quiere decir "Plain Old Documentation". Por ejemplo, para crear la página de manual de un programa dict2docbook, se puede escribir lo siguiente en un fichero dict2docbook.pod:

=head1 NOMBRE
dict2docbook - Crea una versión SGML (DocBook) de glosario.dict
=head1 SYNOPSIS
S<dict2docbook fichero>
=head1 DESCRIPCION
Este programa lee el glosario glosario.dict y crea un fichero SGML a
partir de el, usando el DTD de DocBook.
=head1 AUTOR
Jaime Villate E<lt>villate@fe.up.ptE<gt>.
=cut

Después se usa:

pod2man --lax dict2docbook.pod >dict2docbook.1

para crear la página de manual. La opción lax se usa para que se acepten nombres diferentes a los habituales para las secciones, pues en este caso están traducidos al español. La página creada puede ser leída con:

man -l dict2docbook.1

La sintaxis completa del pod está explicada en "man perlpod", y es bastante simple; también se debe consultar la página de manual de pod2man. El único paquete necesario es perl.

Si el programa que se quiere documentar está escrito en perl, el código pod puede estar dentro del propio programa y puede servir tanto para documentar el código fuente, como para crear la documentación adicional para man.




Página creada en: 2004-11-04 11:40:56 +0000
© Copyright 2001, 2002, 2003, 2004, La Espiral, debian-laespiral@lists.debian.org
Permitida la copia y distribución textual, integral, siempre y cuando se mantenga este aviso.