Re: Como escribir documentacion para man
Andres Seco Hernandez wrote:
> Estoy perdido. Creo que con el sgml se pueden hacer paginas man. He usado
> sgml para escribir howtos, pero no tengo ni idea ni donde hay informacion
> de como hacer paginas man.
> ¿Hay algun otro método?
> Tengo que hacer 2 para un programa nuevo que tengo sin documentar.
Después de ensayar vários métodos como sgml, escribir directamente en
troff, etc, llegué a la conclusión que la mejor forma de hacer páginas
de manual es usando "perl". No es nada complicado ni es necesario saber
nada de perl.
El perl viene con un utilitario llamado pod2man (además de pod2html,
pod2tex y pod2text). "pod" quiere decir "Plain Old Documentation".
Por ejemplo, para escribir la página de manual de un programa que me
convierte un glosario en código sgml para docbook (programa
dict2docbook, ftp://quark/pub/orca/) escribí lo siguente en un fichero
(ejemplo-pod):
=head1 NAME
dict2docbook - Creates a SGML (DocBook) version of glosario.dict
=head1 SYNOPSIS
S<dict2docbook filename>
=head1 DESCRIPTION
This programs reads the glosario.dict text file and creates a SGML
version of it, conforming to the DocBook DTD.
=head1 AUTHOR
Jaime Villate E<lt>villate@fe.up.ptE<gt>.
=cut
Después he hecho:
pod2man ejemplo-pod >ejemplo-pod.1
para crear la página de manual, que después puede ser leída con:
man -l ejemplo-pod.1
La sintaxis completa del pod está explicada en "man perlpod", y es
bastante simple. El único paquete que necesitas es perl (o sea, hoy en
día en Debian, perl-5.004 o perl-5.005). Si el programa que quieres
documentar está escrito en perl, el código pod puede estar dentro del
mismo programa y puede servir tanto para documentar el código fuente,
como para crear la documentación adicional.
Saludos,
Jaime Villate
Reply to: