Advanced Mathematical Editing Configuration

This section helps you to use the configuration options in Zed to extend the support for mathematical operators, including customizations for extending the predefined sets of menus and palettes, customizations for the mappings from content to presentation, customizations for the operator input templates, and customizations for the operator traversal order.


Custom Layout Wizard
Dialogs
Files
Methods
Properties

Zed allows a high degree of customization for many aspects of the operators it supports. Using the configuration customization framework, both end users and application developers can tailor operator editing behavior in a variety of ways. Six general categories of operator configuration information can be customized: menus, palettes, layout rules, template rules, traversal orders, and other properties. The configuration customization framework can be used to define custom menus and palettes for applications, to supply custom layout transformations for mathematical operators, to alter the default bindings for many of the keyboard accelerators used by the editor, or to supply editing behavior for anonymous function symbols.

The configuration information is associated with property values attached to the internal symbols representing MathML content elements and user-defined operators appearing in <apply> elements. Zed uses its generic expression data type for representing the configuration properties associated with each operator, both for convenience in the internal implementation and because it provides an easily implementable and uniform linear syntax for customizing the configuration properties. Dialog boxes allowing access to this internal expression encoding are provided, and are described in more detail below. Zed also supports storing the configuration expressions in a compressed form in an external configuration file, and provides methods for loading, saving, and creating such files, using methods in the Zed Custom API.


Custom Layout Wizard

In addition to the six configuration dialogs described below, Zed provides a Custom Layout Wizard to simplify the process of creating a custom layout transformation for a content operator. Using the Custom Layout Wizard allows you to type an expression into an editor window that resembles a function definition, and to have that function definition be used to supply the mapping from content to presentation for the content operator that appears on the left hand side of the equation.

Example: layout.mml

To use the Custom Layout Wizard, open a new editor window (or simply use an existing editor window) and enter the function definition for the content operator you would like to customize. On the left hand side of the equation, enter the content operator, along with the function arguments needed to construct an application of the function to its arguments. On the right hand side of the equation, enter an expression that has the same presentation as you would like used for the content operator that appears on the left hand side of the equation. Any content expression that produces the desired presentation will do. Clicking on the above link should bring up a frame at the top of the page with an example of the type of function definition that can be used by the Custom Layout Wizard.

Once you've entered the equation as described above, select the Format→Custom menu item, or click the Custom Layout button from the Format toolbar. The Custom Layout configuration dialog will display the layout transformation rule for the content operator that was extracted from the equation that you entered. You may modify the layout transformation as desired, and then you may use the OK button to install the custom layout transformation, or the Cancel button to discard it. When you choose to install your new custom layout transformation using the OK button, you should immediately see the presentation of the left hand side of your equation modified to use the new layout transformation, even though the content expression remains the same.


Dialogs

The Option menu and the Option toolbar each provide access to the six configuration dialogs that you can use to modify the linear encoding of each of the six configuration properties used by Zed. Each configuration dialog displays the linear encoding of one configuration property in an edit box where you can type additional declarations using the same syntax as for Zed expressions. On each configuration dialog there are three buttons. The Get button can be used to fill the configuration dialog with the current value of its associated configuration property. The Set button can be used to update the current value of the configuration property with the expression found in the edit box. The Done button is used to dismiss the configuration dialog, without applying any further changes to the associated configuration property.

When you modify the configuration properties using the configuration dialogs, the changes you make are applied to each of the Zed documents that are currently in use in the current application or container. Once the current application is closed, any unsaved changes to the configuration properties are discarded.


Files

Zed configuration files provide a mechanism for persisting configuration customizations between sessions. The configuration files are stored using a binary encoding consisting of a file header containing a table of section offsets, a symbol table listing the names of the symbols used, and then a binary encoding of each of the six configuration expressions presented by the configuration dialogs. While the binary encoding is certainly not human-readable, Zed provides a number of methods that make it easy for you to load a particular configuration file, or to create custom configuration files from the somewhat more accessible linear encoding used to represent the customization information. Zed configuration files are typically given the extension .zc.

The particular editing conventions used in Zed are largely defined in the standard configuration file distributed with the editor. This file defines initial values for each of the six configuration expressions, collectively providing default editing behavior for each of the standard MathML content elements, as well as the default keyboard accelerators, menus, and palettes used to create them. The standard configuration file is installed as Config/Zed.zc.

The configuration dialogs described in the previous subsection allow you to dynamically modify the behavior of the editor. The configuration changes you make using these dialogs can be saved into a custom configuration file using the menu item Option→Save. These same configuration changes can be loaded into the editor using the menu item Option→Load, which uses the standard file open dialog to allow you to choose the configuration file you would like to use. These operations are also available on the Option toolbar. The configuration files are typically stored in the Config directory.

The operations for loading and saving configuration files allow you to create custom configurations that are useful for editing different types of mathematical expressions, and choose the one you want to use in each session. Alternatively, you can replace the file Config/Zed.zc if you want to change the default state of the configuration options that are loaded each time the editor is launched. If you choose to overwrite the standard configuration file, you might want to make a copy of it somewhere in case you change your mind. Otherwise, you can either reinstall Zed to recover the file if you inadvertently delete it, or use the configuration source files provided in the Config/Source directory to recreate it, as described in the next subsection.


Methods

While it is possible to create a configuration file by hand, as described in the previous subsection, there are at least two common situations where a programmatic solution for creating a configuration file is useful. First, when Zed is embedded in a larger mathematical application, the application may want to arrange for custom editing behavior for certain operator symbols when a user first begins to interact with the application. In this case the application can either distribute a custom configuration file that can be loaded when the application starts, or use methods in the Zed Custom API to set up the desired customizations. The second case where methods from the Zed Custom API are useful is in the development cycle for such applications, where a JavaScript program can be used to build the configuration file in an automatic fashion.

The easist way to create a custom configuration file is to start by loading an existing configuration file, such as the standard Config/Zed.zc, make incremental modifications to the configuration options, and then save out the custom configuration file. Each of these steps can be performed using methods included in the Zed Custom API. The LoadConfig method can be used to load the existing configuration file, the AddConfig method can be used to make the incremental modifications, and the SaveConfig method can be used to save the custom configuration file. The LoadConfig and SaveConfig methods allow you to specify the name of the configuration file, and the AddConfig method allows you to specify the special key symbol identifying which configuration property to modify, and the additional configuration information to be added to the property.

In addition to the AddConfig method, the GetConfig method can be used to get the linear encoding of any configuration property, allowing general string operations to be applied to the returned value, then the property can be updated using the SetConfig method. These methods allow for more general control over the form of the configuration expressions.

Lastly, during the development cycle for an application to be built using Zed, one can create a collection of source files containing the configuration expressions to be compiled into a custom configuration file. These source files are each encoded using the linear encoding of the Zed expression used to represent the configuration property. Once these files are created, they may be used to create a custom configuration file by using the ReadConfig method to load each configuration property, one at a time, from the source file into an instance of the Zed component, then using the SaveConfig method to write out the entire collection to the new custom configuration file. This process is used to create the standard configuration file distributed with Zed, and is illustrated by the files in the Config/Source directory. Executing the file Config/Source/zconfig.js on a machine with the Microsoft Windows Scripting Host installed will create a file Config/ZedCustom.zc which should be byte-for-byte identical to the standard configuration file Config/Zed.zc distributed with the editor.


Properties

Menus
Palettes
Layout Rules
Template Rules
Traversal Orders
Other Properties

The remaining piece of the configuration customization framework is the specific format of the information encoded in each section of the configuration options. The following paragraphs describe each configuration property, the scope of the information it represents, and the particular conventions used to express that information in the configuration expression used to encode each configuration property.


Menus

The menus configuration property in Zed encodes the arrangement of menus and menu items that appear on the Math menu. The standard configuration file provides an extensive collection of predefined menus containing menu items for invoking virtually any of the editing transformations available to the user.

The expression encoding the menus configuration property consists of a list of menus. Each menu is itself a list, whose first element is the keyword menu, whose second element is the name of the menu, and whose remaining elements encode the subordinate menus and menu items that are to appear on the menu. The menu items are themselves represented as a list with two elements: the first is the text to appear on the menu items, the second is a symbol identifying the template rule to be invoked by the menu item. The text label for the menu item may contain special characters by enclosing the text in either single or double quotation marks. The template rule to be invoked may also be identified by giving a specification for a keyboard accelerator whose action will be invoked by the menu item.

The menus configuration property includes two special elements. The first special element is a specification for the empty menu named unknown that is used as a default menu under certain circumstances. The second special element is a specification for the structure of the Math menu. Typically these two entries are the only items appearing in the menus configuration property.

The menus configuration property can be accessed using the Zed Custom API methods using the section keyword menus.


Palettes

The palettes configuration property in Zed encodes the arrangement of each named palette, including the array of buttons that appear on the palette, and the editing transformation invoked when you click on the palette button. The standard configuration file provides an extensive collection of predefined palettes containing buttons for invoking virtually any of the editing transformations available to the user.

The expression encoding the palettes configuration property consists of a list of palettes. Each palette is itself a list, whose first element is the keyword palette, whose second element is the name of the palette, and whose third element is the description of the palette buttons. The palette buttons are specified as a list of lists, where each list starts with the keyword list, and where each element of the inner lists is either a symbol identifying the template rule to be invoked by the corresponding palette button, or a specification of a keyboard accelerator whose action is invoked by the palette button.

The palettes configuration property includes two special elements. The first special element is a list beginning with the keyword palette, the keyword Palette and followed by the names of each of the palettes that are to appear on the Palette menu. The second special element is a specification for the empty palette named unknown that is used as a default when an unrecognized named palette is requested through the Zed Custom API.

The palettes configuration property can be accessed using the Zed Custom API methods using the section keyword palettes.


Layout Rules

The layout rules configuration property in Zed encodes the layout transformations used to convert MathML content to MathML presentation. The standard configuration file provides an extensive collection of layout transformations that include rules for converting each of the content elements defined in MathML for presentation on the screen.

The expression encoding the layout rules configuration property consists of a list of layout transformations, encoded as rewrite rules. Each layout transformation begins with the keyword eq, followed by an expression encoding the left-hand side of the transformation, followed by an expression encoding the right-hand side of the transformation.

The left-hand side of a layout transformation consists of a pattern expression that specifies when to use the layout transformation. This pattern may take one of several forms. The pattern may be an empty list, matching any expression, which is used to supply a default layout transformation to use if no other rule matches. The default layout transformation in the Zed standard configuration creates an empty <mrow> element. The pattern may be the keyword unknown, which matches any atomic expression, and provides a default rule for creating character data. The pattern may be the keyword symbol, which matches any alphabetic atom, or number, which matches any numeric atom. Typically symbol and number atoms create character data that will be enclosed in either <mi>, <mo> or <mn> elements as appropriate. If the pattern is any other atomic symbol, the layout transformation provides a rule for displaying the symbol when it appears in operator position in an expression, usually as an <mo> element.

If the pattern takes the form of a non-atomic expression, a more general matching process is used to determine whether or not to use the layout transformation. The name of the operator must match exactly, as must the number of arguments, unless the special keyword * is used in place of the argument list, which matches all possible arguments. Other symbols in argument position in the pattern match a single child element of the current expression. Simple matching on attribute values can be achieved by replacing the operator name with a list consisting of the operator name, the attribute name, and the desired attribute value. Multiple attribute values may be matched by putting additional attribute name/attribute value pairs at the end of this list. Using the keyword * in place of the attribute value matches any expression where the attribute is explicitly given, regardless of its value.

The right-hand side of a layout transformation is essentially a Zed presentation expression that may contain MathML presentation elements, references to parts of the current expression, or one of a collection of other special forms used to express the rule for creating the presentation of the expression from the presentation of its child elements.

The layout rules configuration property can be accessed using the Zed Custom API methods using the section keyword layouts.


Template Rules

The template rules configuration property in Zed encodes the editing transformations used to transform one content expression to another during the course of editing operations invoked by the user. The standard configuration file provides an extensive collection of editing transformations that include templates for creating one or more variant forms for each of the content elements defined in MathML, plus additional editing transformations for associating keyboard accelerators with the editing transformations they invoke.

The expression encoding the template rules configuration property consists of a list of editing transformations, encoded as rewrite rules. Each editing transformation begins with the keyword eq, followed by an expression encoding the left-hand side of the transformation, followed by an expression encoding the right-hand side of the transformation.

The left-hand side of an editing transformation consists of a pattern expression that specifies how to invoke the editing transformation. This pattern may take one of several forms, but will always be a list. In its simplest form, this list may contain a symbol and the keyword +, where the symbol assigns a name to the editing transformation, which can be used to invoke the transformation by name. The transformation name may be preceded by a keyword such as infix that specifies that the editing transformation is only to be invoked when the current expression is in an infix editing context. Such keywords may be combined by enclosing them in a list; each of these context-specifying keywords must apply before the editing transformation is applicable. In place of the name of the editing transformation, a specification of a keyboard accelerator may be used to associate an editing transformation with an appropriate key binding which will invoke the transformation. Finally, the keyword + may be replaced by an expression pattern (as described above) that must match the current expression for the editing transformation to be applicable.

The right-hand side of an editing transformation is essentially a Zed content expression that may contain MathML content elements, MathML presentation elements, references to placeholder elements, or references to special built-in editing transformations described in the Operator Reference.

The template rules configuration property can be accessed using the Zed Custom API methods using the section keyword templates.


Traversal Orders

The traversal orders configuration property in Zed encodes, for each operator, the order in which its arguments are visited in an inorder traversal of the expression. Since the default traversal order for virtually all of the operators used by MathML can be successfully inferred from the presentation of the operator, the standard configuration file only overrides those operators for which the default traversal order is clearly inappropriate.

The expression encoding the traversal orders configuration property consists of a list of permutations. Each permutation is itself a list, where the first element is the name of an operator, and the rest of the list consists of integer indices encoding a permutation. The permutation will be applied to any expression using the named operator that has the correct number of child elements appearing in the presentation of the expression; the permutation determines the final order in which to visit each child element in an inorder traversal of the expression. A zero appearing in the permutation allows the permutation to be used for an expression with a given number of child elements, where one or more of the child elements is to be omitted in the traversal order.

The traversal orders configuration property can be accessed using the Zed Custom API methods using the section keyword orders.


Other Properties

The other properties configuration property in Zed encodes, for each operator, any special property that applies to the operator, with its value, as appropriate. The standard configuration file includes operator precedence information where needed, as well as information on which operators are to be considered as nary operators, associative operators, or array operators.

The expression encoding the other properties configuration property consists of a list of properties. Each property is itself a list, where the first element is the name of an operator, the second element is the name of a property, and the rest of the list gives the value of the property.

The properties assoc, nary, and array assert that the corresponding property is true of the operator, and require no additional information. The nary property, however, accepts the additional keyword binary declaring the operator will be treated as a binary operator taking two or more arguments, or two additional integer arguments detailing the minimum and maximum number of arguments accepted by the nary operator due to optional arguments. The properties prec, lbp, rbp, olbp, orbp all describe operator precedence information that can be specified with a single integer argument; higher numbers imply stronger binding power and therefore a greater need for parentheses in the presentation of child elements. The olbp and orbp properties concern the binding power of log-like operators in their enclosing context. The addop property declares that the named operator should be treated for purposes of display much like the additive operator <plus>; the single additional argument specifies the corresponding additive inverse operator that will be treated much like the additive inverse operator <minus>.

The other properties configuration property can be accessed using the Zed Custom API methods using the section keyword bindings.