The mouse has three buttons named LEFT, MIDDLE, and RIGHT corresponding to their physical layout.

The keyboard is used for commands as well as text input. Here are the names for the special keys:

The bottom right blank key is an alternative CTRL key. You can use either CTRL key and either SHIFT key interchangeably.

In a document such as this one that uses levels to reflect its logical structure, it is often useful to start with a view of the first level only and then progressively scroll the document and show more levels as you zoom in on a particular topic. This process is slowed when you have to move the mouse between the scroll bar and the levels menu, so we have made it possible to scroll and change levels in a single operation. This works by using the SHIFT and CTRL keys as modifiers of the LEFT-click that causes scrolling up:

If you LEFT-click the Clear button, the `clicked' viewer is cleared. If you MIDDLE-click the Clear button, a new empty viewer is created below the clicked one. Finally, if you RIGHT-click the Clear button, the clicked viewer is closed and a new empty viewer appears in its place.

In the viewer's caption (at the top, where the file name would normally appear), an empty viewer will display just a working directory, ending in `>'. An empty viewer produced by Clear inherits its working directory from the `clicked' viewer.

Naturally the most common thing to do with an empty viewer is to load a file. If you type a file name into an empty viewer and then hit LF, it is as if you selected the name and hit Get but no confirmation is required. CTRL-LF provides a similar function for GetImpl. You can also type a working directory name (ending in `>' or `/') and hit LF; this will simply change the working directory for the empty viewer.

Reset is a guarded menu command to prevent accidental loss of edits. The line through the menu item represents the guard. The first click removes the guard for a short time interval and posts a confirmation message in the window at the top of the screen. A second click while the guard has been removed executes the command.

If you LEFT-click the Get button, the file is loaded into the `clicked' viewer and replaces the previous contents. If you MIDDLE-click the Get button, a new viewer is created below the clicked one in the same viewer column. Finally, if you RIGHT-click the Get button, the clicked viewer is closed to make it iconic and a new viewer appears in its place.

If the selected name is a partial name (not beginning with `[' or `/'), Tioga interprets the name in the `clicked' viewer's working directory.

If the selected name does not include an explicit extension, Tioga will search for the file using a set of standard extensions. The default extensions are mesa, tioga, df, cm, config, and style. You can specify your own list of extensions with a user profile entry for SourceFileExtensions.

If the selected name contains a vertical bar ("|") followed by a position number, the feedback selection is set at the indicated position and document is scrolled to make it visible.

If the selected name is of the form <alpha>.<beta> and such a file exists, it is opened. Otherwise, if <beta> is one of the standard set of extensions, you will be informed that the file doesn't exist. However, if <beta> is not a standard extension, the system tries to open the file as if you had simply selected <alpha>. If this succeeds, it searches in the file for a definition of <beta> (see Def in the Places menu). This convention is intended for use with programs that have many instances of <Interface>.<Item> in which <Interface>.mesa is a file containing a definition for <Item>.

If the selected name does not include an explicit extension (i.e., there is no period in the selected text), Tioga will use a set of standard implementation extensions. Currently, mesa is the only default implementation extension. You can specify your own list of implementation extensions with a user profile entry for ImplFileExtensions.

If the selected name is of the form <Interface>.<Item> and an implementation for the item is currently loaded, the system will find the name of the file holding the implementation (our thanks to the Cedar runtime model for providing this information). Otherwise, the system tries to open the file as if you had selected <Interface>Impl, and, if this succeeds, searches in the file for a definition of <Item>.

Store is also a guarded menu command like Reset.

Tioga keeps 2 versions by default when it stores files, so you can retrieve the previous version if necessary. If the file has a keep property, then Tioga keeps that number of versions. Use the SetKeep command to change the keep property on a file.

It is not uncommon to forget to save the contents of a viewer before destroying it or loading something else into it. However this is not a disaster since Tioga holds onto `unsaved' documents so you can reload them with edits preserved. The number of such documents that Tioga will remember is set by a profile entry (named Tioga.UnsavedDocumentsCacheSize); the default is four.

Whenever there are unsaved documents, Tioga creates a special viewer named `Unsaved Documents List' containing the names of the unsaved documents. To retrieve a document with all the unsaved edits, select the entire filename, including a version number if one, and click Open in the system menu area at the top right of the screen.

Unsaved documents are put into the cache by Destroy, Clear, Get, GetImpl, and PrevFile. They are not put in by Reset. If the cache is already full when a new entry arrives, the oldest entry is discarded. Whenever a file is needed for Get, GetImpl, or PrevFile, the cache is checked to see if an unsaved version is available. Unnamed documents are not put into the cache.

The selection is highlighted in one viewer only, however edits will be reflected in all viewers for the document. Note that the split viewers can be independently closed, opened, or moved on the screen, and may be displayed at different levels of detail (see the Levels menu section).

In this command and the following two, the direction of search and capitalization are determined by the mouse buttons and SHIFT keys. LEFT-clicking searches forward from the current selection point; RIGHT-clicking searches backwards; MIDDLE-clicking does a wrap-around search by first searching forward to the end of the document then searching from the beginning until the entire document has been searched. By default, the search matches capitalization. Clicking with the SHIFT key down invokes a `caseless' search in which capitalization does not matter.

A word is defined to not have adjacent letters or digits.

A definition is an instance of the selected text that is immediately followed by a colon and isn't immediately preceded by an alphanumeric.

This is useful with compiler error messages that give locations as character counts. The command scrolls to the selected character number and then selects it — e.g., if `183' is selected, scroll to and select character number 183 in the document.

Compiler error messages give locations that exclude comment nodes. For error messages that include comment nodes, such as those from the TSetter, select the number and SHIFT-click Position to include comment nodes.

LEFT-click to scroll to the start of the selection, RIGHT-click to scroll to the end, or MIDDLE-click to scroll to the caret. If the document in this viewer does not contain the selection, scrolls to the start of the document.

Go back to the place that was previously visible in this viewer discounting manual scrolling that may have taken place since.

LEFT-click to get screen style (legible on screen). RIGHT-click to get print style (fonts, spacing, line breaks more closely match printed output). Note that different style kinds may be used in different viewers on the same document.

The insertion point goes with primary selection. It is shown by a blinking `caret' at one end or the other of the selection — the end closer to the cursor when the selection was made or the end most recently extended.

The selection hierarchy consists of the following granularities: point, character, word, node, branch, and document.

The primary selection has a blinking caret at one end. Some operations, such as delete and type-in, reduce the selection to just the caret. This is called a point selection.

LEFT-click with the cursor over the desired character. You can hold the LEFT button down and move to the correct place before letting the button up.

You can cancel the new selection by hitting DEL while the mouse button is still down. Tioga will restore the previous selection.

A `word' is defined as a sequence of letters and digits or a sequence of identical characters that are not letters or digits. Use the MIDDLE mouse button to make word selections. As with character selection, you can hold MIDDLE down and move to the correct word before letting up.

LEFT-double-click to select a node.

A branch is a node and any children branches it might have. MIDDLE-double-click to select a branch.

CTRL-D extends the selection to include the entire document. `D' stands for for `Document'.

Extend an existing selection by pointing at a new endpoint either before or after the selection and RIGHT-clicking. The system will extend the end of the selection closer to the cursor when RIGHT goes down. You can hold RIGHT down and move the endpoint to a new position.

If you just RIGHT-click, the selection is extended at the same level in the selection hierarchy. For example, a selection at the word level will be extended a word at a time. Double-RIGHT-click to extend at a lower level in selection hierarchy. Triple-RIGHT-click to extend at a higher level in selection hierarchy. Thus, if you have a node-level selection and wish to extend it to a word position within a node, double-RIGHT-click to reduce the level to words and then do the extension. If necessary, you can then double-RIGHT-click again to reduce to character level.

A delete selection is deleted as soon as the selection is completed. It is shown as video reverse. Hold down CTRL to make a delete selection. The selection is complete when you let up on both the mouse button and the CTRL key.

`Pending-delete' selections are automatically deleted by subsequent insertions. They are shown with video reverse rather than solid underline. Whenever you extend a selection by RIGHT-clicking, the selection is automatically made pending-delete. Notice that you don't have to actually point to a new place in the text to `extend' a selection. For example, you can MIDDLE-click to select a word and then RIGHT-click without moving the mouse to make it pending-delete. Or you can combine these actions by `rolling' from the LEFT or MIDDLE mouse button to the RIGHT button to make a char or word selection pending-delete.

Copy and Move operations require two selections, one for the source of the operation and the other for the destination. The Primary and Secondary selections are used for these. Secondary selections are made with the SHIFT key held down and are shown with a gray underline.

The operations described above work by copying or moving a secondary selection to the primary selection. However, sometimes the primary selection is itself the thing you want to copy or move. The following two commands take care of these situations.

We now have covered commands to copy or move either the primary or the source selections. A final option is to transpose the primary and the source. To do this, hit CTRL-X, and with the CTRL key still held down, select a source. The primary selection is made pending-delete as soon as you hit CTRL-X to indicate that it will be moved rather than copied. The transpose takes place as soon as you let the keys and mouse buttons up.

Hit DEL before finishing the selection and the previous selection will be restored. This works during either primary, source, destination, or transpose selections.

A `placeholder' is all the text between a matching pair of placeholder brackets,
. Hit NEXT to find and select the next placeholder beyond the current selection. Hit SHIFT-NEXT to find the previous one. Recall that NEXT is the blank key to the right of RETURN.

If there isn't another placeholder, NEXT will move the selection to the end of the document. If the selection is already at the end, NEXT will try to find the next nested text viewer. Similarly, SHIFT-NEXT will move the selection to the start of the document if it doesn't find a previous placeholder and will try to find the previous nested text viewer if it is already at the start. This allows you to use NEXT both when filling in placeholders within a document and when filling in text viewers in tools.

CTRL-V expands the selection to include the `visible' characters on the left and right ends.

This is useful for selecting things like full file names. For example, in the following you could make a character selection anywhere in the name and then extend the selection with CTRL-V.

CTRL-] extends the selection to the left and right to find a matching pair of [..]'s. Similarly for CTRL-}, CTRL-), and CTRL->. Note that you hit CTRL with the right bracket to extend the selection. In addition, you can hit CTRL with the left bracket to insert matching brackets around the selection.

To do a search, enter the text you're looking for in the `Target' field, select where you want the search to start, and LEFT-click `Search' to search forward, RIGHT-click to search backwards, or MIDDLE-click to search first forward then backwards. The system searches from the current selection and updates the selected viewer if the search succeeds. (Fine point: in both searches and substitutes, the match is limited to a single node — we do not yet have mechanisms for doing matches across node boundaries.)

The multiple choices below the `Replacement' field control what is matched in searches and replaced in substitutes. You can select or deselect an item by clicking it with the mouse. White text on black background means that the item is selected; black text on white means it is not selected.

For example, if you pick the Looks option and deselect the Text option, you can search for any text that has a particular set of looks. If you pick only Text, the matching will ignore the looks of the target. If you pick Text and Looks, the matching text must match both the characters and the looks of the target text.

The other options deal with node properties. If you pick Format, the matching will be limited to nodes with the same format as the target node. Similarly, if you pick Style, the matching will only look at nodes whose style is the same as the target node's. Finally, if you pick Comment, the match will consider only nodes with the same value of the Comment property (TRUE or FALSE) as the target.

The first two rows of boxes below the multiple choices give you control over how matching is performed. LEFT-click with the cursor over a box to change the choice next to it. The various choices are as follows:

To do a substitution, enter the new text in the `Replacement' field, enter the text to be replaced in the `Target' field, and hit `Substitute' in the menu at the top of the EditTool. The Text/Looks/Format/... options guide the search in the usual manner and also control what is replaced.

The final three boxes in the Search&Substitute section give you further control over this operation.

When you specify that the target be matched as a pattern rather than literally, the following symbols in the target text are interpreted specially. A short summary of these symbols appears at the bottom of the Search&Substitute section of the EditTool.

The named subpatterns are of use in substitutes that reorder or duplicate parts of the matching text. The full syntax for a named subpattern is <name:subpattern>. The special case of `match any sequence of characters' is provided as a default — i.e., <name> is equivalent to <name:*>. As far as the matching is concerned, the occurrence of <name:subpattern> is the same as if the subpattern had appeared without a name, but it has the side-effect of remembering the subsection it matched. The `Replacement' field can contain <name>s corresponding to named subpatterns in the target. The replacement text is constructed by replacing the <name>s with the section of replaced text that matched the subpattern. The replacement is automatically considered to be a pattern whenever the target is — you don't need to do anything special to get the <name>s in the replacement interpreted as subpatterns.

For example, if the target is

and the replacement is

then `WHILE blue[moon] DO' will be converted to `WHILE moon IS blue DO'.

The Looks commands let you read and modify the looks of the caret or the selection. The looks are shown as a series of letters in the `Looks characters' field. The box lets you pick whether you want the looks for the selection or the looks for the caret.

The Format commands let you read and modify the format for the root node or the selected nodes. The box at the right lets you pick the case you want.

A style is a collection of interpretations for looks and formats. The definition of style rules are described later in their own section. The Style commands in the EditTool let you read and modify the name of the style for the root node or the selected nodes. The new style applies to the specified node and all the nodes within its sub-branches that do not themselves have explicit styles.

A node can have an arbitrary set of `properties'. Each property consists of a name and a value. Certain properties are used by the system, but you (and your programs) are free to add others.

The `Property name' field specifies the name of a property. Case distinctions do matter in property names — `foo' is a different property than `Foo'. The `Property value' field specifies a value. The box lets you pick whether you are talking about properties of the root node or the selected nodes.

Properties may also be applied at the character level; click the box until it says "For selected characters". Character properties are not always interpreted the same way as the node properties, but the Postfix property (see below) works for both.

In addition to setting and reading properties, there is a mechanism that lets you find nodes with a certain property value. For example, if you have annotated a document with comments under the property name `MyOpinion', and you want to find nodes in which your comment included the word `good', enter the name in the `Property name' field and the text in the `Value pattern' field. Then use the `Find' command to search forward or backwards from the caret node for a node with a value of the property that matches the pattern. (LEFT-click to search forward, RIGHT-click to search backwards.) Value patterns can use the standard set of special characters for searches. If a match is found, the node is selected and the property value is displayed.

Tioga and some other commonly-used programs use several property names for representing structure. Many of these have values that are simply human-readable character strings, but some are meant to be read and written only by programs, and so you should not try changing them with the EditTool unless you really understand what you are doing. Others are non-persistent (i.e. do not get saved in files) and are read and written only by programs. Note that programs other than Tioga may register new kinds of properties, so the list here is not exhaustive. The reserved properties are:

All nodes have a `Comment' property which is either `TRUE' or `FALSE'. If its value is TRUE, the text of the node is not seen by programs such as the compiler that are only interested in the basic text contents. This makes it possible to intermix documentation and program text without requiring special escape characters to mark the start and end of comments. You can set the Comment property by using the EditTool or with the following commands.

These commands let you sort or reverse lists of things. The `Sort' command sorts things in alphabetical order, ignoring case. `Sort-and-remove-duplicates' is useful when you are merging sets of things. The box below the Sort button lets you pick whether you want increasing or decreasing order in the result. The right box lets you pick what will be sorted: text delimited by blanks, lines delimited by carriage returns, or branches of the document tree. Leading blanks are ignored when sorting lines or branches.

These commands let you construct simple edit macros. The `Operations' field holds a text description of a command sequence. The `GetLast' command fills in the Operations with the description of the most recent sequence, i.e., the one a Cancel would cancel or a Repeat would repeat. `Do' executes the description in the operations field. `Begin' marks the start of a command sequence. `End' fills the Operations with the description of the commands since the most recent `Begin'. `SetCom' stores the operations under the CTRL-number key for the number in the `Command [0..9]' field. Conversely, `GetCom' fills the `Operations' field with the current CTRL-number definition.

To see how this works, select the following word: `hello'. Hit DEL and type in `howdy'. Now hit the `GetLast' button. The Operations field should now contain: Delete `howdy'. Edit the Operations field contents to replace `howdy' by `goodbye', then hit the `SetCom' button (first put 1 in the Command field if it's not already there). Now select the `howdy' you typed earlier and hit CTRL-1. If all went well, the `howdy' will have been deleted and `goodbye' inserted in its place. More examples of edit macros will be given later.

You can use the EditTool to look through a list of files for one in which the current search specifications are satisfied. This can be accomplished by clicking the `SearchEachFile' button after filling in the `Files' field with the file names (or `@' followed by the name of a file that holds the list of file names). You can also specify a working directory for file lookup by filling in the `Working Directory' field. When you LEFT-click SearchEachFile, a new viewer is created, and one-by-one the files will be loaded and searched until a match is found. The list of files will be updated when a match is found, so that when you are finished with one file you can LEFT-click SearchEachFile again to look for the next one. You can hit the `Stop' button at the top of the EditTool to interrupt the search, but you should not try doing other operations while the search is in progress since it resets the selection each time it loads a file.

Occasionally you will want to apply certain operations to an entire set of files. You can do this by filling in the `Operations' field and the `Files' field, and then clicking `DoForEachFile'. A new viewer will be created, and one-by-one the files will be loaded, selected, edited, and saved. No confirmation is required for the saves, so the entire process can go on without you. In fact, you should not try to do anything else while this is going on since the operations use the primary selection. The one exception is the `Stop' button which you can hit to terminate the process.

For example, to replace the word "apple" with the word "banana" in a number of files in directory ///Users/YourName.pa/Play/, type "apple" for Target, "banana" for Replacement, "DoSubstitute" for Operations, a list of short file names for Files, and "///Users/YourName.pa/Play/" for Working Directory. Click the DoForEachFile button and find something else to do while Tioga makes the substitutions. Note: You probably want to select "Match Words Only", particularly if you are replacing "Scene" by "OBScene", so that no harm will be done if you process the same file twice.

You can invoke a set of operations from a command tool as well as directly from the EditTool. When you run TiogaExecCommands, one of the commands it registers is DoTiogaOps which expects a command line containing operations in the same format as in the operations field. One possible application of this is to create a command file that initializes various EditTool switches to your favorite settings. For example, you could use the following command to set up some of the search parameters: DoTiogaOps IgnoreCase MatchWords MatchPattern.

This section of the EditTool contains buttons for all the basic edit commands. These are useful if you can't remember what keys to hit for an infrequent command or if you've set your user category to beginner or intermediate to filter out certain commands. Many of the buttons correspond to commands that have been documented above. However, a few of them are primarily of use in constructing edit macros and have not been mentioned before. For completeness, all the buttons will be given a brief description.

A few examples should get you started writing your own edit macros. First, assume you find yourself doing a lot of edits of the form <stuff> becomes <pred>[<stuff>] for various values of <stuff> and <pred>. You might like a single command to insert the brackets and move the caret to the place where you will insert the <pred>. To construct such a command, first select a particular <stuff>, hit the Add[ ] button in the EditTool, the CaretBefore button, and the GoToNextChar button using the right mouse button. Then hit GetLast to fill the Operations field, enter `1' in the `Command [0..9]' field, and hit SetCom to save the macro definition. Now you can select <stuff>, hit CTRL-1, and be ready to insert before the left bracket.

A macro to delete matching parentheses will show the use of the SaveSel and RestoreSel commands. Make a selection anywhere inside a pair of matching parens. Give the following sequence of commands: (...) to extend the selection, CaretAfter to position the caret at the right, SaveSel-A so we can restore the selection later, BackSpace to delete the right paren, RestoreSel-A to get the selection back, CaretBefore to move the caret to the front, and finally DeleteNextChar to delete the left paren. Now you can hit GetLast and SetCom to save this macro.

Other operations on the EditTool can also be programmed using edit macros. For example, assume you want a macro to substitute `which' for `that'. The following set of commands will load the target and replacement fields and do the substitute: RIGHT-click to select and clear the target field, type `that' as the target text, RIGHT-click to select and clear the replacement field, type `which' as the replacement text, and finally hit the Substitute button. This macro will only change the target and replacement fields. The other parameters of the substitute are not changed and thus behave like `free variables' of the macro. If you want to bind more of the choices, such as Match Case or Ignore Case, you simply include those commands as part of the macro. For example, you could select Ignore Case just before restoring the selection, and the macro would always set the ignore case flag when it was executed. Note that you must hit the `Target' and `Replacement' buttons to enter the target and replacement text. Directly selecting in those fields would not produce a correct macro because it would terminate the edit sequence and would also fail to identify which field was being filled in.

When you save an edit macro under a CTRL-number key, it only stays around for the rest of the session. If you want to save one for tomorrow, you can of course copy the operations to a file and redefine it another time. But if you really want to make a macro a permanent part of your user interface, you can add it to your `TIP table' which describes the translation from keyboard and mouse actions into executable tokens such as those in edit macros. The details of how to do this are given in a later section.

The values of these properties are command sequences that might be part of a formatting procedure. The Prefix commands are executed just before the standard formatting procedure for the node, and the Postfix commands are executed just after it. This makes it possible to modify the values of the formatting parameters that are the input and output of the format.

The primary use of Prefix properties is for specifying the style on a document or branch. You may want to Postfix properties to make local formatting changes, such as modifying tab stops for a particular table. However, don't abuse this facility. If you find you are making many local changes, you should probably modify the style instead.

It is also possible to put Postfix properties on characters; these get applied after the looks.

In typical use, a style lives in its own file and is referred to by the various documents that use it. However, in some cases you may have a style that is only used in one document, and you'd like to include it as part of the document to avoid the trouble of maintaining the style as a separate file. You can do this by using the StyleDef property. The value of this property is a style definition without any node structure or formatting looks. The style is automatically saved and loaded as part of the file and applies to the node and its children just as if you had set the node style in the usual manner with the EditTool.

You may want to define a new style that is only slightly different than an existing one. One approach would be to copy the existing style and edit it to make the changes. However, it may be preferable to track whatever modifications to the other style that may happen in the future. This can be done by `attaching' the old style to the new one. For example, if your new style includes a command of the form

then the new style will automatically include everything from the current version of Cedar style. Thus, if a format is not defined in the new style, it will be taken from Cedar style instead.

The basic form for a rule definition in a style is

In many cases it will be desirable for a rule definition to be different depending on whether the output is for printing or for display. To simplify this, you may define a format both as a ScreenRule and as a PrintRule. The ScreenRule definition will be used for display, while the PrintRule will be used for printing. If there is only a StyleRule definition, it will be used for both printing and display.

Style rules should be used only to change style parameters; they should not use what's on the stack, and should not define or re-define anything that persists after they are done. This needs to be the case so that caching of the results can be done. Some attempt is made to enforce these rules.

Names in JaM are always case-sensitive. Format names are always converted to lower case before lookup. To make this work, StyleRule and friends register with both the literal name, and the name converted to all lower case. Thus if you define "MyFormat", it can be invoked by the name "myformat" or by "MyFormat", but not by "myFormat". You don't often have to think about this, but it can lead to some mysterious behaviour if you don't know about it. To ease layering of styles, style rules are also registered under names like "stylename.myformat" (all lower case). For example,

This section lists some of the formatting parameters. Those that are recognized by the style machinery but are not currently implemented are in strikeout type. Typically, the name of the parameter is a command defined in JaM that pops an item from the stack and makes it the new parameter value. However if the item on the top of the stack is the word `the', the commands push the current parameter value, so style rules can read parameters as well as write them. For numeric parameters, the following mechanisms are provided to simplify making incremental changes to the current parameter value:

The conditionals provided by JaM (namely .if and .ifelse) are a bit clumsy to use and hard to read; to alleviate this, the style machinery provides constructs of the form