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>[email protected]</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>[email protected]</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.