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
Logic-error blog 
Mar 03, 2009 @ 03:15:27
Nota: si usan xsltproc en vez de xmlto hay que señalarle donde esta la plantilla, en debian se encuentra en /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl pero no se en donde esta en otras distros
Traducir una aplicacion pygtk-Glade « Python Mania
Mar 15, 2009 @ 21:53:58
Empaquetar un script python para debian « Python Mania
May 09, 2009 @ 15:22:45
Ago 04, 2009 @ 15:28:41
Que gran articulo. Te felicito. Hace rato busque una explicación sencilla. Finalmente la encontre.
Nov 01, 2010 @ 02:47:04
La pregunta del millón, cómo funciona la internacionalización con estos manpages? me refiero a cómo se almacenan en las carpetas de /usr/share/man los idiomas, español, inglés, y cómo hacer nuestros manpages en diferentes idiomas 😀
Dic 09, 2010 @ 20:52:20
el archivo .xml que se crea al abrirlo con un editor de texto te muestra (y puedes modificar) esa información, como el autor y demás.
Ahora dentro de /usr/share/man hay una serie de directorios con las siglas de los locates, por ejemplo en /usr/share/man/de/… están todas las paginas en alemán, en /usr/share/man/es/… están las en español y así para los demás idiomas. En general la estructura es mandir/locate/man-section/ en donde mandir usualmente es «/usr/share/man» y man-section corresponden a las sección, o sea man1, man2, man3…
Dic 09, 2010 @ 22:56:33
Osea al básicamente creamos un archivo en nuestro idioma que luego ponemos dentro de los man1 man2 man3, pero esos man1 man2…. que función tienen?, aparte de contener los documentos deben tener una función destinada, un orden por tipo de man, o categoría, sistema, de usuario….
Gracias
Dic 25, 2010 @ 00:29:25
man1, man2, etc. corresponden a las secciones o categorías de las paginas man, en resumen los números de las secciones son:
1 Comandos Generales
2 Llamadas al sistema
3 Biblioteca C de funciones
4 Ficheros especiales (normalmente dispositivos, que se pueden encontrar en /dev) y drivers
5 Formatos de fichero y convenciones
6 Juegos y salvapantallas
7 Miscelánea
8 Comandos de administración del sistema y Demonios
así por ejemplo wget es un comando general por lo que va en man1, en cambio el exit que es parte del sistema (el que cierra el terminal) va en man2 y el exit que es una librería de c va en man 3
Ene 30, 2011 @ 04:53:07
Hola, me ha servido de mucho tu artículo.
Pero tengo una duda. ¿Como hago saltos de línea?
Es decir, si tengo algo como:
Hola
Adios
OOOO
Al abrir el manpage con man -l …..
me saldrá como «Hola Adios OOOO», es decir, se quita el cambio de línea.
Espero me puedas ayudar.