Using MathFlow in XMetaL

Overview, XMetal integration

XMetaL Author

MathFlow for XMetaL includes the MathFlow Editor, which is a WYSIWYG editor for entering MathML into your XML documents. The MathFlow Editor is integrated with the XMetaL Editor so MathML can be quickly and easily edited in the XMetaL environment. The MathFlow menu provides access to the following MathFlow features:

Insert Equation… opens a MathFlow Editor window.
Refresh Equation Images manually re-synchronizes the preview images in the XMetaL Editor window.
Fast Equation Rendering generates equation images using the C++ equation rendering component.
MathFlow Help will open a window with the MathFlow documentation. Note this will open the documentation installed onto your computer with XMetaL. We recommend always using the documentation at docs.wiris.com unless you're not connected to the internet. The documentation here is always kept more up-to-date than the copy installed with XMetaL.
About MathFlow will open a window with information on the installed MathFlow version, as well as about what features are licensed and available for use.

The basics of using the MathFlow Editor in XMetaL are described in the following topics. For further details on the editor, please refer to the MathFlow Editor and Tutorials sections.

As a general rule, while editing a document not of a MathML-aware doctype, the XMetaL Editor will operate as if MathFlow has not been installed. While all of the above MathFlow enhancements will still be present, only MathFlow Help and About MathFlow will operate as advertised.

XMAX

To illustrate how to use MathFlow with the XMetaL ActiveX control, the XMetaL ActiveX example has been modified to include MathFlow

This sample application is located in the <path‑to‑xmetal>\Author\[MF]\activex\XMActiveX_[MF]HtmlSample directory. To view this sample, you must have XMetaL ActiveX installed either by installing XMetaL Developer or the XMetaL ActiveX control. If Internet Explorer is your primary browser, simply double-click XMetaLActiveX.html to begin. If another browser is your primary browser, find XMetaLActiveX.html in a File Explorer window and in the contextual menu (right-click), choose Open With > Internet Explorer.

The following modifications are made to the XMetaL menu:

There is a new menu item, MathFlow containing three entries: Insert Equation, MathFlow Help (opens a window with the MathFlow documentation) and About MathFlow for XMetaL (opens a window with information on the installed MathFlow version, as well as what features are licensed and available for use).
There is a new Insert Equation icon on the toolbar which opens a MathFlow Editor window.

Please note the MathFlow XMetaL ActiveX example is not a full application. It is simply intended to show how MathFlow can be added to an XMetaL ActiveX application. To create a full ActiveX application, see Create a MathFlow XMAX HTML Application.

Author: Sample document types

The concept of a MathML-aware document type (doctype for short) is important to understand when authoring MathML documents in XMetaL. Most of the components and script code that make up MathFlow integration with the XMetaL editor do not depend on a specific document type, but your doctype must include MathML to be able to create and edit equations with MathFlow

There are several considerations in setting up a new math doctype, such as including the MathML 3.0 schema module in your custom schema. Although MathFlow has been designed to help minimize the amount of work required and in some cases setting a few configuration variables will suffice, in most instances much more customization will be needed. For complete details on setting up your own doctype, including discussion of the DTD (Document Type Definition), please refer to the Setting up a custom doctype section later in this documentation.

MathFlow comes with two sample doctypes, which can be used as guidance when setting up MathFlow to work with custom doctypes. The demo files in the sample doctypes can also be used to familiarize yourself with MathFlow features.

Journalist_math

The Journalist_math doctype is an extension of the XMetaL sample Journalist doctype. The doctype files for journalist_math can be found in the following location:

<path-to-xmetal>\Author\Rules

You can find a sample file to demonstrate how to use MathFlow to include MathML in a document:

<path-to-xmetal>\Author\Samples\Journalist_math\demo.xml

DITA_mathml

The dita_mathml doctype is a MathML domain specialization for DITA. DITA is a public standard maintained by OASIS.

The doctype files for dita_mathml can be found in the following location:

<path-to-xmetal>\Author\DITA\XACs\dita_mathml

The demo files for the dita_mathml doctype include a map file (MathML_Map.ditamap) that references a topic file and a concept file and are located in the following folder:

<path-to-xmetal>\Author\Samples\DITA

For instructions on inserting equations with MathFlow from the DITA sample doctype, see

<path-to-xmetal>\Author\Samples\DITA\MathML_Task.xml

To start creating your own DITA files using the MathML domain specialization, you can use the templates provided in the following location:

<path-to-xmetal>\Author\Template\DITA Topic

Author: Inserting an equation

To insert an equation, go to the MathFlow menu in XMetal and click Insert Equation…:

The keyboard shortcut Ctrl+Alt+Q will also insert an equation, as well as clicking the Insert Equation icon on the XMetaL toolbar.

All of these options open an instance of the MathFlow Editor.

Once you have created an equation in the MathFlow Editor, click the OK button to close the Editor and insert the resulting MathML into the document structure. A preview image is also generated for the XMetaL Editor window.

Author: Editing an existing equation

To edit an existing equation, double click on the equation preview in the XMetaL Editor. This will open the equation in the MathFlow editor. Once you have finished editing the equation, click OK to update the equation.

Refresh equation images

To refresh all of the equation images in the current document, go to the MathFlow menu in XMetal and click Refresh Equation Images:

Fast equation rendering

To turn Fast Equation Rendering on or off, go to the MathFlow menu in XMetal and click Fast Equation Rendering...

If Fast Equation Rendering is on, the system will use the C++ equation rendering component to generate equation images, rather than the default Java equation image rendering component. The C++ component is optimized for speed, however the image generated may not match the look of the equation in the MathFlow Editor, which is generated by the Java component.

The Fast Equation Rendering option is useful in cases where a document contains greater than 100 equations, since each equation image is rendered when the document is opened.

Author: Editing MathML source

You can edit MathML Source directly by switching to XMetaL's "Plain Text" option on the View menu. Changes show automatically when switching back to normal view (only if the MathFlow equations are white and not gray; i.e. the MathFlow license is checked out). You can also manually re-synchronize the preview images in the XMetaL Editor window. To do this, select the Refresh Equation Images command from the MathFlow menu, shown in the screen shot above.

Author: XHTML+MathML output

As mentioned in Installation, MathFlow installs a stylesheet for XHTML+MathML output. You can generate XHTML+MathML output with this stylesheet by duplicating the output configuration for "Single HTML" and changing the default stylesheet used. To do that:

Open a DITA map file, and in the Resource Manager menu, select File > Generate Output for DITA map or click the icon:
In the dialog that pops up, click Configure Output…. This will open a new dialog window.
In the Configure Output Options dialog, select Single HTML file and click Duplicate.
With Copy of Single HTML file selected, click Edit.
In the "Edit Deliverable Type" dialog, change the Name to XHTML+MathML, then click Advanced.
In the Advanced tab, enter the path or browse to the singlexhtml.xsl stylesheet and click OK. Default location for this file depends on your version of XMetaL, but it should be in one of these locations:

C:\Program Files\Common Files\XMetaL Shared\DITA_OT\demo\xhtmls\xsl C:\ProgramData\SoftQuad\XMetaL\Shared\DITA_OT[version]\plugins\com.xmetal.xhtmls\xsl mathflow_xhtml-mathml_configure_output_edit_deliverable_type.png

Under "Other output parameters", enter: ANT_PARAM_args.grammar.cache="no"
Click OK again.
Back in the "Configure Output Options" dialog, click Advanced. Under "Other output parameters", find cmd_dita_ot_per_user_version, and change the value to 2. Verify the value for DITA_OT_DIR is %XMETAL_SHARED_ALL%\DITA_OT[version]
Click OK.
From now on, the XHTML+MathML output configuration will show up in the "Generate Output for DITA map" dialog, and can be chosen to generate the output.

XMAX: Journalist Math document

Choose File|Open from the menu and the File dialog will open.

For the XML File, use the Browse button to select the journalist_math sample document (demo.xml). For the XAC File, use the Browse button to select the journalist_math.xac file.

Click OK to open the journalist_math sample document.

XMAX: Inserting an equation

To insert an equation, you can either click the Insert Equation icon on the toolbar, or choose MathFlow from the menu.

Both of these options open an instance of the MathFlow Editor.

Once you have created an equation in the MathFlow Editor, click OK to close the Editor and insert the resulting MathML into the document structure. A preview image is also generated for the XMetaL Editor window.

Editing an existing equation

To edit an existing equation, double click on the equation preview in the XMetaL Editor. This will reopen the equation in the MathFlow editor. Once you have finished editing the equation, click OK to update the equation.

In this section: