Antes que nada, se deberá tener instalado y funcionando un sistema DocBook (con todas las dependencias que implica: Jade, JadeTeX, las hojas de estilo DSSSL, etc). La instalación de un sistema sgml-DocBook está fuera del alcance de este tutorial. En Apéndice C se puede encontrar información sobre este punto.
Hay dos formas de tener funcionando el software dbtexmath. La primera es instalar el paquete original de DBTeXMath de Allin Cottrell. La segunda forma, la cual recomendamos por su simplicidad, es usar DBTeXMath junto con la hoja de estilo DSSSL ldp.dsl[1] para integrarla con DBTeXMath.
Recomendamos el uso de la segunda alternativa por las siguientes razones:
Simplicidad. Dado que no tendremos que hacer referencias a las hojas de estilo locales de nuestro sistema, el uso de DBTeXMath será más ágil y por lo tanto nuestros documentos serán más compatibles en otros sistemas
Ventajas implícitas de ldp.dsl. Entre las cuales se pueden enumerar entidades traducidas al español, formato de salida de calidad muy superior al de las hojas de estilo DSSSL comunes que vienen en nuestro sistema local, compatibilidad con la documentación de GNU/Linux, etc.
Solución de algunos problemas. Los símbolos que no están dentro de latex2 estándar, sino en paquetes auxiliares como latexsym o asmlatex, darán mensajes de error cuando tratemos de generar salidas en formato HTML. El problema fue solucionado en el paquete de que incluye DBTexMath junto con ldp.dsl.
Lo primero será bajar el paquete dbtexmath-0.3.tar.gz . Como alternativa se podrá bajar el paquete dbtexmath-es.tgz el cual es la versión de dicho software pero con los comentarios de los archivos en español y un breve explicativo de cómo instalarlo.
Dado que el paquete DBTexMath, como ya se dijo, consiste principalmente en una hoja de estilo DSSSL auxiliar a la de sgml-DocBook, lo único que deberemos hacer es modificar las rutas a algunos archivos locales (las hojas de estilo DSSSL DocBook de nuestro sistema) que aparecen en un par de ficheros de dicho paquete.
Se explicará todo con un ejemplo. Supongamos que creamos el archivo DocBook probe.sgml en el directorio en donde se desempaquetó DBTexMath, por ejemplo DBTexMath-0.3.
Importante: Es muy importante que nuestro documento SGML se encuentre dentro del directorio donde se desempaquetó DBTexMath. Entre otras cosas, el archivo Makefile contiene órdenes para generar los archivos de salida y cuenta con que nuestro documento se encuentra en su mismo directorio. En realidad, para los que están acostumbrados a programar, la tarea de formatear pasa a ser similar a compilar el programa fuente. Si el usuario conoce la herramienta make, teniendo en cuenta el esquema Figura 1 le será trivial comprender el funcionamiento de DBTexMath observando el archivo Makefile.
Queremos que este nuevo documento sea un artículo. Supondremos que nuestra versión de la DTD DocBook es 4.2[2]. La declaración SGML de tipo de documento será la que estamos acostumbrados a usar, o sea:
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
Importante: Si su versión de la DTD DocBook es otra, debería modificar las líneas anteriores cambiando el "4.2" por alguna otra cosa.
Nota: El formateo de nuestro archivo probe.sgml no será tan sencillo como al que estamos acostumbrados hasta ahora. Es decir, para, por ejemplo, obtener una salida PDF no bastará con sólo una simple orden 'db2pdf probe.sgml o docbook2pdf probe.sgml. En realidad, tanto db2pdf y docbook2pdf son scripts shell que hacen automáticamente los procesos que se describen en Figura 1. Para obtener una salida en otro formato, de deberán ejecutar varias órdenes. Pero no nos asustemos: de todo eso se encargará la herramienta make y el archivo Makefile que debe haber venido con el paquete DBTexMath. Si se lo examina, se puede ver en él el orden de los eventos y dependencias para obtener tanto las salidas PDF como HTML.
El siguiente paso a seguir es modificar la variable DOC del archivo Makefile por el nombre de nuestro documento sin la extensión ".sgml". En nuestro caso DOC = probe. Aunque no en la mayoría de los casos, puede ocurrir que debamos cambiar algunas de las demás variables del Makefile según la configuración de nuestro sistema.
Una vez hecho esto, se debe proceder a verificar que las rutas locales que aparecen en el archivo sample-both.dsl sean las correctas para nuestro sistema. Este es el paso más delicado: la hoja de estilo DSSSL sample-both.dsl debe tener acceso a las hojas de estilo dsssl de DocBook para que puedan, de alguna manera, trabajar juntas y junto con jade sobre nuestro archivo.
Sugerencia: En la mayoría de las distribuciones GNU/Linux, las hojas de estilo DSSSL se encuentran en /usr/share/sgml/DocBook/dsssl*, aunque esto no tendría porqué ser así en todos los sistemas. En mi cajita Linux, la hoja de estilo que uso es /usr/share/sgml/docbook/dsssl-stylesheets-cygnus/stylesheets/cygnus-both.dsl.. Probablemente, si hacemos cat `which db2html` | grep DB_STYLESHEET o cat `which docbook2html` | grep DB_STYLESHEET aparezcan rutas a las hojas de estilo que utilizan nuestro paquete DocBook-tools, las cuales, si tenemos bien configurado nuestro sistema, deberían ser las correctas.
Si hemos hemos hecho todo correctamente, ya deberíamos ser capaces de usar DBTeXMath. Esto se discute en la sección de nombre Obtención de salidas en formatos HTML y PDF.
El paquete que contiene el software DBTeXMath junto con la hoja de estilo ldp.dsl se puede obtener de http://www.geocities.com/cancerbero_sgx/dbtexmath_ldp.dsl.tar.gz .
A diferencia del paquete original, si usamos este paquete, no será necesario insertar las rutas a las hojas de estilo locales de Docbook. El método de puesta en funcionamiento del software DBTeXMath será el mismo que el anterior, pero omitiendo el paso 4. Esto hace que el uso del software DBTeXMath sea casi inmediato. El único requisito necesario para que funcione será modificar en el Makefile la variable DOC como ya se indicó.
A diferencia del paquete original, si usamos una estrategia en cuanto a las hojas de estilo como la ofrecida en tldp.org/authors/ldp.dsl, no será necesario insertar las rutas a las hojas de estilo locales de Docbook. El método de puesta en funcionamiento del software DBTeXMath será el mismo que el anterior, pero omitiendo el paso 4. Esto hace que el uso del software DBTeXMath sea casi inmediato. el único requisito necesario para que funcione será modificar en el Makefile la variable DOC como ya se indicó.
| [1] | Esta es la hoja de estilo del Proyecto de documentación de Linux (The Linux Documentation Project, TLDP), modificada por Jaime Davila. |
| [2] | La última versión estable de la DTD Docbook al momento de escribirse este documento. |