… también son necesarias. A ver si aprendemos.
Creo que ya lo he mencionado antes pero por si acaso alguien se lo ha perdido lo cuento de nuevo. Llevo algunos años creando software para mi empresa que funciona específica y concretamente en Debian. Construyo los paquetes nativos y mantengo un repositorio para actualizar todas las máquinas de una manera que yo considero cómoda.
Hasta ahora no he echado en falta los detalles porque eran aplicaciones muy autocontenidas y podía saber lo que estaban haciendo. Pero ahora, como desde hace unos meses he refactorizado varias de ellas, tengo una pequeña gran colección de paquetes con sus correspondientes scripts y las dependencias entre ellos. Ya no puedo saber qué hace un programa simplemente analizando su nombre; antes algo como imprimir-facturas-venta era informativo. Ahora algo como ucs-build-root-trace me fuerza a mirar el código en el ejecutable o en el repositorio de donde viene. Y como no siempre incluyen un parámetro help que me enseñe qué hacen empiezo a ponerme un poco tenso.
He buscado una solución que me sea más o menos cómoda. Cuando escribo programas Perl no tengo ningún problema. La documentación está contenida en los fuentes y existen herramientas automáticas de sobra para construir páginas de manual e instalarlas en los lugares adecuados del sistema operativo. Pero si los scripts están hechos en otro lenguaje no quiero tener que aprender más herramientas; me bastaría con algo tipo formulario, donde escribiese la información mínima, y que luego, automágicamente, se convirtiese en una página de manual estándar.
Una entrada en Linux Journal me ha puesto sobre la pista del programa txt2man de Marc Vertes y le he dado una oportunidad para ver si puedo integrarlo rápidamente en mi ciclo de desarrollo.
Este programa lee un archivo de texto plano, busca en él secuencias concretas que identifican las secciones y crea el fuente correspondiente en formato troff/groff (residuo de otros tiempos y que funciona maravillosamente siempre que esté muy, muy lejos de un humano).
El texto de entrada puede ser algo tan sencillo como lo siguiente:
NAME scriptname - script short description SYNOPSIS Example of use DESCRIPTION Long description OPTIONS -h Show help -v Show version ENVIRONMENT Special environment settings BUGS List of program's bugs AUTHOR Victor Moral
La integración de este programa en mi desarrollo la he conseguido mezclando los siguientes elementos:
- Creación de un directorio con las páginas de manual en docs/manpages.
- Creación de unas reglas en el archivo Makefile que reconstruyen la versión final reconocible por la extensión .1 desde el fuente correspondiente con la extensión .txt.
- Añadir a la instalación en el archivo Makefile la copia de las páginas finales en el directorio correspondiente del sistema.
- Ignorar las páginas con la extensión final en el repositorio dado que cambian mucho y son útiles únicamente para construir el paquete.
El archivo Makefile las declara de esta forma:
MANPAGES=$(subst txt,1,$(wildcard docs/manpages/*.txt))
...
build: build-manpages
build-manpages: $(MANPAGES)
%.1: %.txt
txt2man $? > $@
install-manpages: build-manpages
install $(MANPAGES) $(DESTDIR)/usr/share/man/man1/
Y sólo tengo que preocuparme de mantenerlas actualizadas con los scripts a los que documentan.