Using MathFlow in oXygen

oXygen Editor/Author

When we subsequently mention oXygen Editor, we mean both Editor and Author. Likewise, in oXygen you have the choice of using MathFlow's Structure Editor or Style Editor. Unless it's necessary to distinguish between the 2, we will use the term MathFlow Editor to mean whichever of the 2 you are using. If the difference is important to the topic under discussion, we will make the distinction.

MathFlow for oXygen includes the MathFlow Editor, which is a WYSIWYG editor for entering MathML into your XML documents. The MathFlow Editor is integrated with the oXygen Editor so MathML can be quickly and easily edited in the oXygen environment. Before you begin to create and edit equations in oXygen, ensure you've completed the process of configuring oXygen for MathFlow.

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

As a general rule, while editing a document not of a MathML-aware doctype, the oXygen Editor will operate as if MathFlow has not been installed.

The concept of a MathML-aware document type (doctype for short) is important to understand when authoring MathML documents in oXygen. Most of the components and script code that make up MathFlow's integration with the oXygen 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.

oXygen comes with a good many templates you can use choose from to create documents with math:

  • Global templates
    • EPUB 3.0 Book
  • Framework templates
    • DITA (see section below)
    • Daisy
      • DTBook With MathML
    • DocBook
      • DocBook 4
        • Article with MathML
      • DocBook 5
        • Article with MathML
        • Article with MathML and SVG [DocBook/DocBook 5.0]
      • TEI
        • All plus SVG and MathML
        • Minimal with Math
      • XHTML
        • XHTML 1.1 DTD Based + MathML 2.0 + SVG 1.1
        • XHTML 5
        • XHTML 5 Article

These can also be used as guidance when setting up MathFlow to work with custom doctypes. There are sample documents in the samples/docbook/v4 and docbook/v5 folders you can use to help familiarize yourself with MathFlow's features.

In addition, oXygen includes a number of templates you can use to create MathML "documents", which essentially are stand-alone MathML equations:

  • Framework templates
    • MathML
      • Equation 2.0 DTD Based
      • Equation 2.0 Schema Based
      • Equation 3.0 DTD Based [MathML]
      • Equation 3.0 RNG Based
      • Equation 2.0 Schema Based

To insert an equation, click the insert a math ml equation icon on the toolbar if it's there. It won't be there for all templates, so if it's not there, look in the template's menu for the Insert Equation command:

Insert an equation by clicking Insert Equation on oxygen's toolbar.

There's not a keyboard shortcut, but you can create one. In oXygen's Options/Menu Shortcut Keys dialog, click in the search bar at the top and type insert equation. You should see several; in oXygen 21.1 there are 6 (see screen shot). Make sure Global Options is selected at the bottom, click to select one of the entries (DocBook 5 shown in screen shot), and click Edit (double-clicking will also bring up the Shortcut key dialog). Set as many of them as you want, then click OK.

Assigning a shortcut key to insert an equation.

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 oXygen Editor window.

MathML in DITA

Since MathML is part of the DITA 1.3 spec, MathML is included by default, with no special action required on your part. You should be able to find the Insert Equation command in the Insert flyout of the DITA menu for any of the DITA templates available in oXygen 17.1 or later. This assumes, of course, the insertion point is located inside an element where MathML is allowed.

Adding MathML equations to a DITA project.

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

You can edit MathML Source directly by switching to oXygen's "Text" edit mode. Changes show automatically when switching back to "Author" mode.