• Monday October 6th 2008
• All the leaves are brown …

Skip to Content

abacus

resources:	Home Mailing List Roadmap Installation Usage Source Code Members Bugs Screenshots

User Manual

You may wish to open up the screenshots page in another tab. It will give you a better idea how to use the Abacus projects than this page alone will.

Starting the MathML Editor from Mozilla Composer

After the spell-check button on the main toolbar of Mozilla Composer, there will appear a button with an image of an abacus and the word "MathML" beneath it. Clicking this button (when it is not disabled) launches the MathML Editor.

Using the MathML Editor

• When the MathML Editor initially starts, the "OK" button should be disabled. If not, something is seriously wrong, and you need to cancel quickly.
• There are two work areas in the MathML Editor. The top one is your template section. The bottom one is your actual MathML expression. The top one determines what the MathML Editor will overlay on the bottom one.
• Light blue and red squares indicate unselected portions of the expression. White and light red squares indicate selections. If a box is shaded in red, that means the value entered in it is considered invalid. If the MathML expression has any such red boxes, the OK button is disabled.
• You can choose which template to work with by the various menu options provided in the second toolbar. The first entry on that toolbar tells you which languages (human and markup) you are working with, but is not itself a menu. The last entry, labeled "Index", provides an alphabetical list of all templates (just in case you're having trouble finding one).
• The upper workspace also includes, frequently, various controls which allow you to change the number of entry fields. For instance, the Addition template has a "Number of arguments" control in it. The number of entry fields will change after you click the "Update Template" button.
• Whichever entry field is selected in the lower workspace will receive the template in the upper half when you click the "Apply Template" button. The selection in the lower workspace becomes whatever field was selected in the upper workspace. (Note: There is a known crash bug on Windows by clicking Apply Template with Abacus 0.1.1. It has not been identified yet.)
• You can select an entire sub-expression of the lower workspace by using the Controls menu and calling "Move Selection Up.". This allows you to replace one section of the MathML expression with a completely new template. Similarly, the "Move Selection Back" command lets you back the selection up one. (This menu also has Undo and Redo commands for backing out and restoring templates.)
• You are very strongly advised to include a unique id in the textbox immediately below the workspaces. This id is used as a prefix for each entry in the MathML expression for internal cross-references.
• On occasion, if a JavaScript error happens, the MathML Editor will add a multiline textbox with a JavaScript stack trace. This stack trace is for debugging; the OK button will be disabled and you will only be able to cancel it. The JavaScript console will have the original error message.

Using the Template Editor

1. The first step is to open the Template Editor in Mozilla Navigator. Visit the URL chrome://abacus/content/templates/editor.xul to start the template editor.
2. If the Operation Name menu does not contain any entries, then something is seriously wrong, and you need to check the JavaScript console. (Most likely, you didn't follow the installation instructions, and left out JSLib's libraries. The second probability is that the XML files containing the templates were not saved properly from the previous editing session; in this case, there has been a serious bug where the Template Editor will accidentally wipe out an entire template file. Frequent backups are strongly recommended!)
3. There are five fields the MathML Editor and the Template Editor use for supporting templates in the MathML Editor. The first two, "Operation Name" and "Index Code", designate a content MathML template. (Index code is simply a code for allowing multiple content templates for a single content MathML element, and is normally best left at the default, "A".) The next three are for designating presentation-specific templates: first, the human-written language code (for American English, this is en-US), then the markup language (MathML, XHTML, SVG, etc.), then an alternate index number (again, for allowing multiple presentation templates for one content template). These values are used more than once.
4. To find a template already in the stored files, fill in the appropriate fields as completely as you think necessary, and click the "Search" button. This performs a regular-expression-based search, so an exact match isn't always necessary.
5. To open a template, first search for it, and then click the "Open Template" button.
6. To create a new template, fill in all five search fields with appropriate values, and hit the Search button. Scroll through the selections to confirm the template does not already exist, and then click the "Open New Template" button. This will typically open two dialog windows: one for the presentation template you specified, and another for the content template it corresponds to.
7. Editing a template is easy (if not always immediately testable). A markup section indicates where you would write the template. The <mEdit:fitb/> element indicates a "fill-in-the-blank" value, which the MathML Editor instructions above refer to as an entry. The mEdit:index attribute indicates in a brief expression (or constant number) the index value this particular element corresponds to (equivalent to an id or xref attribute in MathML). The <mEdit:fitb-set> element indicates a set of elements for repetition. The already-implemented templates for addition and multiplication can explain this better; the most important thing to remember is that the mEdit:index values which the template produces must match up as they would in a pure MathML expression. Also, the root element of any template must have a mEdit:index="0" attribute, and be the only element in the template to possess that attribute.
8. Presentation templates also have, as an option, controls. These allow the user to specify arguments for <mEdit:fitb-set/> elements. Again, the addition and multiplication templates give examples of their use; conversely, the subtraction, division, and comparison templates give examples of templates that do not have a flexible number of arguments.
9. When you have not-well-formed XML markup, the background of the template's markup section will be shaded in light red, and the OK button will be disabled. This is a safety measure for the MathML Editor.
10. Creating templates is not enough; you must also create a user-interface for the MathML Editor to call on those templates. There is a specific user-interface available for each human/markup language combination, selectable by a menulist with the combination as the label.
11. You can add new menus by setting a label value in the "Label" box and selecting the "Add New Menu" option in the Controls menu. Menus can be moved to the left and right of each other by opening the menu and selecting "Move this menu to the left" and "Move this menu to the right", respectively. Menus can also be deleted by selecting "Delete this menu".
12. All user-interface changes in a session can be reversed and/or reinstated using the "Undo" and "Redo" options in the Controls menu.
13. To change the label of a menu, enter a new label name in the Label box, and select "Set new label and image" in the menu.
14. Adding a new item to the menu is easy. You enter the label into the Label box, and select "Add new item to menu" in the menu you want it added to. Items can be moved up or down within a menu similarly to how a menu is moved left and right; likewise, you can change the label of an item or delete it entirely via the item's submenu (which only appears in the Template Editor, not the MathML Editor).
15. There is also a "Set Presentation Template" option for menu items in their submenus. To set a template, fill in the five template fields used for searching among templates with the appropriate values, and click the "Set Presentation Template" option. When you return to the submenu, you will see a shorthand for that template name immediately beneath the "Set Presentation Template" option.
16. After all works-in-progress have been completed and the dialogs closed, click the "Save Changes" button. Then verify that the file was written correctly! For MathML, this would mean simply opening chrome://abacus/content/templates/math.xml in another tab of your browser. If it wasn't, you will need to restore from a backup copy of this file, or else the MathML Editor will be unusable.
17. You can also test your templates and their user-interface by clicking on the "Open Abacus MathML Editor to test templates" button, which will launch an instance of the Abacus MathML Editor. (As of 0.1.1, however, you will need to reload the Template Editor first. This is another known bug.)

Using the Abacus MathML Editor from other applications

(This information is as of Abacus 0.1.1, and may be subject to change in the future.)

For a working example of this process in action, reference chrome://abacus/content/overlays/composerOverlay.js .

1. Include chrome://abacus/content/tools/nsITransaction.js in your application.
2. (Optional, but recommended) Create an object with localAppDoTxn and localAppUndoTxn methods, which reflect application-specific processing of a returned MathML node.
3. If your application does not has a transaction manager (which handles undo/redo operations in Mozilla), create one. The MathML Editor assumes implicitly that you will pass it your application's transaction manager.
4. Identify the original contents and the MathML root element you will pass to the MathML Editor. If you do not have a MathML root element, create one: var aMathMLNode = aDoc.createElementNS("http://www.w3.org/1998/Math/MathML", "math"). For HTML documents not served as XML or XHTML, use aDoc.createElement("math").
5. Create a default ID attribute which the MathML Editor can use as a prefix for its output. I recommend something like this: urn:application_name:figure_name:abacus.
6. Identify the node which the MathML node will be appended to. (Due to DOM 2 Range usage, you must explicitly specify this.)
7. Create a new abacusTransaction object: var txn = new abacusTransaction(transactionManager, MathMLRootElement, originalContents, idPrefix, parentNodeToAppendResult);
8. If you created an object foo with localAppDoTxn and/or localAppUndoTxn, txn.acceptMethods(foo);
9. Abacus MathML Editor supports partial configuration at runtime. This is done by passing a custom object (we'll call it aRuntimeConfig). If you create aRuntimeConfig.templatesTable with chrome://abacus/content/tools/template.js, the MathML Editor will use that. Otherwise, if you pass it an array of XML template file names as aRuntimeConfig.filesByName, it will create a templates table from those named files. If you include aRuntimeConfig.exportIndexNodes = true, the MathML Editor will export its results as a MathML+"mEdit" combination (basically, it won't clean out the template code; this may be useful if you have another use for the mEdit:index attributes). If you wish to use the default configuration, then var aRuntimeConfig = {};
10. To open the MathML Editor, txn.openDialog(aRuntimeConfig).