Writing Mathematics

Writing LaTeX Mathematical Equations
Writing MathML equations

Writing LaTeX Mathematical Equations

Presentation

DocBook doesn't define elements for writing mathematical equations. Only few elements exist that tell how equation should be displayed (inlined, block):

  • inlineequation tells that the equation is inlined,

  • informalequation tells that the equation is displayed as a block, without a title.

  • equation tells that the equation is displayed as a block, with or without a title.

These tags include a graphic (graphic or mediaobject) or an alternative text equation, as shown by the example.

Example 3.5. Equation taken from TDG

<equation><title>Last Theorem of Fermat</title> 
  <alt>x^n + y^n &ne; z^n &forall; n &ne; 2</alt>
  <graphic fileref="figures/fermat"></graphic>
</equation>
   

Implementation choice

The principle is to use only the alt element. If initially alt contains actually the text to print, it is chosen to use this element to embed LaTeX mathematical equations. This choice has the following advantages:

  • The translation done by dblatex is really easy, since the equation is already written in LaTeX.

  • LaTeX is one of the best word processor to render mathematical formulas.

  • One doesn't need to write the equations in MathML.

  • This method isn't specific to this tool (see the following section).

Mathematical Delimiters

The dblatex implementation is as light as possible. This is why it is up to the writer to properly use the mathematical delimiters ($, \(, \), \[, \]). By this way the writer fully controls how he writes equations.

By default dblatex checks that consistent mathematical delimiters or environment are used in alt and it inserts the default math mode delimiters if dblatex thinks they are missing, but you can ask dblatex to write directly the alt content without any action. To do this, use the texmath Processing Instruction with delimiters set to 'user'.

For example, Example 3.6, “Equation with user delimiters” has user specific delimiters:

Example 3.6. Equation with user delimiters

Equation 3.1. Equation block with align tabs


In the XML source this equation uses a specific align* environment and the texmath PI to let the equation as is:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<equation>
  <title>Equation block with align tabs</title>
  <alt><?texmath delimiters="user"?><![CDATA[\begin{align*}
S & = \left\lfloor { { N \bmod 65536 } \over 32768 } \right\rfloor  \\
E & = \left\lfloor { { N \bmod 32768 } \over  1024 } \right\rfloor  \\
M & = N \bmod 1024.
\end{align*}]]></alt>
</equation>
 

Compatibility

This implementation is not contradictory nor specific. In particular, the DBTeXMath proposal to extend the DSSSL stylesheets used by jade follows the same approach, and is integrated in the Norman Walsh XSL stylesheets.

Examples

The following examples show how to write the equations.

Example 3.7. Inlined Equation

The formula is inlined in the paragraph. Its XML source is:

<para>The formula 
  <inlineequation id="eg-inlineequation">
    <alt>$C = \alpha + \beta Y^{\gamma} + \epsilon$</alt>
    <graphic fileref="figures/eq1"/>
  </inlineequation>
is inlined in the paragraph. Its XML source is:</para>


Example 3.8. Equation in a block

The following formula:

is displayed in a separate block. The XML source is:

<para>The following formula:
  <informalequation>
    <alt>\[C = \alpha + \beta Y^{\gamma} + \epsilon\]</alt>
    <graphic fileref="figures/eq1"/>
  </informalequation>
is displayed in a separate block. The XML source is:</para>


Example 3.9. Equation in a float

The formula Equation 3.2, “Simple Formula” below:

Equation 3.2. Simple Formula


is displayed in a block with a title. Its XML source is:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<para>The formula <xref linkend="eq-with-title"/> below:
  <equation id="eq-with-title">
  <title>Simple Formula</title>
    <alt>\[C = \alpha + \beta Y^{\gamma} + \epsilon\]</alt>
    <graphic fileref="figures/eq1"/>
  </equation>
is displayed in a block with a title. Its XML source is:</para>


Example 3.10. Equation without a title

The formula Equation 3.3 below:

Equation 3.3. 


is displayed as a latex equation with its own equation numbering. Its XML source is:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<para>The formula <xref linkend="eq-with-no-title"/> below:
  <equation id="eq-with-no-title">
    <alt>C = \alpha + \beta Y^{\gamma} + \epsilon</alt>
    <graphic fileref="figures/eq4"/>
  </equation>
is displayed as a latex equation with its own equation numbering.
Its XML source is:</para>


Writing MathML equations

You can write MathML equations in a DocBook based document, by using the MathML Module for DocBook XML instead of the DocBook DTD.

dblatex now translates the MathML equations to latex by using the excellent stylesheets of the XSLT MathML Library by Vasil Yaroshevich. A large amount of tests from the W3C MathML Test Suite 2.0 is supported (657 of 712 tests). The test file used to validate the MathML stylesheets is provided in the package.