Recientemente, para un mini proyecto personal realizado en Java y Swing, necesité integrar un sistema de ayuda.
Naturalmente pensé en el sistema estándar y predeterminado de Java para Swing:
JavaHelp. Este nos permite crear un sistema de ayuda completo con tabla de contenidos, secciones, buscador y todas las funciones que esperamos encontrar. Incluye un SDK para el desarrollo, visualizadores, ejemplos y hasta puede extenderse para personalizarse si lo deseamos. Como está implementado 100% en Java, automáticamente está disponible para todas las plataformas.
Aunque lo conocía de antes, hasta el momento nunca había tenido oportunidad de usarlo, así que era una buena excusa para incursionar en el tema. Pero me encontré con un pequeño problema: no me parecía del todo útil aprender otro lenguaje de marcado, cuando encima solo podría generar como resultado archivos de ayuda en dicho formato. Estaba pensando en usar algo más universal, que pudiera generar salidas al menos en pdf y html, además del formato JavaHelp.
Una de las mejores alternativas, si no la mejor, es
DocBook, que es el lenguaje XML específico para crear documentación en general y que cumple con todos los requisitos. Es un estándar muy usado para ello. Desde DocBook tenemos todas las opciones posibles para exportar a cualquier otro formato de salida, incluído JavaHelp, CHM, PDF, HTML (simple y multipágina), XML-FO y muchos más. Les enlazo una
introducción en castellano a DocBook, en la cual pueden encontrar el siguiente diagrama:
DocBook es una especificación abierta, implementada y soportada por distintas herramientas. Hasta existen editores visuales para escribir documentos en este formato, por si no queremos aprender el lenguaje de marcado. Es muy conocido y utilizado en el entorno GNU/Linux.
Pero para completar el círculo, el desarrollador en mi pedía automatizar el proceso. Investigando un poco más, busqué información hasta lograr armar el conjunto de herramientas adecuado. No hay mucha información al respecto, no al menos de forma completa. Terminé usando un script de ANT desde Eclipse 3.5 Galileo, con un archivo fuente XML en DocBook, y con el soporte de varias librerías, ya me permite generar toda la documentación completa tanto en JavaHelp como en HTML, y eventualmente en cualquier otro formato. Probablemente agregue PDF y tal vez CHM.
El mejor y más completo tutorial que encontré es
"Build DocBook XML in Eclipse". Hay que seguirlo al pie de la letra. Tiene un dato clave que es que la implementación Xalan/Xerces proporcionada por ANT en Eclipse no funciona debido a un bug, y debe ser reemplazarla por la última versión estable. Por supuesto, tuve ese problema :D. También fueron útiles en cierta medida los artículos
"Creating an Online Help System with JavaHelp and DocBook" y
"DocBook with Eclipse - Tutorial", que aportan algunos detalles más.
Aunque se supone que generar archivos de ayuda y documentación debería ser una tarea bastante habitual para todos los programadores, la ausencia de buenos tutoriales y algunas herramientas actualizadas que faciliten la tarea demuestran que no es tan así. Al final termino confirmando esa sensación de que es un ítem bastante olvidado. Ojalá sirvan estas lineas para facilitar la implementación de esta funcionalidad tan importante, tantas veces descuidada.
En este comienzo de la primavera, les tengo un regalito. Hoy publico un juego en SourceForge.net, como código abierto, bajo una licencia libre. Se trata del clásico juego de naipes españoles de la "Escoba de 15".
