Creando y Accediendo man pages

Todo aquel que se inicia en Linux (o en cualquier sistema *nix) y busca información sobre cómo usar un comando, función de librería, dispositivo, etc, seguramente se encuentre con comentarios en la red referidos a leer el manual. Más de una vez se encontrarán con gente que utiliza las siglas RTFM (Read The F*cking Manual), con el afán de que la gente no sea vaga y lea los manuales, que para eso están!
En los sistemas *nix (y Linux en particular), los programas suelen venir con manuales que pueden ser accedidos desde línea de comandos utilizando el comando man. Todo aquel que lleva un tiempo utilizando Linux sabe que ésta es la fuente de información más directa, y a pesar de que los años pasan e internet se vuelve la mayor fuente de información, los man pages siguen ahí, y se siguen utilizando mucho.

Ahora, aquellos curiosos como yo, querrán saber dónde están estos manuales y en qué formato se escriben. Todo programador *nix debería saber cómo escribir el manual de su programa, que acompañe al programa en sí para que luego pueda ser accedido por los usuarios. Es por eso que me interesé en investigar y escribir este artículo.

Por suerte la vida nos sonríe y escribir manuales es extremadamente sencillo, sólo hace falta conocer la estructura básica. Los man pages se escriben en texto plano, utilizando ciertos tags para demarcar secciones y tipo de letra. Estos tags son interpretados por el procesador nroff (o groff) y traducido a formato lindo, entendible para el usuario.


Formato del manual

El procesamiento de los manuales es como el de los lenguajes HTML, LaTeX y otros. Los tags se interpretan y se formatean las líneas según el significado del tag. El sistema permite diversos formateos, como cambios de font, espaciado, margenes, y notas al pie, entre otros.
Actualmente, los procesadores más utilizados son nroff (newer roff) y groff (GNU roof), los cuales, descienden de troff, el cual a su vez es hijo de roff, y si seguimos para arriba en el árbol genealógico de este programa, nos encontramos con RUNOFF (cuyo nombre, supuestamente, proviene de la frase "I'll run off a document").

Como cualquiera que haya abierto un manual en Linux pudo observar, éstos se estructuran de la siguiente forma:
1. Cabecera
2. Nombre
3. Sinopsis
4. Descripción
5. Opciones
6. Recursos
7. Diagnósticos
8. Véase También
9. Copyright
10. Bugs
11. Autores

Como mencioné, el formato descripto es para los manuales de Linux, dado que los manuales Unix siguen un patrón algo diferente:
1. Cabecera
2. Nombre
3. Sinopsis
4. Descripción
5. Opciones
6. Archivos
7. Véase También
8. Bugs

Por supuesto que no todas las secciones son mandatorias. Si bien es deseable que un manual tenga las secciones citadas, es posible eliminar secciones que no sean relevantes. En los manuales de Linux también es posible encontrarse con las secciones:
- Valores de Salida
- Errores
- Entorno
- Versiones
- Conforme a
- Notas
- Ejemplos

Cada sección dependerá del tipo de manual que estemos armando. Los manuales pueden ser de alguno de los siguientes tipos:
0 - Header files
1 - Comandos estándar
2 - Linux kernel system calls
3 - Funciones de librería estándar de c
4 - Dispositivos especiales
5 - Formatos de archivo y convenciones
6 - Juegos
7 - Misceláneos, por ejemplo estándares (SQL, ISO, etc)
8 - Comandos de administración de sistema (generalmente sólo para root)
9 - Rutinas del kernel
n - nuevo [obsoleto]
l - local [obsoleto]
p - público [obsoleto]
o - viejo [obsoleto]

Para el funcionamiento que nosotros estamos buscando (crear un manual simple), los tags principales son los siguiente:
* .TH - Título del man page
* .SH - Titulo de sección
* .SS - Título de sub-section
* .PP - Nuevo párrafo
* .B - Texto en negrita
* .I - Texto en itálica
* .BR - Salto de línea
* ." - Línea de comentario

Para conocer otros tags, pueden dirigirse a Creating and Formating man pages o a troff/nroff quick reference. Ahora, veamos un ejemplo. Creamos un archivo de texto llamado dtransfer.txt que contenga el siguiente texto:

." seteamos un titulo
.TH dtransfer 1
." creamos una seccion
.SH NOMBRE
transferidor de archivos de demasiadovivo
.SH SINOPSIS
dtransfer -h <
.I host
> -p lt;
.I port
> -f lt;
.I file
>
.SH DESCRIPCION
Programa para transferir archivos entre máquinas
.SH OPCIONES
." poner opciones en subsecciones
.B -v
versión
.SH EJEMPLO
dtransfer -h 192.168.0.1 -p 4444 -f /home/demasiadovivo/man-pages.txt
.SH AUTOR
demasiadovivo

y luego verificamos que el manual tiene la forma que deseamos, utilizando nroff:
$ nroff -man dtransfer.txt
Si todo va bien, nroff nos mostrará la salida de cómo se ve el manual formateado.


Ubicación de los manuales

Ahora, qué hacemos con los manuales? es claro que si no los ponemos en una carpeta donde el comando man pueda encontrarlos, no nos servirá de mucho. En Linux, los manuales se ubican en /usr/share/man o /usr/local/man. Si inspeccionan la carpeta de manuales, observarán que existen varias subcarpetas, algunas de las cuales comienzan con man, osea, la palabra man más el número del tipo de manual. Así los manuales de comandos van en man1, los de funciones en man3, los misceláneos en man7, etc. También existe una convención para mantener manuales en distintos lenguajes, es por ello que en el directorio de manuales también podemos encontrarnos con un directorio por cada lenguaje. Por ejemplo, los manuales en español van en es, los japoneses en ja, los de alemania en de, etc. Dentro de cada directorio de idioma, se sigue la misma convención antes citada para los tipos de manuales, así nos encontraremos con es/man1 para los comandos, es/man3 para las funciones, etc.
Una vez que sabemos en dónde ubicar nuestro manual, nos hace falta saber algo más sobre el formato. Como mencioné más arriba, los manuales se escriben en archivos de texto plano, pero para que el comando man los encuentre, deberemos colocar el tipo de manual al final del nombre. Para mi ejemplo, el manual deberá llamarse dtransfer.1 (en lugar de dtransfer.txt). El 1 indica que es un manual de comando. El archivo de texto además deberá comprimirse con gzip antes de posicionarlo en el lugar que debe. Para ello podemos hacer un:
$ gzip dtransfer.1
Recopilando todo lo que tenemos hasta ahora, llegamos a que tenemos un manual de comando, escrito en español, así que deberemos ubicarlo en /usr/share/man/es/man1 (necesitaremos permiso de root para hacerlo):
# mv dtransfer.1.gz /usr/share/man/es/man1
Si todo fue bien, simplemente tipeando "man dtransfer" debería aparecer nuestro super elaborado manual, no es hermoso?

Para más información sobre la estructura de directorios donde van los manuales, pueden leer Filesystem Hierarchy Standard - 4.11 /usr/share: Architecture-independent data.


Más ejemplos

Como siempre, una de las mejores formas de aprender, es mirando ejemplos. Por suerte, contamos con miles! Simplemente vallan a /usr/share/man, descompriman los manuales que quieran y abranlos con su editor favorito para ver el formato.


Accediendo manuales

Dado que tenemos varios tipos de manuales en diferentes lenguajes, también es interesante saber cómo acceder a un dado manual utilizando el comando man. Si bien tipeando "man man" podemos obtener información sobre cómo usar man, para completar el artículo me parece interesante mencionar algunas opciones:
man -a, --all : nos muestra secuencialmente todos los manuales que encuentra sobre .
man : nos muestra el manual del tipo indicado en . Por ejemplo, si queremos ver el manual del comando time, tipeamos man 1 time, pero si queremos el manual para usar time en programación, hacemos man 7 time.
man -k, --apropos [palabra1] [palabra2] ... : busca todos los manuales en donde aparezcan las palabras claves dentro de la definición del manual.
man -w, --where, --location : muestra la ubicación del manual dentro del sistema de archivos.

El idioma del manual dependerá del locale que tengamos seteado. El locale es un conjunto de parámetros que definen características de nuestra localidad, como ser, lenguaje, codificación de caracteres, tipo de moneda, formato de hora, etc. El locale se setea utilizando las variables de entorno $LANG y $LC_* ($LC_COLLATE, $LC_CTYPE, $LC_MONETARY, $LC_TIME, $LC_NUMERIC, $LC_MESSAGES, etc). Si por ejemplo, en la variable $LANG tienen seteado es_AR.UTF-8, man primero buscará los manuales en español para la palabra buscada, si no lo encuentra, buscará entre los manuales default (en ingles de USA). Para leer un poco más sobre los locale, pueden visitar Locales en Ubuntu y Controlling your locale with environment variables.


Convirtiendo manuales

Para darle un cierre a este interesante tema de man pages, me gustaría citar algunas transformaciones que pueden hacerse a los manuales.
Odian ver los manuales en la consola?, son amantes de la web y quisieran ver los manuales desde el firefox? a no desesperar, porque existen facilidades para transformar los manuales a html. Una de estas herramientas es man2html, con la cual simplemente necesitaremos apuntar el browser a http://localhost/cgi-bin/man/man2html para leer y buscar manuales.

Utilizando groff y la opción -T también es posible transformar páginas en formato troff a ps, dvi, html, y con la combinación ps2pdf es posible obtener los manuales en formato pdf. Para más información, vean el manual de groff: man groff.

Por último, les va a resultar interesante saber que konqueror trae incorporado una función para formatear man pages e info pages. Simplemente basta tipear man: en la barra de direcciones para ver el manual en cuestión. Por ejemplo, si tipean man:ls verán el manual de ls. Sin dudas, konqueror es una gran herramienta que nos brinda muchísimas funciones.


Algunas otras referencias

Creating Linux Man Pages - How to Create On-Line Documentation for Linux
Linux Man Page HowTo
Creating a Linux Manual (man) Page
Man and Info Pages