"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>

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

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

            parse="text"/> </programlisting>

</example>

</section>

<section>

<title>Compatibility</title>

<para>This implementation is not contradictory nor specific. In particular,

the 

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>

            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>

            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>

            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>

            parse="text"/>

</programlisting>

</example>

</section>

</section>