Man: Creando nuestros propios manuales Linux

Recientemente mirando diferentes manuales y ayudas de algunas aplicaciones y/o scripts estuve pensando que si bien son realmente útiles, no tenemos por costumbre crear nuestros propias guías de ayuda. Esto no lo digo desde el punto de un desarrollador o un administrador de sistemas, sino desde el punto de la manejabilidad de un programa o script. Cuando alguien crea una aplicación, conoce ésta como si fuese su propio "hijo" ya que ha estado creándola con cariño y esfuerzo hasta alcanzar el resultado deseado, pero el hecho de que el creador conozca los entresijos de su aplicación, no implica que el resto tenga la misma facilidad... A veces la aplicación en cuestión no tiene misterio alguno, ya que se basa en un simple ejecutable que efectúa una tarea y listo ¿Pero que ocurre cuando tenemos una aplicación que ofrece diferentes posibilidades? Probablemente alguno piense en la posibilidad de añadir un parámetro -h (help) para brindar ayuda al usuario, pero el uso de este recurso debe de ser con fines muy genéricos... Es decir, no podemos poner un enorme párrafo que explique al detalle todo, sino unas ayudas generales de los parámetros que ofrece la aplicación. Es por ello que cuando se quiere brindar una guía muy detallada con respecto a la aplicación, se debe recurrir a un recurso un poco más profundo y avanzado: Un recurso llamado man.

¿Cuantas veces hemos usado el comando man para orientarnos en el uso de un nuevo programa? ¿De cuantos atolladeros hemos salido al navegar por los entresijos de los manuales ofrecidos por este comando? Esta herramienta, aunque es muy minimista, pues está basada en la consola, ofrece una ayuda indispensable a los usuarios, sin importar el nivel de conocimientos de éstos; es por ello que se trata de un recurso muy a tener en cuenta a la hora de querer compartir una herramienta con el público... Así bien ¿De donde proceden dichos manuales? Obviamente han sido escritos y generados por alguien, pero más de uno puede pensar que este proceso resulta laborioso y complicado, si bien no lo es tanto como parece... Para ello, lo primero y más aconsejable sería coger un manual y "diseccionarlo" con el fin de saber como funciona, ya que aunque a primera vista no lo parezca, el contenido de un manual, y lo mostrado por éste al escribir man "programa" difieren bastante.

Comencemos entonces seleccionando un programa al azar; yo en mi caso he optado por uno que viene incluido en el sistema por defecto llamado gpg, pero no importa cual escojamos siempre y cuando éste se encuentre instalado en el sistema y tenga un manual incluido... Para ello lo primero que habría que saber es donde se "esconde" gpg y todo lo relacionado con éste; lo cual lograríamos preguntando al sistema donde ésta; es decir, usando el comando whereis tal y como muestro a continuación:

1. whereis gpg

Al preguntarle esto al sistema, obtendremos la localización de los distintos ficheros asociados a éste, entre los cuales uno de ellos nos interesaría especialmente; Dicho fichero (sea cual sea el programa que estemos buscando) siempre estará alojado en un subdirectorio que se encontraría en el interior de /usr/share/man. El subdirectorio en cuestión variaría dependiendo del programa buscado, pero es importante tener presente esta ruta inicial para buscar nuestro manual; Por ejemplo en mi caso el manual de gpg estaría alojado es /usr/share/man/man1/ y su nombre sería gpg.1.gz. Para no alterar este fichero tan importante, lo ideal sería copiarlo en otro directorio para poder manipularlo sin miedo alguno a modificar su interior o a corromperlo por accidente; esto se realizaría mediante el comando cp y yo por ejemplo he optado por copiarlo al directorio /usr/src/:

1. cp /usr/share/man/man1/gpg.1.gz /usr/src/

Dependiendo del manual que estemos buscando puede estar almacenado en una carpeta man distinta, pues si observáis el contenido de la carpeta man, veréis que aparecen 8 secciones distintas referentes a la carpeta man; secciones con una representación numérica que va del 1 al 8. Por ejemplo gpg se encuentra en la sección 1 (man1) pero en cambio si buscásemos iptables veríamos que se encuentra en la sección número 8... Estos números tienen su razón de ser... Con el fin de tener todo correctamente estructurado, se han establecido una serie de estándares numéricos, para que dependiendo del tipo de programa, su manual correspondiente sea almacenado en una carpeta u otra.  Dichos estándares son denominados números de sección y he aquí el listado de los susodichos junto con su función y/o propósito correspondiente:

1. 1 Programas ejecutables y guiones del intérprete de órdenes
2. 2 Funciones provistas por el núcleo (kernel) del sistema
3. 3 Funciones de la biblioteca del sistema
4. 4 Ficheros especiales (se encuentran generalmente en /dev)
5. 5 Formato de ficheros y convenios p.ej. I/etc/passwd
6. 6 Juegos
7. 7 Paquetes de macros y convenios p.ej. man(7), groff(7).
8. 8 Órdenes de administración del sistema (generalmente solo son para root)

Ahora que tenemos nuestro fichero en un lugar seguro, podemos manipularlo sin miedo. Si observáis bien, el fichero en cuestión está comprimido en formato gzip, con lo que lo primero que tendríamos que hacer para poder pasar a su manipulación sería descomprimirlo mediante el comando:

1. gzip -d /usr/src/gpg.1.gz

Con el fichero descomprimido, ya se podría observar lo que hay en su interior sin problema alguno... Al ser un fichero bastante extenso y que queremos revisar con atención, recomiendo prescindir del uso del comando cat y optar por un editor de texto a vuestra elección (vi, nano, mcedit...) o por hacer uso del comando less. Explorando con atención el fichero veréis que está plagado de diferentes secciones que definen cada uno de los aspectos del manual; desde el título, a párrafos y secciones que luego son mostradas en el manual de distintas formas, dependiendo de las nomenclaturas utilizadas en el manual... Dichos parámetros o nomenclaturas son denominados macros de formato, y forman parte del formato de texto que se mostrará al usuario final. Las macros que aparecen en el fichero pueden resultar algo confusas para nosotros... No son descriptivas ni tienen un guión que muestre qué hace cada cosa; es por ello que a continuación os explicaré la función de cada uno de los éstas.

Comencemos con la primer macro de todas, que hace referencia al título del manual; representada como .TH. Aquí es muy importante tener en cuenta que el título que se vaya a poner debe de seguir una estructura determinada, estructura que debe de seguirse si queremos que la macro en cuestión funcione correctamente. La estructura siempre sería la misma:

.TH nombre-comando número-sección fecha-creación Autor título-manual

Por ejemplo en gpg el título sería:

.TH GPG 1 2015-03-08 "GnuPG 1.4.12" "GNU Privacy Guard"

Además del título, se pueden generar diferentes secciones en el manual; secciones que vienen representadas con la macro .SH y que siempre tienen la estructura:

.SH nombre_sección

A diferencia de con el título, aquí no es necesario seguir procedimiento alguno para la asignación de secciones... Lo importante es tener clara la estructura del manual para ser lo más informativo posible para el usuario final... Un listado de ejemplo de los nombre de secciones más usados sería:

NAME /NOMBRE

Nombre del comando, archivo o herramienta.

SYNOPSIS /SINOPSIS

Sintaxis de uso de forma muy resumida.

DESCRIPTION /DESCRIPCION

Descripción del comando, archivo o herramienta.

OPTIONS/OPCIONES

Descripción de las opciones aceptadas en la línea de comandos por el comando o herramienta. Normalmente solo se implementa en las secciones 1 y 8.

COMMANDS/COMANDOS

Listado de los comandos asociados a la herramienta. Por lo general solo se suelen usar opciones pero a veces también se hace uso de esta sección.

ENVIRONMENT /ENTORNO

Muestra una lista de las variables utilizadas por el comando o herramienta, describiendo cómo son usadas.

FILES /ARCHIVOS

Listado de todos los archivos utilizados por el comando o herramienta.

BUGS /ERRORES

Descripción de errores o problemas conocidos.

EXAMPLE /EJEMPLO

Ejemplos de uso del comando o herramienta.

AUTHORS/AUTORES

Lista de los nombres de los autores. Generalmente se utiliza el formato: Nombre del Autor <email@example.org>.

SEE ALSO/VÉASE TAMBIÉN

Una lista de páginas man sugeridas, separadas por coma.

El listado puede ser mayor, pero estos podrían considerarse como los recursos "estándar" o los recursos más usados... Teniendo definidas las secciones, no podemos olvidar que a veces es necesario recurrir a algunos formatos para resaltar algunas partes de nuestro contenido, ya sea para ponerlo en negrita o para ponerlo en subrayado. Los métodos para dar formato al texto serían:

.B --> Negrita
.I --> Subrayado
.R --> Romana

Estos parámetros o macros podrían combinarse entre sí, creando cosas tales como .BI, .IR, etc... Un inconveniente que ofrecen estos parámetros es que ocupan toda la línea, a menos que les digas lo contrario... Todo lo que vaya después de una de estas macros de formato, iría automáticamente en dicho formato, a menos que después se introdujese de otro formato nuevo que interrumpiese el anterior; por ejemplo:

.B esto es una .I prueba --> esto es una prueba

Otra forma de hacer esta cambio pero teniendo todo mejor controlado ,sería usando los mismos caracteres (es decir B I y R) precedidos por \f. Con esto no sería necesario recurrir a espacios entre cada macro, siendo muy cómodo cuando queremos introducir pequeños cambios en párrafos grandes. Si nos basásemos en el ejemplo anterior sería:

\fBesto es una \fIprueba --> esto es una prueba

Con los formatos bien claros, podríamos pasar a otro aspecto muy importante de los manuales. los párrafos y saltos de línea. El salto de línea es muy parecido al que se usa en HTML; ya que se usa la macro .br. Mientras que cuando queremos presentar un párrafo, la macro .PP sería la encargada de lograr dicho objetivo.

Por último pero no menos importante estarían los comentarios... Un comentario se trata de más ni menos que texto que solamente aquel que entre en el propio manual (es decir, que haya entrado como nosotros y no mediante el comando man) puede ver. Esto puede ser útil cuando queremos que las futuras ediciones de éste sean realizadas por otra persona. Esto lo lograría mediante la macro .\

Ahora que tenemos las nociones generales, vamos a crear un pequeño manual basándonos en estos conceptos. El manual hará referencia a un script; con lo que su número de sección sería el 1; Al tener que poner siempre el número de sección como extensión del manual, en este manual de ejemplo llamaríamos a nuestro manual test.1. He aquí el texto que incluiremos en nuestro manual:

1. .\Comentarios del autor
2. .TH test 2015-07-23 Ivan "Manual de test"
3. .SH NAME
4. \fB test\fR - Manual de test con test en negrita
5. .SH SYNOPSIS
6. .I Este es un breve manual de pruebas subrayado
7. .SH DESCRIPCION
8. Aquí describiremos todas las características del programa
9. .PP
10. Este es un párrafo nuevo aparte del primero
11. .br
12. Además hemos añadido una nueva línea
13. .SH FILES
14. Los ficheros necesarios para usar el programa en caso de haberlos
15. .SH AUTHOR
16. .BI He aquí los datos del autor

Aunque tenemos el manual preparado, todavía no estaría listo para ser usado... Aun falta agregarlo al directorio de manuales... Para ello habría que comprimir el archivo en el mismo formato que el resto de ficheros, es decir; hay que comprimirlo en formato gzip. Esto es tan sencillo como escribir:

1. gzip -q test.1

El comando daría como resultado un fichero denominado test.1.gz... fichero perfectamente válido para ser usado como manual; solamente quedaría alojarlo en el directorio correcto. Tal y como he comentado antes, se trata de un fichero cuyo número de sección es 1, con lo que la carpeta en la que habría que alojarlo sería en /usr/share/man/man1/. Con el fichero correctamente situado, ya podríamos escribir el comando:

1. man test

Que daría como resultado el siguiente manual:

Esto sería todo por hoy. El manual creado es muy sencillo, pero puede extenderse tanto como nosotros necesitemos, siempre y cuando respetemos la sintaxis y las macros atrás mencionadas.

Espero que os haya resultado útil.

Saludos.