Una aplicación de consola decente siempre cuenta con una manpage para documentar cómo usarla. Sin embargo, las interioridades de las manpages son bastantes arcanas, aunque para ser un formato de fichero de 1971 ha aguantado bastante bien.
Hoy en día hay dos manera estándar de aprender a usar un comando de consola (aparte de buscar en google ;) ): tecleando el nombre de la aplicación, seguido de "--help", para obtener un resumen de cómo usar la aplicación, o teclear "man" seguido del nombre de la aplicación para obtener información detallada de cómo usarla.
Para implementar "--help" en nuestra aplicación podemos incluir un parseado manual de "--help", aunque lo más recomendable es usar una librería como la de python ArgParse para parsear argumentos de usuario.
El enfoque de usar el comando "man" implica escribir una manpage de tu aplicación..
La manera estándar de crear manpages es usar el formato troff. Linux tiene su propio estándar de implementación de troff, denominado groff. Si quieres cacharrear para hacerte una idea de cómo es el formato con el que se escriben las manpages, puedes teclear lo siguiente como el contenido de un fichero que se llame, por ejemplo, corrupt.1:
.TH CORRUPT 1
.SH NAME
corrupt \- modify files by randomly changing bits
.SH SYNOPSIS
.B corrupt
[\fB\-n\fR \fIBITS\fR]
[\fB\-\-bits\fR \fIBITS\fR]
.IR file ...
.SH DESCRIPTION
.B corrupt
modifies files by toggling a randomly chosen bit.
.SH OPTIONS
.TP
.BR \-n ", " \-\-bits =\fIBITS\fR
Set the number of bits to modify.
Default is one bit.
Una vez salvado, ese fichero puede visualizarse conel comando man. Suponiendo que estemos en la misma carpeta que el fichero corrupt.1, podemos teclear:
dante@Camelot:~/$ man -l corrupt.1
La salida será:
CORRUPT(1) General Commands Manual
NAME
corrupt - modify files by randomly changing bits
SYNOPSIS
corrupt [-n BITS] [--bits BITS] file...
DESCRIPTION
corrupt modifies files by toggling a randomly chosen bit.
OPTIONS
-n, --bits=BITS
Set the number of bits to modify. Default is one bit.
CORRUPT(1)
Puedes eligir escribir directamente manpages para tu aplicación siguien, por ejemplo, esta pequeña chuleta.
De todos modos, el formato troff/groff es bastante raro y en mi opinión mantener dos fuentes de información (tu README.md y tu manpage) no es sino fuente errores y un desperdicio de esfuerzos. Por eso sigo un enfoque diferente: escribo y mantengo actualizado mi README.md y luego lo convierto a una manpage. Es cierto que hay que mantener un formato estándar para que la conversión de README.md cuadre con lo que se espera de un manpage, pero al menos evitaremos teclear las mismas cosas dos veces, en dos ficheros diferentes, y con diferentes lenguajes de etiquetado.
La clave de la conversión es la herramienta denominada Pandoc. Esa herramienta es la navaja suiza de la conversión de documentos. La puedes usar para convertir entre muchos formatos documentales como word (docx), openoffice (odt), epub... o markdown (md) y groff man. Pandoc suele estar disponible en los repositorios estándar de la mayor parte de distribuciones de linux habituales, por lo que en un ubuntu no hay más que teclear:
dante@Camelot:~/$ sudo apt install pandoc
Una vez que Pandoc esté instalado, hay que respetar una serie de convenciones en nuestro README.md opara hacer que la conversión sea más sencilla. Para ilustrar las explicaciones de este artículo, vamos a seguir el ejemplo del fichero README.md de mi proyecto Cifra.
Como se puede ver, el README.md enlazado contiene medallas de GitHub justo al comienzo aunque las quitaremos antes de hacer la conversión, tal y como veremos más adelante. Todo lo demás está estructurado para cumplir con lo que se espera que tenga una manpage estándar.
Puede ser que lo más sospechoso sea la primera línea. No es normal encontrar una línea como esta en un README de GitHub:
En realidad, esa línea contiene metadatos para el visor de manpages. Tras el carácter "%" aparece el título del documento (generalmente el nombre de la aplicación), la sección del manual, una versión, un separador "|" y finalmente una cabecera. La sección del manual es 1 para los comandos de usuario, 2 para las llamadas de sistema y 3 para las funciones de C. Tus aplicaciones encajarán en la sección 1 el 99% de las veces. No he incluido una versión para Cifra en esa línea, pero lo podría haber hecho. Además, la cabecera indica a que categoría de documentación pertenece este manpage.
Tras esa línea, cada sección es de las habituales en un manpage, pero las únicas que deberían ser incluidas como obligatorias son:
- Name: El nombre del comando.
- Synopsis: Un resumen de una línea explicando los argumentos y las opciones.
- Description: Describe en detalle como usar el comando.
Otras secciones que se pueden añadir son:
- Options: Opciones del comando.
- Examples: Ejemplos de uso del comando.
- Files: Útil si tu aplicación incluye ficheros de configuración.
- Environment: Aquí se describe si la aplicaciónusa variables de entorno.
- Bugs: ¿Se deben reportar los bugs detectados? Aquí se puede enlazar la página de issues de GitHub.
- Authors: ¿Quién es el autor de esta pieza maestra?
- See also: Referencias a otros manpages.
- Copyright | License: Un buen lugar para incluir la licancia de tu aplicación.
Una vez decididas las secciones a incluir en el manpage, hay que escribirlas siguiendo un formato fácilmente convertible por pandoc en un manpage con una estructura estándar. Esa es la razón por la que en el README de ejemplo las secciones principales están todas marcadas con un nivle de indentación ("#"). Un problema con la indentación es que aunque en markdown se pueden conseguir múltiples niveles de indentación usando el carácter "#" ( "#" para los títulos principales, "##" para los subtítulos, "###" para las secciones, etc) esos subniveles sólo son reconocidos por Pandoc hasta el subnivel 2. Para conseguir más subniveles he tenido que tirar de las"pandoc lists", un formato que puedes usar en tu markdown y que luego lo reconoce Pandoc:
En las líneas 42 y 48 tenemos lo que Pandoc llama "line blocks". Estos son líneas iniciadas por una barra vertical ( | ) seguidas por un espacio. Esos espacios entre la barra vertical y el comando se conservarán en el texto del manpage que genere Pandoc.
Todo lo demás del fichero README.md de ejemplo es formato markdown clásico.
Supongamos que hemos escrito todo nuestro README.md y que queremos hacer nuestra conversión. Para hacer eso podemos usar un script como este desde una carpeta temporal:
Las líneas 3 y 4 limpian cualquier fichero usado en una conversión anterior, mientras que la línea 5 es la que en realidad copia el README.md desde la carpeta de origen a la de destino.
La línea 6 borra cualquier medalla de GitHub que podamos tener en nuestro README.md.
La línea 7 es donde llamamos a Pandoc para realizar la conversión.
Hecho eso, ya tendremos un fichero que puede ser abierto con man:
dante@Camelot:~/$ man -l man/cifra.1
Aunque los manpages suelen estar comprimidos con gzip, como se puede ver con los manpages de nuestro sistema:
dante@Camelot:~/$ ls /usr/share/man/man1
Esa es la razón por la que la línea 8 del script comprime el manpage generado. A pesar de estar comprimido, el manpage sigue siendo leíble por man:
dante@Camelot:~/$ man -l man/cifra.1.gz
Aunque son unos cuantos pasos, se puede ver que son fácilmente automatizables mediante un script o como un paso más de tu flujo de integración y despliegue continuo.
Como se puede ver, con estos sencillos pasos sólo se necesita mantener actualizado el README.md, dado que el manpage puede ser generado a partir de él.
