Skip to main content

Entities in MathFlow and Abortext

Applicability

The information on this page applies to:

MathFlow 1.x-2.x for Arbortext

Arbortext Editor 4.x and later

Issue

Arbortext Editor and MathFlow give you full control over the entities saved to your XML file. You have the choice as to which names are used to represent each character, as well as the ability to save your entities as entity names, Unicode characters, or the Unicode codepoint. This article explains how to fully manage the handling of entities.

Reason

There are several factors involved in managing your MathML entities. First, MathFlow allows you to map its toolbar buttons to the Unicode character of your choice. This is useful when there are similar Unicode characters and your company prefers the use of one over the other. For instance, when you insert a left angled bracket from MathFlow toolbar, the character x27E8 is inserted, whereas you may need to use the almost identical x2329.

Once you finish the editing in MathFlow the equation gets entered into your XML document, and Arbortext takes all the entities MathFlow passes in and converts them to the format the user prefers. If named entities is listed as the preference, you have the choice of mapping your preferred entity names to the Unicode.

Solution

Mapping Entity Codes for MathFlow

You can set up a special file to change the numerical codes MathFlow reads and generates for some chosen entities:

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

Continuing with the  x27E8/x2329 example introduced above, you specify the mapping in an Incoming translation table (giving your code first – x2329– and MathFlow after it – x27E8) and in an Outgoing table (reversing the order). The Incoming table is used whenever MathML is read into the MathFlow Editor, or sent to generate an image. The Outgoing one 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 format of the charmap.txt file contains the following:

  • 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 0xnnnn, where 'n' stands for any hexadecimal digit). As mentioned, the first one is your desired code; the second one is MathFlow code.

  • Lines in the Outgoing table also consist of a pair of codes in the same format, but now the order is reversed: the first code corresponds to MathFlow the second one to your own code.

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

## Character Code Mapping for [MF]
[Incoming Table]
# our angled bracket [MF]'s
0x2329 0x27E8
[Outgoing Table]
# [MF]'s angled bracket Ours
0x27E8 0x2329
##end of file

Setting the Entity Output Preference in Arbortext Editor

To change the default preference of entity output:

  1. Go to Tools>Preferences in Arbortext Editor.

  2. Click on Advanced.

  3. Double-click preference "entityoutputconvert" and choose "On". Click OK.

  4. Double-click preference "writenonasciichar" and choose from the drop-down menu. Your choices are:

Choice

Example

Entity References (entref)

&

Numerical References (numref)

&#x0026;

Unicode character (char)

&

Mapping Entity References for Arbortext Editor

You can choose which entity names are associated with the Unicode. Put your mappings in a charent.cf file and then point the environment variable APTCHENTPATH to its location. An example is available at <custom>\lib\mathflow\auxiliary\charent.cf. In the example file, the entity name "not" has been mapped to the Unicode x000AC. More information about the table in charent.cf can be found in the Arbortext Editor documentation.

We hope this has been helpful. As always, please let us know if you have questions about this, or if you have additional techniques that work. We'd love to hear from you.