Primeros pasos con Docbook
28.oct 2004
Envía un trackback
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 reune todas las caracter�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.
Escribe tu comentario
Intenta que tu comentario sea interesante y con información relevante al tema de la entrada. BBCodes disponibles:
[url=http://direccion]texto[/url], negrita: [b]texto[/b],
itálica: [i]texto[/i], subrayada: [u]texto[/u].
Para mencionar o citar a alguien (quote): [cita]texto[/cita]
