Setting up a custom doctype for Arbortext

MathFlow has been designed to minimize the amount of work required to set up a new doctype. In most cases, little or no ACL programming is required, only setting of a few configuration variables reflecting how MathML has been incorporated into the doctype.

Each custom doctype is specified by a DTD or XML Schema, which must include the MathML 3.0 module if MathFlow is to be used. MathFlow doesn't place any restriction on how you embed MathML, but by following certain guidelines you can make your life easier.

The central consideration is how the distinction between inline and display style equations is reflected in the markup. The sample axdocbook_math.dtd provides <equation> and <inlineequation> elements for this purpose. If you can use these elements in your custom doctype, very little MathFlow customization is required. If you can arrange to use two distinct elements for inline and display math, the situation is still fairly straightforward. If you use some other scheme, you will have to provide ACL functions for distinguishing the two cases.

The following sections illustrate step-by-step instructions for setting up a custom doctype for use with MathFlow.

If you use Styler stylesheets for composition, you need to add the MathML Styler module (in <custom-path>/stylermodules/mathml.style) to your stylesheet. Please note the Styler stylesheet (.style files) will not work with the UMSS output for HTML.

To include the MathML Styler module in your stylesheet,

  1. Open your stylesheet for editing in Arbortext Styler.
  2. Select File | Modules. The Modules dialog box opens.
  3. Select the Add button. The Add Module dialog box opens.
  4. Browse to the directory containing the MathML styler module (<custom>/stylermodules/mathml.style), select it, and select the Add button.

You can also edit the .style file by hand by copying and pasting the lines at the end of axdocbook_math.style (found in the <custom-path>/doctypes/axdocbook_math folder) between the <Modules> tags.

For more details about using modules and Styler, see Arbortext Styler's documentation.

The MathFlow installation also includes other examples of stylesheets for your reference. For XSLT examples, please see

<custom-path>/doctypes/axdocbook_math/axdockbook_math-html.xsl

for HTML composition or

<custom-path>/doctypes/axdocbook_math/axdockbook_math-fo.xsl

for PDF. Both pass along the MathML markup, only deleting some undesired attributes.

Add the following math namespace declaration to the <xsl:stylesheet> start tag in your XSL stylesheets (replacing the prefix "m" with the one you have chosen):

xmlns:m="http://www.w3.org/1998/Math/MathML"

NOTE: To get the best results from MathFlow Composer, Arbortext Styler users must export their style sheet to XSL-FO or XSL-HTML (from the File | Export menu in Styler). Users can then edit exported style sheets by deleting all templates for MathML elements and copying the code to pass MathML.

To get the formulas to line up correctly with the surrounding text when using FOSI stylesheets, you would have to make sure you have the following lines in a .tmx file in your doctype directory, which defines a new command raisegraphic:

% \raisegraphic is called from the FOSI's e-i-c for inlinegraphic
% to provide vertical adjustment of the graphic \def\raisegraphic|#1#{%
% #1 is either \2-\3X or just X where X is an unsigned dimen
{\def\2{}\def\3{}\def\raiseamount{#1}\global\dimen0=\raiseamount}%
\raise\dimen0\hbox
}

It should also be used in the inlinegraphic element in yourdoctype.fos stylesheet, in something like this:

<e-i-c gi="inlinegraphic">
<charlist charsubsetref="character"></charlist>
<att>
<fillval attname="baseline" fillcat="savetext" fillchar="conrule">
<charsubset>
<savetext textid="graphic-shift">
<usetext source="%\raisegraphic%,graphic-shift,%{%" placemnt="before"></usetext>
<usetext source="%}%" placemnt="after"></usetext>
</charsubset>
</att>&revflag;
</e-i-c>

For examples, look at the files axdocbook_math.tmx and axdocbook_math.fos in the distributed custom directory.

The following sections include instructions for setting up MathFlow for use with a custom doctype.

The DTD and XML schema

You'll need to add the MathML 3.0 module to your DTD or XML Schema. The DTD or XML Schema sets the rules for your document and tells MathFlow and Arbortext Editor your document can include MathML.

DTD

As a guide, you can use the sample DTD located at this path:

<custom-path>/doctypes/axdocbook_math/axdocbook_math.dtd

For axdocbook_math, the relevant lines are listed below (with line numbers used for description):

  1. <!-- MathML .........................................................-->
  2. <!-- ======= UNCOMMENT THE FOLLOWING TO USE NAMESPACE PREFIXES ======-->
  3. <!ENTITY % MATHML.prefixed "INCLUDE">
  4. <!ENTITY % MATHML.prefix "m">
  5. <!ENTITY % mathml-dtd PUBLIC "-//W3C//DTD MathML 3.0//EN" "mathml3.dtd">
  6. %mathml-dtd;
  7. <!- - Equation.content includes the para element, for now, to -->
  8. <!-- facilitate import of equations from Word. This should be -->
  9. <!-- reassessed long term. -->
  10. <!ENTITY % equation.content "(graphic|fd+|m:math+|para+)">
  11. <!ENTITY % inlineequation.content "(graphic|f+|m:math|para+)">
  12. <!-- Add the baseline attribute to inlinegraphic, so we can use -->
  13. <!-- vertical offsets. -->
  14. <!ENTITY % local.graphics.attrib "baseline CDATA #IMPLIED">
  15. <!-- ................................................................-->

Line 3 determines whether the MathML elements should be preceded by a namespace prefix. If you do not plan to use a namespace prefix, you can change the setting from INCLUDE to IGNORE. If you are using a namespace prefix, set the prefix at Line 4.

Line 5 gives the location of the mathml2.dtd relative to your doctype DTD.

Line 6 instantiates the MathML DTD.

Lines 7-14 are specific to the axdocbook_math DTD, but you will need similar declarations listing the MathML math element as a possible child element.

XML schema

There are two steps necessary to customize your XML Schema:

  1. Import the MathML Schema, as in this example:

    <xs:import namespace="http://www.w3.org/1998/Math/MathML"schemaLocation="mathml3.xsd"/>
  2. Add the <m:math> element as a possible child of the appropriate element, shown in this example:
    <xs:group name="equation.content">
    <xs:sequence>
    <xs:element minOccurs="0" ref="alt"/>
    <xs:choice>
    <xs:element maxOccurs="unbounded" ref="graphic"/>
    <xs:element maxOccurs="unbounded" ref="mediaobject"/>
    <xs:element maxOccurs="unbounded" ref="m:math"/>
    </xs:choice>
    </xs:sequence>
    </xs:group>
    <xs:complexType name="inlineequation.content">
    <xs:sequence>
    <xs:element minOccurs="0" ref="alt"/>
    <xs:choice>
    <xs:element maxOccurs="unbounded" ref="graphic"/>
    <xs:element maxOccurs="unbounded" ref="inlinemediaobject"/>
    <xs:element maxOccurs="unbounded" ref="mathphrase"/>
    <xs:element maxOccurs="unbounded" ref="m:math"/>
    </xs:choice>
    </xs:sequence>
    </xs:complexType>

Catalog files

  1. Modify the file <custom-path>/doctypes/catalog to include a line similar to this:

    PUBLIC "-%%//%%Arbortext%%//%%DTD DocBook XML V4.0 + MathML%%//%%EN"
    "axdocbook_math/axdocbook_math.dtd"
  2. Add the appropriate entries to <custom-path>/doctypes/<yourdoctype>/catalog (copy from <custom-path>/doctypes/axdocbook_math/catalog) to include the various .ent files, as well as mathml3.dtd.

mathml_user.acl

  1. Add your new doctype to the mathml_doctypes array in the file <custom-path>/scripts/mathml_user.acl (create it if it you haven't done so already.) The entry should be similar to the line near the beginning of <custom-path>/init/mathml_init.acl:

    $mathml_doctypes[1] ="axdocbook_math";

    (where you should change the index [1] to [2], [3], etc. with successive additions of doctypes, and use the external name of your own doctype instead of axdocbook_math.

    This name should match the one returned by the ACL function doc_type(). Alternatively, you can open a document of this doctype, open the Session dialog box (by choosing Help | About Arbortext Editor | Session from the main menu bar) and look up the Document Type entry in its Document tab.)
  2. Depending on what markup mechanism you've chosen to distinguish inline and display equations, add new elements to display_parents, inline_parents, and paralike_parents arrays in the file <custom-path>/scripts/mathml_user.acl. They should look like the entries near the beginning of <custom-path>/init/mathml_init.acl:

    $display_parents[$mathml_doctypes[1]] = "equation";
    $inline_parents[$mathml_doctypes[1]] = "inlineequation";
    $paralike_parents[$mathml_doctypes[1]] = "para";

    The array indices here should match up with the ones in the previous point, for the corresponding doctype.

    If your mechanism doesn't fit in with this scheme, you will have to modify the implementation of the functions is_math_display, etc. immediately following the array definitions in <custom-path>/init/mathml_init.acl.

    If you have only one equation element, you can set both the display_parents and inline_parents array indices to the same element, but unless you modify the is_math_display function, the images will be generated in display style.
  3. Add the MathML namespace prefix for your doctype in the nsprefix array index as in <custom-path>/init/mathml_init.acl:

    $nsprefix[$mathml_doctypes[1]]="m";

    If you are not using a namespace prefix, leave this value empty.

Your doctype dcf file

Edit your doctype's dcf file to specify a MathML element as a graphic element. To do so, add this line (changing the prefix as necessary):

<Graphic element="m:math" filename="altimg" reproDepth="height" reproWidth="width" vertOffsetAmount="baseline"/>

Stylesheet changes

  • If you are using the FOSI stylesheet to format screen display, you will need to modify your doctype .fos file. We want to show all math elements, but hide from view any elements inside it. We accomplish this by adding lines such as these for every MathML element (except math itself):
    <e-i-c gi="m:mrow">
    <charlist inherit="1">
    <suppress sup="1">
    </charlist>
    </e-i-c>

    You can just copy the corresponding lines from axdocbook_math.fos into your own FOSI stylesheet. They are the lines between the comments
    <!-- MathML elements to hide -->
    and
    <!-- end of MathML elements to hide -->.

  • If you are using an Arbortext Styler stylesheet, add the MathML formatting module (located in <custom>/stylermodules/mathml.style). To do this,
  1. Open your stylesheet for editing in Arbortext Styler.
  2. Select File | Modules. The Modules dialog box opens.
  3. Select the Add button. The Add Module dialog box opens.
  4. Browse to the directory containing the MathML styler module (<custom>/stylermodules/mathml.style), select it, and select the Add button.

For more details about using modules and Styler, see Arbortext Styler's documentation.

(see Arbortext's documentation on Building Map Files for more detailed information).

To set up Arbortext's Import feature for a new doctype, you must create a new map file. No customization of MathFlow itself is required. The MathType/Word macros wrap the generated MathML in MTConvertedEquation styles, which are then wrapped in MTDisplayEquation styles for displayed equations. Your map files should process these styles and replace them with appropriate wrapping tags for MathML elements in your doctype.

The sample doctype axdocbook_math is used to demonstrate equation integration with the original axdocbook doctype. Design Science provides the following map file as an example of mapping elements into the correct tags for the axdocbook_math doctype:

<custom-path>/importexport/STDTemplates/word2axdocbook_math.std

Your own map files should include analogous entries, replacing equation and inlineequation with corresponding elements in your doctype.

After you have created a project, you can open the map files in Arbortext. To do this, select File | Import/Export | New Import Project… and create a new folder inside, e.g.,

<custom-path>/importexport/STDTemplates/MyProjects/

Make sure the new folder is selected and click the OK button. The Import Workbench window will appear, allowing you to open the map template word2axdocbook_math.std (see above file location). To open the map file, choose File | Open | MapTemplate…, selecting the file you wish to open. The file word2axdocbook_math.std contains a modified version of the word2axdocbook.std file and adds the rules necessary to handle equations. The first and second rules from the bottom of the list are called equation and inlineequation. The first rule can be summarized by the following:

SELECT element(s):
( whose name equals 'SPECIALTEXT')
AND ( whose Text CONTAINS '<m:math>')

Notice it searches for a ppXML tag called SPECIALTEXT, and the specific text <m:math>. The second rule can be summarized by the following:

SELECT element(s):
( whose name equals 'SPECIALTEXT')
AND ( whose Text CONTAINS '<m:math display='block'>')

Note this rule is similar to the previous rule, except it searches for <m:math display='block'>. The output hierarchy for the output rule of each of these Map Objects is as follows: first, MTDisplayedEquation styles are changed into equation elements surrounded by para tags. Next, the MTConvertedEquation styles are processed and surrounded by equation tags. Lastly, the rest of the MTConvertedEquation styles are converted into inlineequation elements.

In many cases, there are several Unicode characters almost visually identical. In these cases, MathFlow generally has a preferred character, which is provided when using the toolbar and palettes. While MathFlow attempts to use the most common or semantically correct characters in cases where there are several visually similar choices, customers may have existing policies for preferred characters do not correspond with Mathflow's choices.

Consequently, MathFlow provides a character mapping feature to change numerical codes for some chosen entities:

<custom-path>/lib/mathflow/auxiliary/charmap.txt

For example, you may want to use x2329 instead of MathFlow's x27E8 for an angled bracket.

To do this, specify it in an Incoming translation table (providing your code x2329 first, then MathFlow's x27E8 after it) and an Outgoing table (thereby reversing the order of codes). The Incoming table is used whenever MathML is read into the MathFlow Editor, or sent to generate an image. The Outgoing table is used when receiving the markup from the MathFlow Editor, before inserting it back into your Arbortext document. Most of the time, you will end up writing entries in pairs—one for each table—but having two separate tables gives you the most flexibility for replacing codes.

The following items outline the format of the charmap.txt file:

  • Lines starting with # are considered comments and ignored.
  • A line starting with [Incoming signals the beginning of the Incoming table. Any line following it is considered part of this table, until there is a line starting with [Outgoing, which signals any line following it is part of the Outgoing table.
  • Lines in the Incoming table should consist of a pair of codes (in the format xNNNN, where "N" stands for any hexadecimal digit). As mentioned, the first one is your desired code; the second one is MathFlow's code.
  • Lines in the Outgoing table also consist of pairs of codes in the same format, but now the order is reversed; the first code corresponds to MathFlow's, the second one to your own code.

For the example mentioned above, the charmap.txt file could be the following:

## Character Code Mapping for MathFlow
[Incoming Table]
# our angled bracket MathFlow's
x2329 x27E8
[Outgoing Table]
# MathFlow's angled bracket Ours
x27E8 x2329
##end of file
Note: This is a simple mechanism, and there are several limitations to its use, especially when changing the glyphs of entities. Realize this only translates between MathFlow and the rest of the world, but it does not change MathFlow's internal workings. So for example, if you map the code for phi to the one for phiv, and then add a phi in MathFlow's Editor, you will still see the glyph of phi in this editor's window. However, once you insert the markup back into Arbortext, the image generated should have the expected glyph, the one corresponding to phiv.

Likewise, this does not affect the way Arbortext itself renders characters. So, if you are viewing the MathML markup content in Arbortext (as opposed to viewing the preview images created by MathFlow) you will still see the glyphs corresponding to Arbortext's codes, not the ones you put in charmap.txt. Arbortext has a similar mechanism for changing the codes of named entities, via a charent.cf file. You should have one such file in <custom-path>/lib/mathflow/auxiliary. If the codes you are mapping correspond to named entities, you may want to add entries in this file to make Arbortext's glyphs agree with MathFlow's.

When creating a DITA specialization in Arbortext, a few additional customization steps are required to use MathFlow with resolved maps. Resolving a map file for editing (via the Edit | Edit Resolved Document menu in Arbortext) generates a temporary document in the rdedit doctype, while resolving a map for styling generates a temporary document in the rdstyle doctype. Therefore, to be able to view the MathML as preview images in resolved maps, you must also customize the rdedit and rdstyle doctypes as described in the previous sections.

For an example of rdedit and rstyle customizations, please see the documents in the following locations:

<path-to-custom>/doctypes/mathml-rdedit <path-to-custom>/doctypes/mathml-rdstyle

Furthermore, the DITA map doctype's Document Configuration File must be edited to give the doctype identifiers of the new rdedit and rdstyle doctypes. For example:

<Options ditaRDEdit='resolvedmap PUBLIC "-//DESSCI//DTD RDEdit with MathML//EN" "mathml-rdedit.dtd"'
ditaRDStyle='RDStyle PUBLIC "-//DESSCI//DTD RDStyle with MathML//EN" "mathml-rdstyle.dtd"'/>

Use the files in the following folder as a guide:

<path-to-custom>/doctypes/map