Using macros

[Definition: A macro is an XML-tag that is not in MathDox, but that can be transformed into MathDox]. An example of a macro could be using p instead of para or iv for an OMOBJ containing an OMV.

Example 1. A first example with macros

Using these example macros,

          
  <p>
    Let <iv>n</iv> be a positive integer.
  </p>

would then be short for

          
  <para>
    Let <OMOBJ><OMV name="n"/></OMOBJ> be a positive integer.
  </para>

which, when displayed looks like:

Let n be a positive integer.

Macros can be abbreviations for longer tags or constructs. An example is a maxima, which could be an abbreviation for a longer MONET-query which calls Maxima with some options, see also the following example.

Example 2. A more complicated macro example: maxima

Using this example macro,

          
  <para>
    The sum of 
    <OMOBJ>
      <OMI>1</OMI>
    </OMOBJ> and 
    <OMOBJ>
      <OMI>2</OMI>
    </OMOBJ> is
    <maxima>
      <OMOBJ>
        <OMA>
          <OMS cd="arith1" name="plus"/>
          <OMI>1</OMI>
          <OMI>2</OMI>
        </OMA>
      </OMOBJ>
    </maxima>.
  </para>

would then be short for

          
  <para>
    The sum of 
    <OMOBJ>
      <OMI>1</OMI>
    </OMOBJ> and 
    <OMOBJ>
      <OMI>2</OMI>
    </OMOBJ> is
    <monet:query xmlns:monet="http://monet.nag.co.uk/monet/ns">
      <monet:classification>
        <monet:directive-type href="http://mathdox.org/phrasebook/maxima#eval"/>
      </monet:classification>
      <monet:body>
        <monet:output>
          <OMOBJ>
            <OMA>
              <OMS cd="arith1" name="plus"/>
              <OMI>1</OMI>
              <OMI>2</OMI>
            </OMA>
          </OMOBJ>
        </monet:output>
      </monet:body>
    </monet:query>.
  </para>

and if the maxima service is set up properly the output would be:

The sum of 1 and 2 is 3.

Another reason to use macros could be familarity with an other format. Editors who are more familiar to HTML might find it easier to use p instead of para.

The largest problem of using macros is that the resulting document source is no longer MathDox. This could be complicated if multiple people want to work on a document together and not everyone uses the same macros.

Another problem is that allowing different ways to enter the same information might result in confusion. People who use macros might be confused when others use the corresponding MathDox instead. Furthermore others will probably not understand the macros.

It is possible to convert the code with macros into MathDox and put this in the MathDox Player. This however means having two copies. The people who use the macros might want to edit the macro version, while others might want to edit the MathDox version. This can cause problems when working in teams.

MathDox supports macros in the following way. If one provides an XSLT file with the mathdox source, then this file will be used bu the MathDox Player to expand the marcos. The XSLT file should be named macros.xsl and should be placed in the path from the root to the MathDox document, for example, in the same directory as the MathDox source.

[Definition: XSL stands for Extensible Stylesheet Language] and [Definition: XSLT stands for XSL Transformations]. XSLT is a standard by the World Wide Web consortium. On their website are the specifications for XSLT 1.0 and XSLT 2.0.

Example 3. An example XSLT file

The following XSLT 1.0 file can be used to transform the macros mentioned above to MathDox. The file macros.xsl is also included in this manual.

	  
<!-- 
  Example stylesheet file for converting macros
  2007-08-14
  Jan Willem Knopper 
-->
<xsl:stylesheet version="1.0"
  xmlns:monet="http://monet.nag.co.uk/monet/ns"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
>
  <!-- 
    set output indenting
  -->
  <xsl:output indent="yes" method="xml"/>

  <!-- 
    default: copy 
  -->
  <xsl:template match="@*|node()">
    <xsl:copy>
      <xsl:apply-templates select="@*|node()"/>
    </xsl:copy>
  </xsl:template>

  <!--
    convert iv to OMV inside an OMOBJ
  -->
  <xsl:template match="iv">
    <OMOBJ>
      <OMV>
        <xsl:attribute name="name">
	  <xsl:value-of select="."/>
	</xsl:attribute>
      </OMV>
    </OMOBJ>
  </xsl:template>

  <!--
    convert maxima to a MONET-query
  -->
  <xsl:template match="maxima">
    <monet:query>
      <monet:classification>
        <monet:directive-type href="http://mathdox.org/phrasebook/maxima#eval"/>
      </monet:classification>
      <monet:body>
        <monet:output>
	  <xsl:apply-templates/>
	</monet:output>
      </monet:body>
    </monet:query>
  </xsl:template>

  <!--
    convert p to docbook para
  -->
  <xsl:template match="p">
    <para>
      <xsl:apply-templates select="@*|node()"/>
    </para>
  </xsl:template>

</xsl:stylesheet>

If you apply the above XSLT file on the examples described above you will find the following results (only if the maxima service is set up properly).