Generar libros para devhelp

devhelp es un brower de documentación técnica. Hay disponibles libros para instalar en devhelp. Un libro es la documentación empaquetada de algún programa o herramienta concreta. Esta receta explica como hacer tus propios libros.

Un ejemplo para empezar

Se supone que en Debian hay un paquete llamado devhelp-book-pygtk2, pero no instala desde hace muuucho, aunque no sé porqué sigue saliendo en los listados de paquetes. Como podrás deducir se trata de la documentación de la libreria GTK 2.0 para Python. Vamos a ver cómo conseguir nuestro libro de PyGTK2.

  1. Descarga la referencia de la librería de PyGTK, en formato HTML, que te la dan ya comprimida en un tar.
  2. Descomprímelo en ~/.devhelp/books/:
    ~/.devhelp/books$ unp pygtk2reference.tbz2
  3. Ahora descarga esto y lo copias en ~/.devhelp/books/pygtk2reference

Ya está instalado. Ejecuta devhelp y ahí lo tienes.

Qué es un “libro devhelp”?

La cuestión es que la documentación son ficheros HTML. El libro en si sólo es el fichero .devhelp que te has bajado. Si lo abres verás que es un XML que contiene todos los metadatos del libro, es decir, la estructura, el índice, la tabla de contenidos, etc.

En realidad los HTML se generan a partir de la documentación original, que suele estar escrita en DocBook. El fichero .devhelp se genera con una XSL llamada devhelp.xsl que viene con el paquete gtk-doc-tools. Y dado que esta XSL ya forma parte del sistema de construcción de documentación de GNOME/GTK cualquier paquete de documentación incluye el .devhelp y se instala como libro automáticamente en Debian. De modo, que para conseguir el libro de PyGTK basta con instalar el paquete python-gtk2-doc, el tutorial está en python-gtk2-tutorial y el libro de la referencia general de python está en python2.4-doc

Cómo se crean

Pues lo dicho, a partir de la documentación en gtk-doc (que es DocBook) es tan simple como ejecutar:

xsltproc —output index.html /usr/share/gtk-doc/data/gtk-doc.xsl documento.sgml

Y el resultado se deja en ~/.devhelp/books

Libros ya hechos Referencias

Comentarios

Opciones de visualización de comentarios

Seleccione la forma que prefiera para mostrar los comentarios y haga clic en «Guardar las opciones» para activar los cambios.
Imagen de david.villa

CHM

Otro formato interesante para documentación navegable es CHM (que es HTML “compilado”), sí sí, el de la ayuda de Window$. Hay visores de CHM bastante curiosos como xchm o GnoCHM (gnochm en Debian).

No soy portavoz de ningún colectivo, grupo o facción. Mi opinión es personal e intransferible.