Construyendo una pagina sencilla del man

Hace mucho que no escribo por aqui y mucho más que no lo hago sobre algo relacionado con GNU/Linux, por lo que ya va siendo hora de cambiar esto. Estos dias atrás a raiz de una pregunta en Ubuntu-es, que Odin lo tenga en el Valhalla, estuve investigando sobre la construccion de paquetes deb para empaquetar un simple script (tal vez en otro momento escriba algo sobre eso), y al montar el paquete deb me encontré estudiando como hacer páginas del man, sí me refiero a esas que existen en cualquier sistema Unix o GNU/Linux y que mucha gente decide ignorar porque suele ser más cómodo preguntar a leer la documentación. El caso es que como lintian, que es una especie de validador de paquetes tiene el capricho de avisarte cuando en tu paquete no viene la pagina del man correspondiente, me puse a estudiarlo para ser capaz de generar algún "man" sencillo. Lo primero que hace falta tener instalado es la utilidad a2x (o asciidoc), que en Ubuntu y supongo que en Debian también, se encuentran en el paquete asciidoc. Una vez instalado, lo siguiente que hay que hacer es escribir un archivo de texto que contenga lo que queremos mostrar en la pagina del man, con unas pequenas marcas para que luego el man nos lo saque subrayado, en negrita, ... Por ejemplo si ponemos palabras encerradas entre ' (comillas simples) eso acabara por transformarse en un texto subrayado, si lo ponemos encerrados entre * se convertirá en texto en negrita, si ponemos debajo de una línea un sucesión de = lo que estamos diciendo es que esa línea es el título de la página, y si lo que ponemos es una línea de - lo que hacemos es marcarlo como una sección. A continuación es suficiente con ejecutar el comando a2x pasandole como parámetros -f manpages y el nombre del fichero de texto y nos generará un fichero con el mismo nombre pero terminado en ".1". Si queremos ver como ha quedado podemos utilizar el comando man para que visualice el fichero generado. Vamos a ver un ejemplo para que todo quede un poco más claro. Supongamos que tengo un script muy tonto, que convierte ficheros de formato aac a formato mp3 (aac2mp3):

#!/bin/bash
#
# aac2mp3
#

if [ $# -ge 1 ]; then
   if [ "$1" = "-h" -o "$1" = "-H" ]; then
       echo "$0 : Convierte ficheros aac a formato mp3"
       echo "$0 [-d diraac] : Convierte los ficheros de diraac"
       echo "$0 [-h] : Muestra la ayuda"
       exit 0
   fi
   if [ "$1" = "-d" -o "$1" = "-D" ]; then
       diraac=$2
       if [ ! -d ${diraac} ]; then
          echo ${diraac} no es un directorio
          exit 1
       fi
       cd ${diraac}
   fi
fi

for i in *.aac; do
   faad -w "$i" | lame - "${i%.aac}.mp3"
   sleep 180
done

Como se ve este script tan simple lo que hace es convertir todos los ficheros aac de un directorio a formato mp3. Así, si queremos crear una página del man para este script podriamos partir del siguiente fichero de texto (aac2mp3.txt):

aac2mp3(1)
=========
Jose Luis Jimenez <jljmarin@gmail.com>
v1.0, Julio 12 de 2009

NAME
------
aac2mp3 - Un sencillo script para convertir de aac a mp3

SYNOPSIS
--------
'aac2mp3' [-h] [-d directorio]

DESCRIPCION
-----------
aac2mp3(1) convierte todos los ficheros *.aac* que encuentra en un
directorio a formato *mp3*.

Si no se le indica ningún directorio convierte los ficheros del
directorio desde el que se ejecuta.

Para lograrlo utiliza *faad* y *lame*.

OPCIONES
--------
-d directorio::
        Convierte los ficheros .aac del directorio indicado
-h::
        Muestra la ayuda del script

AUTOR Y CREDITOS
----------------
aac2mp3 es escrito y mantenido por Jose Luis Jimenez <jljmarin@gmail.com>.

Con el fichero anterior al ejecutar:

a2x -f manpage aac2mp3.txt

nos genera un fichero de nombre aac2mp3.1 y al visualizarlo con man

man ./aac2mp3.1

vemos nuestro texto como una página del man. Lo único que quedaría sería comprimirlo con gzip:

gzip --best aac2mp3.1

y copiar el fichero comprimido (obviamente como root) a /usr/share/man/man1 sudo cp aac2mp3.1.gz /usr/share/man/man1 Si en lugar de ir en la sección 1 del man quisieramos ponerlo en otra, por ejemplo la 3, lo único que habría que hacer es sustituir la primera línea del fichero anterior por: aac2mp3(3) y de esa forma el fichero generado al procesarlo con a2x será aac2mp3.3 y el directorio donde debería copiarse sería /usr/share/man/man3. El resultado final se puede ver en la siguiente imagen: [caption id="attachment_383" align="aligncenter" width="300" caption="man aac2mp3"][/caption]