
This is a set of customizations to render real-world mathematics 
in HTML using CSS, DocBook, XSLT and dvi2bitmap.

---------------------- Usage ----------------------------

In principle just add the following to your HTML target XSLT 
customisation file 

<xsl:import href="./latex-math/xsl/latex-math.xsl"/>

---------------------- Basics ----------------------------

The basic idea is that using the alt element we can autogenerate
the equation label and an associated image filename. 
Then we source that image from the resultant html.

So some simple inline math would be:

<inlineequation><alt role="tex">\(F^2_{\rm{calc}}\)</alt></inlineequation>


An informalequation would be:

<informalequation><alt role="tex">\[
     e = m c^{2}
     \]
    </alt></informalequation>

and a labeled equation could have

<equation><alt role="tex">\[
     e = m c^{2}
     \]
    </alt></equation

- where the formal equation label/number is autogenerated according 
to its sequence in the chapter, appendix or document. 

The equations are written out into two separate files:

The first is tex-math-inlines.tex which you should process as:

        latex tex-math-inlines.tex
        ${DVI2BITMAP} ${DVIOPT} --verbose=quiet --query=bitmaps tex-math-inlines | \
        awk '{printf "img[src=\"%s\"] {margin-bottom:%dpx;}\n",$$2,$$6-$$4}' > \
        inline-equations.css

That creates a CSS customization file for adjusting the vertical 
alignment of the bitmap images within a line of text. 
You need to reference that in your HTML target file.



The second file produced is tex-math-equations.tex 
which contains both formal and informal equation blocks.

        latex tex-math-equations.tex
        ${DVI2BITMAP} ${DVIOPT}  tex-math-equations

Because equations are document divisions, there is not so much need to
fiddle with the vertical alignment.

----------------------  Aligning ----------------------------

As an extension to the above, sometimes it is useful to 
preserve the alignment of equations across intermediate text chunks. 
To do that you use the LaTeX align* environment to insert 
alignment markers "&amp;" and then split the equation by 
simulating page breaks as:

<informalequation role="cont"><alt role="tex">\begin{align*}
     e &amp;= \sqrt{p^2 c^2 + m^2 c^{4} }
    </alt></informalequation>

with some intermediate text before the final labeled result
to the effect that when the momentum 
<inlineequation><alt role="tex">\(p=0\)</alt></inlineequation>

<equation role="terminal"><alt role="tex">\
     e &amp;= m c^{2}
    \end{align*}
 </alt></informalequation>


------------------------ Cross References ------------------------

To reference an equation you need to give it a unique id (unique across the whole 
document) like this:

<equation  id="mass-equiv"><alt role="tex">\
     e &amp;= m c^{2}
    \end{align*}
 </alt></informalequation>

Then you reference it in the body text as 
... according to Einstein's mass-energy equivalance 
formula <xref linkend="mass-equiv"/>  ...

Then you need to modify the docbook common/en.xsl template file to 
specify how those <xref> elements should be treated.
Typically look for  "equation"  and replace "%t" with "(%n)" 
in a few different locations ...

The results *should be*    
... according to Einstein's mass-energy equivalance formula (1.1)  ...

----------------------- Short hand -------------------

If you don't mind preprocessing your xml,
you can say, use some dummy entities to substitute for 
some of the surrounding elements. Then perl substitute them 
before XSLT processing or validating.

------------------ Coherent Math Markup --------------

It would be useful to adopt some sensible structuring conventions
in your math markup so that conceivably, the raw tex could be parsed and 
machine *understood*, rather than parsed just for people to understand.  

Conceivably that could interface to the OpenMath effort in some way.

To that end it is useful to define standard operators
rather than the more obscure symbols that are used to represent them.
Some examples are shown in custom-math.xsl
which you would include verbatim in your customization file
