<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<section output="manual">
<title>Writing LaTeX Mathematical Equations</title>

<section>
<title>Presentation</title>

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

<itemizedlist>
<listitem>
<para><sgmltag>inlineequation</sgmltag> tells that the equation is
inlined,</para>
</listitem>

<listitem>
<para><sgmltag>informalequation</sgmltag> tells that the equation is displayed
as a block, without a title.</para>
</listitem>

<listitem>
<para><sgmltag>equation</sgmltag> tells that the equation is displayed as a
block, with or without a title.</para>
</listitem>
</itemizedlist>

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

<example>
<title>Equation taken from TDG</title>

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

<section>
<title>Implementation choice</title>

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

<itemizedlist>
<listitem>
<para>The translation done by dblatex is really easy, since the equation is
already written in LaTeX.</para>
</listitem>

<listitem>
<para>LaTeX is one of the best word processor to render mathematical
formulas.</para>
</listitem>

<listitem>
<para>One doesn't need to write the equations in MathML.</para>
</listitem>

<listitem>
<para>This method isn't specific to this tool (see the following
section).</para>
</listitem>
</itemizedlist>

</section>

<section id="sec-alttex-delimiters">
<title>Mathematical Delimiters</title>

<para>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.</para>

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

<para>For example, <xref linkend="eq-with-texmath-pi"/> has user specific
delimiters:</para>

<example id="eq-with-texmath-pi">
<title>Equation with user delimiters</title>
<xi:include href="equation-eg5.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<para>In the XML source this equation uses a specific <literal>align*</literal> environment and the <literal>texmath</literal> PI to let the equation as is:</para>
<programlisting>
<xi:include href="equation-eg5.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
            parse="text"/> </programlisting>
</example>

</section>

<section>
<title>Compatibility</title>

<para>This implementation is not contradictory nor specific. In particular,
the <ulink
url="http://ricardo.ecn.wfu.edu/~cottrell/dbtexmath/">DBTeXMath</ulink>
proposal to extend the DSSSL stylesheets used by jade follows the same
approach, and is integrated in the Norman Walsh XSL stylesheets.</para>
</section>

<section>
<title>Examples</title>

<para>The following examples show how to write the equations.</para>

<example>
<title>Inlined Equation</title>

<xi:include href="equation-eg1.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>

<programlisting>
<xi:include href="equation-eg1.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
            parse="text"/>
</programlisting>
</example>

<example>
<title>Equation in a block</title>

<xi:include href="equation-eg2.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>

<programlisting>
<xi:include href="equation-eg2.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
            parse="text"/>
</programlisting>
</example>

<example>
<title>Equation in a float</title>

<xi:include href="equation-eg3.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>

<programlisting>
<xi:include href="equation-eg3.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
            parse="text"/>
</programlisting>
</example>

<example>
<title>Equation without a title</title>

<xi:include href="equation-eg4.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>

<programlisting>
<xi:include href="equation-eg4.xml" xmlns:xi="http://www.w3.org/2001/XInclude"
            parse="text"/>
</programlisting>
</example>
</section>
</section>