File:  [mozdev] / abacus / www / usage.html
Revision 1.1: download - view: text, annotated - select for diffs - revision graph
Thu Sep 9 06:43:32 2004 UTC (13 years, 1 month ago) by ajvincent
Branches: MAIN
CVS tags: HEAD
*** empty log message ***

<!-- MAIN CONTENT -->
<h5 class="page-header"><a id="content" name="content">User Manual</a></h5>

<p>You may wish to open up <a href="/screenshots.html">the screenshots page</a> in another tab.  It will give you a
better idea how to use the Abacus projects than this page alone will.</p>

<h2>Starting the MathML Editor from Mozilla Composer</h2>
<p>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.</p>

<h2>Using the MathML Editor</h2>
<ul>
<li>When the MathML Editor initially starts, the "OK" button should be disabled.  If not, something is seriously wrong,
and you need to cancel quickly.</li>
<li>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.</li>
<li>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.</li>
<li>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).
<li>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.</li>
<li>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.)
</li>
<li>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.)</li>
<li>You are <strong>very strongly advised</strong> 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.</li>
<li>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.</li>
</ul>

<h2>Using the Template Editor</h2>
<ol>
<li>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.</li>
<li>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!)</li>
<li>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.</li>
<li>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.
</li>
<li>To open a template, first search for it, and then click the "Open Template" button.</li>
<li>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.</li>
<li>Editing a template is easy (if not always immediately testable).  A markup section indicates where you would write the
template.  The &lt;mEdit:fitb/&gt; 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 &lt;mEdit:fitb-set&gt; 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.</li>
<li>Presentation templates also have, as an option, controls.  These allow the user to specify arguments for 
&lt;mEdit:fitb-set/&gt; 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.</li>
<li>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.</li>
<li>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.</li>
<li>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".</li>
<li>All user-interface changes in a session can be reversed and/or reinstated using the "Undo" and "Redo" options in the
Controls menu.</li>
<li>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.</li>
<li>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).</li>
<li>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.</li>
<li>After all works-in-progress have been completed and the dialogs closed, click the "Save Changes" button.  Then 
<em>verify</em> 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.</li>
<li>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.)</li>
</ol>

<h2>Using the Abacus MathML Editor from other applications</h2>
<p>(This information is as of Abacus 0.1.1, and may be subject to change in the future.)</p>
<p>For a working example of this process in action, reference chrome://abacus/content/overlays/composerOverlay.js .</p>
<ol>
<li>Include chrome://abacus/content/tools/nsITransaction.js in your application.</li>
<li>(Optional, but recommended) Create an object with localAppDoTxn and localAppUndoTxn methods, which reflect
application-specific processing of a returned MathML node.</li>
<li>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.</li>
<li>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:  <code>var aMathMLNode = aDoc.createElementNS("http://www.w3.org/1998/Math/MathML", 
"math")</code>.  For HTML documents not served as XML or XHTML, use <code>aDoc.createElement("math")</code>.</li>
<li>Create a default ID attribute which the MathML Editor can use as a prefix for its output.  I recommend something like
this:  <code>urn:<em>application_name</em>:<em>figure_name</em>:abacus</code>.</li>
<li>Identify the node which the MathML node will be appended to.  (Due to DOM 2 Range usage, you must explicitly specify
this.)</li>
<li>Create a new abacusTransaction object:  <code>var txn = new abacusTransaction(<em>transactionManager</em>, 
<em>MathMLRootElement</em>, <em>originalContents</em>, <em>idPrefix</em>, <em>parentNodeToAppendResult</em>);</code></li>
<li>If you created an object foo with localAppDoTxn and/or localAppUndoTxn, 
<code><em>txn</em>.acceptMethods(<em>foo</em>);</code></li>
<li>Abacus MathML Editor supports partial configuration at runtime.  This is done by passing a custom object (we'll call it
<code>aRuntimeConfig</code>).  If you create <code>aRuntimeConfig.templatesTable</code> 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 <code>aRuntimeConfig.filesByName</code>, it will create a templates table from those named 
files.  If you include <code>aRuntimeConfig.exportIndexNodes = true</code>, 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 
<code>var aRuntimeConfig = {};</code></li>
<li>To open the MathML Editor, <code>txn.openDialog(aRuntimeConfig)</code>.</li>
</ol>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>