[docbook-apps] Mathematics and DocBook

["Kevin S. Van Horn" <kvanhorn at ksvanhorn dot com>]

I'm getting ready to write documentation for some mathematical software, 
and so I've been looking into how to put mathematics into DocBook 
documents.  (I'm new to DocBook.) What I've found so far has been very 
disheartening, as the options are either inadequate to produce nicely 
typeset mathematics, or are excruciatingly painful to use.  These 
options are given in Bob Stayton's book, _DocBook XSL: The Complete Guide_:

1. Plain text math.  You can't get nicely typeset mathematics this way, 
and there are some things you can't express at all (at least not with 
xmlto), due to character entities that don't display correctly.  It's 
also very painful to use:  Stayton's book gives the following VERY 
verbose example for a six-character expression:

 <inlineequation>
   <inlinemediaobject>
     <textobject>
       <phrase>&Psi;(n,k)</phrase>
     </textobject>
   </inlinemediaobject>
 </inlineequation>

Not only is this a lot of effort to type, it's also unreadable when you 
are editing the source XML file.  It gets really bad if you have a lot 
of small snippets of inline math within one's texts, such as references 
to mathematical variables -- the scaffolding outweighs the content by 
TWO orders of magnitude!  This wouldn't be so bad if there were some way 
of defining a macro for all of the wrapping tags -- either a single 
macro taking a parameter which is the math content, or two macros for 
the prelude and postlude -- but there doesn't seem to be any way of 
doing this in  DocBook.

2. Graphic math.  This has all the disadvantages of (1) except for lack 
of nice typesetting, with the added disadvantages that one needs to 
write an additional, separate file for every tiny bit of math, and the 
math is completely unreadable (not even in the same file) when editing 
the source XML file.

3. DBTeXMath.  You can produce nicely typeset math this way, but you 
still have the problem of excruciatingly verbose input for the simplest 
thing.  For example, just to reference a mathematical variable N I have 
to write
 <inlineequation>
   <inlinemediaobject>
     <imageobject role="html">
       <imagedata fileref="texmath1.png" format="PNG"/>
     </imageobject>
     <textobject role="tex"><phrase>$N$</phrase></textobject>
   </inlinemediaobject>
 </inlineequation>

4. MathML.  This is just hopelessly verbose, and the source for your 
math is not easily readable.

Are there any better solutions?  Am I going to have to learn how to 
extend the DocBook DTD and modify the stylesheets to get a reasonable 
solution?  Surely I'm not the first person to run into this problem...




---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org