DBTeXMath

DBTeXMath
	Chapter 21. Math

DBTeXMath is a method for using TeX to typeset mathematics in DocBook FO. The typesetting language TeX has a fine reputation for producing beautifully typeset mathematics. For that reason, TeX is familiar to many mathematicians who write for publication. If you are using an XSL-FO processor that employs TeX as its typesetting engine, such as PassiveTeX, then you can use DBTeXMath.

DBTeXMath was originally written for the DocBook DSSSL stylesheets, and was described in DBTeXMath by Allin Cottrell. It was adapted to the DocBook XSL stylesheets by Jirka Kosek for use with PassiveTeX. Instead of using the alt element, the preferred method in DocBook XSL is to use a textobject with a role="tex" attribute.

The following is an example of using DBTeXMath:

Example 21.1. DBTeXMath using textobject

<equation>
  <title>A TeX Equation</title>
  <mediaobject>
    <imageobject role="html">
      <imagedata fileref="texmath.png" format="PNG"/>
    </imageobject>
    <textobject role="tex"><phrase>$C = \alpha + \beta Y^{\gamma} 
    + \epsilon$</phrase></textobject>
  </mediaobject>
</equation>

The TeX code is in a phrase element inside the textobject. Be sure to include the role="tex" attribute. This example also includes an alternate imageobject with role="html" so the math can also be displayed in HTML output as a bitmap file. The bitmap can be generated from the TeX, as described in the section “Bitmap versions for HTML”. For accessibility for the visually impaired, you should also include a plain text description of the equation in another textobject (without the role="tex" attribute), such as the following:

<textobject><phrase>C = alpha + beta times Y^gamma 
+ epsilon</phrase></textobject>

To enable DBTeXMath processing, you need to set two FO stylesheet parameters :

tex.math.in.alt="latex"
passivetex.extensions="1"

The tex.math.in.alt parameter turns on the DBTeXMath feature. Its value can be either latex if your TeX is written using LaTeX, or plain if your TeX is written in plain TeX. You can't mix both in one document. The passivetex.extensions parameter turns on other PassiveTeX features but must also be set for this feature. The FO stylesheet will then pass the TeX code through to the FO file wrapped in special processing instructions that PassiveTeX will handle.

Bitmap versions for HTML

As an added bonus, you can generate bitmap versions of your TeX math for use in HTML output. Here is how you do it. When you process your file with one of the DocBook HTML stylesheets,

For each equation, add an imageobject to the equation's mediaobject container. The imagedata should name the graphic image file you want to generate:

<equation>
  <title>A TeX Equation</title>
  <mediaobject>
    <imageobject role="html">
      <imagedata fileref="texmath.png" format="PNG"/>
    </imageobject>
    <textobject role="tex"><phrase>$C = \alpha + \beta Y^{\gamma} 
    + \epsilon$</phrase></textobject>
  </mediaobject>
</equation>

The texmath.png file will be created in subsequent steps. Be sure to give all the files different names so they don't overwrite each other.

Process your DocBook file once with an HTML stylesheet with the same DBTeXMath parameters set. The image files will be missing at this point. But as a side effect, it will write the TeX code out to a separate file. By default the file is named tex-math-equations.tex, but it can be renamed with the tex.math.file stylesheet parameter.
Process the tex-math-equations.tex file with your TeX processor. If you specified the value of the tex.math.in.alt stylesheet parameter as plain, then use the tex command. If you specified the parameter as latex, then use the latex command. Either command will generate a .dvi file.
Process the .dvi file with the dvi2bitmap command. The dvi2bitmap program is available from http://www.astro.gla.ac.uk/users/norman/star/dvi2bitmap/. It will generate one bitmap image file for each equation in the document. The files will be named according to the imagedata names assigned in your document.
When you process your DocBook file again with an HTML stylesheet, the bitmap images of your TeX equations will be included in the output.

Creating these bitmap images from the TeX code requires an extra step. That step must be repeated whenever the TeX code changes, but not every time the document is processed.


SVG math		MathML