Writing Mathematics
Prev | Chapter 3. Using dblatex | Next

## Writing Mathematics

### 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.

Prev | Up | Next
Correcting Poor Formatting | Home | Musical Notation