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

Used for commands as well as text input. Here are the names for the special keys.

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 up and show more levels as you zoom in on a particular topic. This process is slowed when you have to move the mouse from the scroll bar up to the levels menu and back, so we have made it possible to scroll and change levels in a single operation. This works by using the (left) SHIFT and CTRL keys as modifiers of the left-click that causes scrolling up.

Old version of the file is renamed to have a "$" at the end of the extension so that you can retrieve it if necessary.

If the version of the file on the disk has a more recent create date than the document you are about to save, the system will tell you. This is to warn you about situations in which you load a file and while it is in a viewer transfer a more recent version to your disk.

If the click is done with the left button, the file is loaded into the "clicked" viewer and replaces the previous contents. If it is done with the middle button, a new viewer is created below the clicked one. Finally, if it is done with the right button, the clicked viewer is closed and a new viewer appears in its place.

If you use a remote file name, such as /Cedar/Documentation/TiogaDoc.Tioga, the system will fetch the file and make the viewer "ReadOnly". This lets you browse remote files and copy information from them. In future releases, Tioga will support editing of remote files.

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 simply selected <Interface>, and, if this succeeds, searches in the file for a definition of <Item>.

If the click is done with the left button, the "clicked" viewer is cleared. If it is done with the middle button, a new empty viewer is created below the clicked one. Finally, if it is done with the right button, the clicked viewer is closed and a new empty viewer appears in its place.

The empty viewer will say "No Name" at the top in the place that would normally hold the file name. Naturally the most common thing to do with a "No Name" viewer is to load a file. If you type a file name into a "No Name" 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.

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 (UnsavedDocumentsCacheSize); the default is four. Whenever there are unsaved documents, Tioga creates a special viewer listing their names.

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. "No Name" 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.

Find another instance of the selected text.

In this command and the following two, capitalization matters in the search (e.g., hitting Find with "the" selected will not select "The").

Find an instance of the selected text that is a "word" — i.e., doesn't have adjacent letters or digits.

Find a "definition" of the selected text — i.e., an instance of the selected text that is immediately followed by a colon and doesn't have an immediately prior 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.

If the document in this viewer does not contain the selection, scrolls to the start of the document. Otherwise scrolls to make the selection visible — 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.

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

Restore the most recent selection in this viewer and scroll to it.

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 one most recently extended.

The selection hierarchy consists of the following levels at which a selection can exist: 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. The system 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 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 it is automatically made pending-delete. Notice that you don't have to actually change the selection when you "extend" it. For example, you can middle-click to select a word and then immediately right-click 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. For example, the sequence MIDDLE-down, RIGHT-down, MIDDLE-up, RIGHT-up will produce a pending-delete word selection.

Source 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 source selection to the primary selection. However, often 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 control key still held down, select a source. 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.

Fine point: Unfortunately, our keyboards don't have both left and right quote keys. However most of the fonts, including TimesRoman and Helvetica, do provide a left and right single quote. The keyboard key inserts a right single quote (code 047); the left single quote (code 140) can be inserted using the MakeOctalCharacter command in the Edit Tool or with the Insert Matching Single Quotes command (CTRL-'). The Edit Tool also has a command which extends the selection to find a matching pair of left and right single quotes. The situation for double quotes is even less uniform. Some fonts, such as Classic, have a left double quote (code 264) in addition to a right double quote (code 042). However, most fonts have only the 042 double quote, so the Tioga commands for inserting and matching double quotes use that code exclusively.

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 Edit Tool. 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 Edit Tool.

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 Style commands 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. (Incidentally, 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.

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.

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 Edit Tool 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). 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 exeception is the "Stop" button which you can hit to terminate the process.

You can invoke a set of operations from the User Exec as well as directly from the Edit Tool. 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 Edit Tool switches to your favorite settings. For example, you could use the following to set up some of the search parameters: DoTiogaOps IgnoreCase MatchWords MatchPattern.

This section of the Edit Tool 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 Edit Tool, 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 Edit Tool 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. You may want to use this 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.

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. 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.

This section lists some of the formatting parameters currently supported. 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 procedures 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: