Primeros pasos con Docbook

Hace tiempo tuve una pequeña aproximación a Docbook para escribir documentos "técnicos", en mi querida Slackware (¡qué recuerdos!). No nos pongamos sentimentales, nace ahora la inquietud de volver a recordar aquellos primeros pasos con Docbook, sgml, xml, xslt... Aunque ahora lo que lleva mi HDD es una Debian. Como en aquella época no dejé reflejada ninguna información al respecto, tendré que partir de cero. Lo primero de todo será instalar las herramientas con las que vamos a trabajar:


solar:/home/r0sk# apt-get install docbook docbook-utils jade sgml-base
Se instalarán los siguientes paquetes extras:
jadetex libkpathsea3 libncursesw5 libsgmls-perl libt1-5 libwww0 lynx sgmlspl sp tetex-base tetex-bin tetex-extra texinfo
Paquetes sugeridos:
sgmls-doc doc-base
Paquetes recomendados
openjade1.3 openjade tetex-doc dialog texi2html perl-tk
Se instalarᅵn los siguientes paquetes NUEVOS:
docbook-utils jadetex libkpathsea3 libncursesw5 libsgmls-perl libt1-5 libwww0 lynx sgmlspl sp tetex-base tetex-bin tetex-extra texinfo
0 actualizados, 14 se instalarán, 0 para eliminar y 542 no actualizados.
Necesito descargar 32,9MB de archivos.
Se utilizarán 116MB de espacio de disco adicional después de desempaquetar.
ᅵDesea continuar? [S/n]
s
...


Pongámonos cómodos mientras descarga el material necesario de trabajo (33Mb).  Una vez instalado todo el software procedemos a hacer varias pruebas, las conversiones se harán con jade definitivamente, esta herramienta reúne todas las carcterísticas que estamos buscando:


1.- Exportación a múltiples formatos (html y pdf principalmente)
2.- Exportación a html mᅵltiples (nochunk.dsl)
3.- Exportación a html ᅵnico (chunk.dsl)
4.- Exportación a html habilitando hojas de estilo css.
5.- Exportación a pdf usando jadetex


Una vez tenemos nuestro documeto.sgml creado y listo para procesar necesitaremos una dsl de donde jade lea las pautas a la hora de la exportación (por ejemplo si queremos que cree índice o no, en varios documentos o en uno solo, la hoja de estilo a aplicar en su caso, autonumeración de capítulos, etc...). Un ejemplo muy sencillo de una dsl sería lo siguiente:


<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL
]>

<style-sheet>
<style-specification use="docbook">
<style-specification-body>

(define %graphic-default-extension% "png")
(define nochunks #t)

(define %stylesheet%
;; Name of the stylesheet to use
"estilo.css")
</style-specification-body>
</style-specification>
<external-specification id="docbook" document="docbook.dsl">
</style-sheet>


Donde le digo a jade que el html generado use DocBook, vaya en un archivo único (nochunks) y use el archivo estilo.css para dar formato al código resultante. Guardaremos este documento como nochunk.dsl. Ahora llegamos al momento cumbre, la hora de exportar a html, nada más sencillo que usar el siguiente comando:


solar:/home/r0sk# jade -t sgml -d nochunk.dsl documento.sgml > documento.html


Lógico es que para que el archivo se visualice correctamente hemos de tener previamente definido el estilo.css en el mismo directorio que el html resultante.

Para finalizar solo he de hacer una pequeña referencia a las webs donde podeis encontrar todas las directivas para crear vuestros propios dsl, http://docbook.sourceforge.net/ y http://www.oasis-open.org/docbook/. Agradecer a Juanjo la paciencia y conocimientos prestados. Espero que ya no tengas excusa (hipotético lector) para documentar todos tus proyectos eficazmente.

About the author

Óscar
has doubledaddy super powers, father of Hugo and Nico, husband of Marta, *nix user, Djangonaut and open source passionate.