Introducción

Se supone que el usuario que esté leyendo este documento ya está convencido de que la herramienta definitiva para la edición estructurada de textos es Docbook. Si no es así o el lector no conoce aún lo que es DocBook le recomendamos que empiece a aprender qué es y cómo usarlo, si es que se dedica a realizar documentos electrónicos. Las aplicaciones como Microsoft Word y similares ya tuvieron su lugar en la historia y deben aceptar su lugar real en el mundo: un primer contacto de gente principiante con el mundo de la informática, pero nada más. Si piensa realizar ediciones serias en su computadora, deberá estar al tanto de las nuevas tecnologías como DocBook.

La conveniencia de la edición de documentación en un formato estructurado como DocBook es indiscutible. Esta herramienta junto con emacs y su modo mayor PSGML[1]nos permiten hacer documentos rápidamente y de una forma totalmente distinta a la de las herramientas de tipo WYSIWYG[2], sin tener que preocuparnos por el diseño y la estética del documento y sólo por su contenido y estructura.

DocBook no es la única herramienta para UNIX de su tipo: hay otras más antiguas y hasta más maduras como TeX[3], LaTeX[4] o troff. Sin embargo, ya sea por la posibilidad de realizar salidas de documentos en una gran variedad de formatos, ya sea orientados a la impresión como PDF, PostScript, DVI o RTF, como orientados para la Internet como HTML, ya sea por el alto grado de aceptación que está teniendo DocBook tanto en el mundo del software libre, como en universidades, empresas privadas, etcétera es, hoy en día la mejor herramienta para la edición de documentación.

¿Por qué DBTexMath?

Aunque DBTexMath no es la única alternativa para la representación de expresiones matemáticas en documentos Docbook, en esta sección se explicará el porqué de su elección.

Para los que aún no han intentado escribir documentos DocBook que involucren expresiones matemáticas complejas tal vez les sorprenda el hecho de que DocBook no provee herramientas estándar para tal actividad.

En realidad, la alternativa propuesta (aunque no formalmente) por OASIS consortium[5] es MathML [6]. Sin embargo, según mi parecer, todavía no se habla de una herramienta estándar que venga dentro de la DTD para la representación de expresiones matemáticas. En efecto, hay varias formas de hacer esto como es descrito en http://www.sagehill.net/docbookxsl/Math.html. El uso de MathML tiene dos grandes inconvenientes:

• Dificultad para escribir directamente en lenguaje MathML. Si queremos escribir expresiones matemáticas moderadamente complejas directamente en MathML (por ejemplo en un editor de textos como emacs), nos resultará casi imposible hacerlo ya que es una tarea muy complicada. La única alternativa posible es escribir nuestras expresiones matemáticas en algún editor de ecuaciones con interfaz gráfica. Pero aquí surgen nuevamente los problemas. Primero, obtener software libre de estas características es muy complicado. Desde el punto de vista de muchos la única herramienta libre que cumple con estos requisitos es la aplicación experimental Amaya. Y el segundo problema que se presenta es que aunque existiera, depender de una tal herramienta ya no sería lo que, por ejemplo yo, pretendo de la edición estructurada de textos. Estaría orientando mi metodología a la técnica WYSIWYG, lo cual tiene, en lo personal, sus desventajas.

• La salida de expresiones MathML no siempre es correcta. . Las hojas de estilo DSSSL que hacen, junto con jade la transición de MathML a TeX son experimentales y su trabajo fue discontinuado hace unos años[7]. La salida TeX de las expresiones MathML es confusa, poco prolija y algunas expresiones son totalmente ignoradas como por ejemplo la barra superior del promedio estadístico (). También se pueden ver ciertas diferencias (errores) en expresiones matemáticas relativamente complejas.

Para Allin Cottrell, estos dos problemas fueron lo suficiente importantes como para buscar o crear otra alternativa. El resultado fue su proyecto DBTexMath.

Hasta aquí todo muy bien pero, hasta ahora no hemos contestado la pregunta a la que hace referencia el título de esta sección. ¿Por qué usar DBTexMath en lugar de, por ejemplo, MathML?

Primero que nada, MathML y DBTeXMath parecen ser las dos únicas herramientas para auxiliar a DocBook en la edición matemática. Si algún usuario encuentra otra le agradezco que me lo comunique. Segundo, hemos visto las deficiencias de la edición directa de código MathML dentro de nuestros documentos DocBook. Y tercero, podemos decir que la edición de expresiones matemáticas en el lenguaje TeX es casi perfecta. Con unas pocas líneas se pueden crear expresiones que, en otra clase de lenguajes para los mismos propósitos serían muy complejas. Una prueba de ello es que proyectos orientados a las ciencias (como por ejemplo GSL, la librería para propósitos científicos de GNU) utilizan en su documentación de sólo texto (páginas manual o info) el lenguaje TeX para representar expresiones matemáticas complejas. Esto da una idea de lo práctico que es TeX y del gran uso que se le da. Un ejemplo de la facilidad de la conveniencia de su uso para representar expresiones matemáticas es el siguiente. La cadena

	x_j = \sum_{k=0}^{N-1} z_k e^{ -2\pi i j k / N }
      

Breve explicativo sobre el funcionamiento y terminología de DocBook.

Esta sección está dedicada sólo para aquellas personas nuevas en la composición tipográfica de documentos utilizando DocBook. Dado que el funcionamiento de la herramienta DBTexMath está muy relacionado con los procesos de composición y publicación de los documentos DocBook, nos parece que el lector merece el contenido de esta sección. Así, llegado el punto, no estará obligado a manejarse sólo con terminología vacía, sino que podrá entender, o al menos hacerse una idea de, de qué se habla. Así es como aquel lector que no esté interesado en estos aspectos bien puede saltear el contenido de esta sección.

A continuación se muestran dos breves esquemas de los procesos por los que pasan los archivos fuentes DocBook SGML y XML, respectivamente, para llegar a formatos de salida como PDF, HTML, PostScript, etc.

Puede decirse que el formato DocBook fue creado gracias a los meta-lenguajes de etiquetas SGML y XML[8]. ¿Qué es un meta lenguaje? Son básicamente lenguajes para la creación de otros lenguajes. Tanto en el caso de SGML o XML, estos se basan en el uso de la etiqueta. Una etiqueta es todo aquel conjunto de caracteres encerrado entre los símbolos < y >. En el caso de SGML, este lenguaje sólo define reglas básicas sobre el uso y anidación de etiquetas. Por ejemplo, se encuentra explícito en el lenguaje que cada etiqueta debe tener una etiqueta de final correspondiente y que la anidación de etiquetas debe ser perfecta, lo que significa que las etiquetas internas deben ser cerradas antes de las etiquetas externas. Por supuesto, las definiciones SGML son mucho más complejas que esto, pero básicamente esas son las reglas principales.

Dadas estas reglas básicas, todo lo demás se deja a discreción de quien programa en el meta lenguaje. Este tendrá que crear los nombres para las etiquetas, sus parámetros y las reglas específicas de anidación de estas etiquetas (i.e qué etiqueta puede estar dentro de qué otra).

DTD son las siglas de "(Document Type Definition", o en español "Definición del Tipo de Documento".

Como hasta ahora hemos venido haciendo, nos sentimos obligados a explicar qué es una hoja de estilo DSSSL (o en inglés DSSSL stylesheet) de las cuales se hablará a lo largo de este documento.

En ningún momento la DTD define qué fuentes, qué espaciado entre párrafos, alineación, etc se usará. Es decir, no hay ninguna información sobre el estilo que se usará para publicar el documento DocBook en una DTD. Tan sólo existen definiciones de etiquetas, y reglas de anidación.

Es aquí dónde entran en juego las hojas de estilo. Éstas, son simples archivos que definen el estilo de la publicación del documento. Es decir, entre otras cosas definen, para cada formato de salida, la fuente y su tamaño utilizada para cada parte del documento, la alineación del mismo en la hoja, el espaciado entre párrafos, la distribución de secciones como el índice, la bibliografía, los apéndices, los pies de nota, etc.

Durante años se ha intentado producir un lenguaje estándar para realizar hojas de estilo. Entre otros se pueden destacar FOSIs[9], DSSSL[10] (lenguaje soportado por Jade, openJade y otras), CSS [11] y XSL[12]. Cabe destacar que el lenguaje DSSSL es parecido a los lenguajes de programación tipo lisp o Scheme, y el lenguaje para hojas de estilo XSL es el mismo lenguaje XML.

En nuestro caso, supondremos que el usuario usa un sistema DocBook basado en SGML y no en XML y que el lenguaje utilizado para sus hojas de estilo es DSSSL. En este caso, el último paso de la publicación de documentos es utilizar una herramienta como Jade o openJade, que interpreta el lenguaje DSSSL de la hoja de estilo y toma como entrada un documento SGML. Si le indicamos el tipo de salida deseado, esta herramienta nos lo proporcionará.

Para usuarios con experiencia en programar con lenguajes como C, el proceso de composición y publicación tipográfica puede parecer análogo al de programar. Nuestro documento *.sgml sería nuestro código fuente C, la DTD sería lo análogo al lenguaje C (las reglas de sintaxis que se deben respetar para que el documento-programa sea válido y que describen cada etiqueta-estructura) y las hojas de estilo junto con las herramientas de publicación como Jade, openJade, JadeTeX podrían verse como el compilador C. Cualquiera de las salidas ya sean PDF, HTML, RTF, etc podrían ser vistas como el archivo ejecutable compilado.

A continuación expondremos otro esquema más, visto desde el punto de vista de los lenguajes y no de los procesos que intervienen en la composición y publicación de un documento DocBook.

Uso de DBTexMath

En esta sección se explicará cómo insertar expresiones matemáticas TeX dentro de nuestros documentos DocBook. En Apéndice A se discutirá la sintaxis TeX para crear este tipo de cosas.

Para que DBTexMath pueda formatear nuestras fórmulas matemáticas, debemos incluirlas dentro de alguna de las etiquetas <equation>, <informalequation> o <inlineequation>. La etiqueta <equation> hace que nuestra expresión matemática se represente en una nueva línea de texto, y con un título propio. <informalequation> es igual que <equation> pero sin título. <inlineequation> sin embargo, hace que la expresión matemática aparezca en la misma línea de texto. Por ejemplo, a pesar de que podemos escribir letras griegas y otros símbolos matemáticos usando entidades o codificaciones ("encoding") distintas en Docbook, el uso de <inlineequation> es muy práctico para tal propósito dentro de un párrafo. La sintaxis básica es:

<equation>                                                 
  <alt> "Expresión matemática TeX" </alt>                  
  <graphic fileref="nombre-de-archivo.png">                
</equation>
      

A continuación brindamos un ejemplo de las aplicaciones más comunes de esta sintaxis.

 <para> La ecuación
  
    <informalequation>
      <alt>$ r=a+b\theta $</alt>
      <graphic fileref="ecuacion_espiral.png">
    </informalequation>
  
  representa una espiral, donde 
    
    <inlineequation>
      <alt>$ a, b, \in \Re $</alt>
      <graphic fileref="espira_condicion_1.png">
    </inlineequation>

  y 
    
    <inlineequation>
      <alt>$ r, \theta $</alt>
      <graphic fileref="theta.png">
    </inlineequation>
      
  se refieren a las coordenadas polares. 

</para>

Salida del ejemplo La ecuación representa una espiral, donde y r, se refieren a las coordenadas polares.

¿Cómo funciona DBTexMath?

Ahora que conocemos algo del proceso de composición y publicación de documentos DocBook, pasaremos a explicar cómo encaja DBTexMath en todo esto.

DBTexMath podría describirse como un conjunto de archivos que permiten al usuario embeber sus expresiones matemáticas en formato TeX dentro del mismo documento sgml-DocBook. Básicamente estos archivos forman una hoja de estilo DSSSL que complementa la hoja de estilo DSSSL de nuestro paquete DocBook local. Funcionan de la siguiente manera: El usuario escribe sus expresiones matemáticas en formato puro TeX dentro de una etiqueta <alt> dentro de cualquiera de las etiquetas <equation>, <informalequation>, <inlineequation>, tal como ya se ha explicado en la sección de nombre Uso de DBTexMath, dentro del documento SGML.

El proceso de publicación por parte de DBTexMath será distinto según el formato sea orientado a la impresión (PDF, PostScript), o a Internet (HTML):

• Orientado a la impresión. En el caso de que se desee una salida orientada a la impresión como PDF o PostScript, el archivo *.sgml se traduce en *.tex a través de alguna herramienta como Jade u openJade. Hasta ese punto el proceso de publicación es igual al estándar. Sin embargo, el siguiente paso es pasar el archivo TeX a través del filtro Perl unescape_math.pl, el cual lo que hace es obtener las expresiones TeX de las etiquetas <alt> para que estas puedan ser evaluadas por JadeTex (programa que traduce estos archivos TeX en DVI, PostScript y PDF).

• Orientada a la Internet. En el caso de que se desee una salida orientada a la Internet (formato HTML) el proceso es llevado a cabo del siguiente modo. Un script Perl llamado texmath2png.pl traduce las expresiones TeX dentro de las etiquetas <alt> (que deben estar en modo matemático) a imágenes PNG. Para cada ocurrencia matemática TeX dentro de nuestro documento DocBook se muestra la imagen PNG respectiva en el documento salida HTML.

En realidad el proceso no es tan simple como esto, pero según nuestra opinión, no hace falta saber los detalles exactos para poder insertar nuestras fórmulas en DocBook.

Obtención e instalación de DBTexMath

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[13] 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.

Obtención de salidas en formatos HTML y PDF

Si hemos hecho todo bien en la sección anterior, y si nuestro archivo probe.sgml no tiene errores (tanto de síntaxis sgml-DocBook como en las expresiones matemáticas en TeX), podremos formatear nuestro archivo probe.sgml a HTML simplemente escribiendo make html (salida que quedará en el subdirectorio, html_out) o make htmls (salida que quedará en el subdirectorio, htmls_out y que tendrá diversos archivos html) . De manera análoga, podremos obtener una salida de este documento en formato PDF, escribiendo make pdf. Si queremos publicar el documento en ambos formatos, podremos hacerlo simplemente escribiendo make.

A modo de prueba, ofrezco un archivo probe.sgml, sin errores:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN">

<article>

  <articleinfo>
    <title>Prueba de DBTexMath en DocBook</title>
    <author>
      <firstname>Sebastián</firstname>
      <surname>Gurin</surname>
      <email>cancerbero_sgx@users.sourceforge.net</email>
    </author>
  </articleinfo>

  <section>
    <title>Matrices</title>

    <para>A continuación va un ejemplo de la representación de
    expresiones matemáticas que involucran matrices.</para>

    <informalequation>
      <alt>
\renewcommand{\arraystretch}{1.3}
\setlength{\arraycolsep}{.05in}
\[
\left[
\begin{array}{c}
\dot{L} \\
\dot{C}
\end{array}
\right]
= \frac{1}{-\alpha}
\left[
\begin{array}{cc}
af & bfh \\
1 & b(fh-k)
\end{array}
\right]
\left[
\begin{array}{c}
L \\
C 
\end{array}
\right]
-\frac{1}{\alpha}
\left[
\begin{array}{cc}
afh & 0 \\
h & \alpha 
\end{array}
\right]
\left[
\begin{array}{c}
\dot{m} \\
r_w
\end{array}
\right]
\]


      </alt>
      <graphic fileref="matriz_mult.png" align="center">
    </informalequation>

  </section>
</article>

Consejos

Considero que lyx puede resultar de ayuda para muchos usuarios. Si por falta de tiempo no se puede aprender estrictamente la sintaxis TeX, se puede usar lyx y su panel para la edición de fórmulas matemáticas para escribir la expresión deseada. Todo esto es de un modo WYSIWYG, por lo que no debe resultar difícil a cualquier usuario. Luego, se podrá exportar el documento a formato LaTeX, abrirlo en un editor de textos y pegar nuestra expresión dentro de nuestro documento DocBook. Este procedimiento también se puede usar cuando no nos acordamos de memoria ciertos comandos, letras griegas, o para construcciones complejas como matrices, etc.

Un buen tutorial de Lyx y SGML se encuentra en www.karakas-online.de/mySGML

Tener en cuenta que para exportar el documento lyx a LaTeX, dentro de lyx se deberá ir al menú Archivo->Exportar->Latex

Depende de cada uno hasta qué punto utilizar este tipo de herramientas para editar estructuradamente, algo que sólo se debería hacer en un editor de textos como emacs. Personalmente pienso que si esto agiliza nuestra tarea (no nos distrae y no nos hace pensar en el diseño más que en el contenido), entonces está bien usarlo.

(define $usepackage$
  "X")
	  

\usepackage{X}
	

No todo es color de rosas...

Primero que nada, cabe decir que el paquete DBTexMath fue realizado voluntariamente y para uso personal del autor. Así, no fue diseñado ni planeado para cumplir con todas los requisitos que puedan surgir entre los usuarios.

A continuación enumero características que en lo personal faltarían, como también malos funcionamientos del programa. Agradecería las sugerencias de aquellos usuarios que han logrado solucionar los problemas-carencias que aquí se plantean.

• Estandarización. Como ya se dijo, no existe un paquete estándar, dentro del mundo Docbook para la edición de fórmulas matemáticas. Es por esto, que en cada uno de nuestros documentos DocBook que utilicen DBTeXMath deberemos incluir las hojas de estilo en la distribución de nuestros documentos o por lo menos hacer referencia a estas.

  El hecho no esta grave dado el tamaño pequeño de las hojas de estilo. Sin embargo, el proceso de obtención de salidas en formatos tales como PDF o HTML por parte de otros usuarios no será tan tribal como ejecutar una orden. Como mucho, lo que podremos hacer para remediar esta situación es usar DBTexMath junto con la hoja de estilo ldp.dsl (ver la sección de nombre Instalación de DBTeXMath junto con ldp.dsl), con lo cual, la configuración constará únicamente en cambiar el nombre de la variable DOC en el archivo Makefile.

• No hay salida en formato RTF. Como ya se discutió en la sección de nombre Obtención de salidas en formatos HTML y PDF, no existe una forma directa de obtener salidas en formato RTF. Esto debe ser consecuencia de la complejidad sintáctica del formato RTF. Nótese que las salidas PDFs derivan de TeX (JadeTeX), por lo que se aprovecha esta característica para pasar las fórmulas matemáticas en TeX directamente. En el caso de HTML, una de las características que se aprovechan es el hecho de que HTML sea un lenguaje de etiquetas derivado de SGML, lo que hace más fácil modificar la hoja de estilo para mostrar las fórmulas. En lo personal el no poder obtener salidas RTF no es una gran pérdida dado que no uso para nada este formato. Yo edito en sgml-DocBook, leo en PostScript o PDF y navego en HTML ;-).

• Incompatibilidades entre SGML/XML y TeX. Con algunos sistemas de edición de documentos Docbook tal como emacs con su modo PSGML, o algún otro sistema de indentación, puede suceder que el código TeX se indentado automáticamente, lo que puede generar errores de sintaxis. Esto en realidad no es realmente un error. Lo que sucede es que, simplemente, los sistemas de indentación de documentos Docbook, no fueron hechos pensando en software como DBTeXMath, o sea, no fueron diseñados para respetar otro código además que esté más allá de las DTDs.

  Sugerencia: Indentar expresiones latex que aparecen dentro de las etiquetas <alt> puede causar errores. No hacerlo!

• Problemas con símbolos LaTeX no estándares. 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 hagamos un make html . No tendremos estos problemas cuando tratemos de generar salidas en formato PDF.

  >Como ya se dijo, estos errores se producirán sólo si estamos usando el paquete original de DBTexMath de Allin Cottrell ya que los paquetes de símbolos latex fueron incluidos en la versión que viene con ldp.dsl.

• Lentitud. Dado que cada expresión matemática es evaluada por separado, si tenemos una gran cantidad de expresiones matemáticas insertadas en el documento el formateo puede volverse un proceso lento. La generación de salidas HTML es particularmente lenta dado que cada expresión matemática en código TeX, luego de haber sido convertida a DVI, se debe convertir nuevamente a formato de imagen PNG.

  Para aquel usuario experimentado, una alternativa que puede mejorar este problema es usar el software dvi2bitmap para la transformación a png. Esto es bien descripto en http://www.sagehill.net/.

• Errores como el siguiente. Aunque el código sgml-DocBook y el fragmento TeX sean válidos en el siguiente segmento de código, por algún motivo el uso de TeX dentro de la etiqueta <abstract> causa problemas lo siguiente no compila

  <article>
    <articleinfo>
      <date>24 de Marzo de 2004</date>
      <author>
        <firstname>Sebastián Gurin (Cancerbero)</firstname>
        <email>anon@adinet.com.uy</email>
      </author>
  
      <abstract>
        <para>Teorema auxiliar para deducir la ecuación de una
        curva en forma de espiral con centro en <inlineequation>
  	  <alt>$ (x_0, y_0) $</alt>
  	  <graphic fileref="punto.png">
  	</inlineequation>.</para>
      </abstract>
  
    </articleinfo>
  
  <!-- .... -->
  
  </article>
  	    

  No hemos podido averiguar cuál es la causa del error. Seguramente sea una excepción de las hojas de estilo de DBTeXMath.