Este pequeño post es para explicar una manera rápida y fácil para escribir paginas de manual (mas conocidas como manpage).

Para ello necesitamos:

Que en debian se pueden instalar fácilmente haciendo:

aptitude install asciidoc xmlto

Ahora abrimos un editor de texto cualquiera y escribimos la manpage, por ejemplo voy escribir esta pagina inventada (la voy a guardar con el nombre ejemplo.txt):

EJEMPLO(1)
=========
John Doe <johndoe@loquesea.com>

NAME
----
ejemplo - Un ejemplo de manpage

SYNOPSIS
--------
*ejemplo* ['OPCION']

DESCRIPCION
-----------
Este es un ejemplo de como escribir una manpage usando asciidoc,
por lo tanto este texto no tiene mucho sentido y solo sirve de
ejemplo.

BUGS
----
Si descubre bugs, intente avisarlos

AUTOR
-----
Escrito por John Doe, <johndoe@loquesea.com>


REFERENCIAS
-----------
Asciidoc: http://www.methods.co.nz/asciidoc/

xmlto: http://cyberelk.net/tim/xmlto/

COPYING
-------
Normalmente se colocar en este lugar una nota sobre la licencia
del programa, pero como es un ejemplo lo dejo a su inmaginacion

Como ven se trata de un simple texto plano, sin ninguna gran complicación, ahora la vamos a transformar a un xml (formato DocBook) para ello hacemos:

asciidoc -b docbook -d manpage ejemplo.txt

Con eso generamos el clásico xml (DocBook) que se usa para escribir manpages.

Finalmente creamos el archivo en formato manpage a partir del xml haciendo:

xmlto man ejemplo.xml

y listo tenemos nuestra manpage, podemos visualizarla haciendo

man -l ejemplo.1

Eso es todo, así de fácil.

Si quieren ver verdaderas manpages creadas con asciidoc pueden revisar la manpage del mismo asciidoc o la de fluxbox

Nota: Si quisiéramos tener la pagina creada en nuestro como parte del sistema como predeterminado, simplemente tendremos que moverla a la ubicación en donde están alojados todos los manpages disponibles, en mi sistema (que es una debian) los manuales/manpages están ubicados en /usr/share/man

Casi se me olvidaba, si alguien quiere usar xsltproc en vez de xmlto para generar el manpage, se hace de la siguiente manera

xsltproc --nonet /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl ejemplo.xml