DragomanWaterlilyFile2.tioga
Pradeep Sindhu October 22, 1985 2:18:57 am PDT
Top level menu
Clear — creates an empty viewer.
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 — discards edits by reloading the filed version of the document.
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.
Get — loads the file named by the selection into a viewer.
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 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>.
GetImpl — like Get but loads the file that implements the selected interface name.
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>.
PrevFile — like Get but reloads the file that was previously in this viewer.
Store — like Save but writes to the file named by the current selection.
Store is also a guarded menu command like Reset.
Save — writes a new version of the file.
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.
A Comment Regarding `Unsaved' Documents
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 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.
Time — inserts the current time at the caret.
Split — creates a new viewer looking at the same document.
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).
Places, Levels — show/remove these submenus.
Places
The Places menu contains commands that cause the viewer to begin displaying at a new place in the document.
For the first three of the commands (Find, Word, and Def) commands, the button used in clicking the menu item determines how the search is carried out — LEFT-click to search towards the end of the document, RIGHT-click to search towards the start of the document, or MIDDLE-click to search first towards the end and, if that fails, then from the start of the document towards the selection. If the selection is visible in the viewer, the search starts there. Otherwise, it starts from the top of the viewer.
Find — find another instance of the selected text.
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.
Word — find an instance of the selected text that is a `word'.
A word is defined to not have adjacent letters or digits.
Def — find a `definition' of the selected text.
A definition is an instance of the selected text that is immediately followed by a colon and isn't immediately preceded by an alphanumeric.
Position — scroll to and select the character position indicated by the selected number.
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.
Normalize — scroll 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. If the document in this viewer does not contain the selection, scrolls to the start of the document.
PrevPlace — scroll to place that was previously visible.
Go back to the place that was previously visible in this viewer discounting manual scrolling that may have taken place since.
Reselect — restore the most recent selection in this viewer and scroll to it.
Levels
These commands in the Levels menu let you control how deep the display goes in the document tree structure.
FirstLevelOnly — show only the top level nodes.
MoreLevels — show one more level than currently.
FewerLevels — show one fewer level than currently.
AllLevels — show all levels of the tree.
Selections
Tioga performs its editing operations on selected portions of the document. The normal method of editing in Tioga is to make a selection and then request an operation. The selection may be changed at any time prior to requesting the operation be completed.
Two kinds of selections are most frequently used: primary and secondary. A third kind of feedback selection provides feedback for tools that manipulate Tioga documents, such as the debugger identifying the point in a source file corresponding to the current execution stack position by scrolling the source file document and posting a feedback selection.
Primary selections
The primary selection is the one that's around most of the time and is the usual site for edits. It is displayed with a solid underline or with video reverse. Make a primary selection with the mouse in ways described below.
Insertion point
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.
Secondary selections
The secondary selection is a selection made with the SHIFT key held down. It is displayed with a gray underline or with a gray background. Secondary seletions are often involved in Copy and Move operations.
Making selections
The selection hierarchy
The selection hierarchy consists of the following granularities: point, character, word, node, branch, and document.
Point selection
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.
Character 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.
Word 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.
Node selection
LEFT-double-click to select a node.
Branch selection
A branch is a node and any children branches it might have. MIDDLE-double-click to select a branch.
Document selection
CTRL-D extends the selection to include the entire document. `D' stands for for `Document'.
Selection extension
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.
Editing by making selections
Delete selections
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
`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
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.
Copy secondary to primary
If you hold down the SHIFT key and select, the source selection will be copied. If the primary selection is currently pending-delete, it will be replaced by the copy of the source. Otherwise, the copy will be inserted at the caret.
Move secondary to primary
If you hold down both the SHIFT key and the CTRL key, the source selection will be moved. As before, if the primary selection is pending-delete, it will be replaced by the source. Otherwise, the source will be moved to the caret.
Destination selections for Copy and Move
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.
Copy primary to secondary
To copy the primary selection, hit CTRL-S, and with the CTRL key still held down, select a destination. The copy takes place as soon as you let the keys up. The primary selection is made not-pending-delete as soon as you hit CTRL-S to indicate that it will be copied rather than moved.
Move primary to secondary
To move the primary selection, hit CTRL-Z, and with the CTRL key still held down, select a destination. The move takes place as soon as you let the keys up. The primary selection is made pending-delete as soon as you hit CTRL-Z to indicate that it will be moved rather than copied.
Transpose selections
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.
Miscellaneous
Cancelling a selection
Hit DEL before finishing the selection and the previous selection will be restored. This works during either primary, source, destination, or transpose selections.
Placeholders
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.
Select visible — expand selection to blanks
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.
Filed on: [Cedar]<Cedar6.0>Documentation>TiogaDoc.tioga
Select matching brackets
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.
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 quote key inserts a right single quote (code 047); the left single quote (code 140) can be inserted using the MakeOctalCharacter command in the EditTool or with the Insert Matching Single Quotes command (CTRL-'). The EditTool 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.
Editing
Text input
Typed-in characters are inserted at the caret.
To insert the current time use CTRL-T — `T' for Time.
When you insert a carriage return by hitting RETURN, the system will automatically copy the blank characters (tabs and spaces) from the start of the previous line. To suppress this, type SHIFT-RETURN and only the carriage return will be inserted.
To insert control characters or characters with a specific octal code, use CTRL-K or CTRL-O. The former will change the character before the caret to a control character, while the latter will convert the three digits before the caret to the corresponding octal character. The inverse operations are also available as CTRL-SHIFT-K and CTRL-SHIFT-O.
Abbreviation Expansion
CTRL-E — `E' for Expand abbreviation
When you hit CTRL-E, the caret is moved to the right of the selection if necessary and the keyname to the left of the caret is then replaced by the expansion text (according to the definition which is linked to the style in a manner described below). If the keyname had looks, they are added to the expansion. If the keyname was all caps, the expansion is made all caps too. If the keyname had an initial cap, the first character of the expansion is made uppercase (useful at the start of sentences, for example). If the definition node has a non-null format, the format of the caret node is changed to be the same as the definition node. If the expansion contains a placeholder, the first placeholder is selected. Otherwise the entire expansion is selected.
Definitions for abbreviations come from Tioga documents which are automatically read by the system when needed. The name of the appropriate abbreviations file is determined by the style that is in effect at the caret when the expansion takes place. For example, if the style is `Report', the abbreviations will come from the file `Report.Abbreviations'. You can override this by explicitly naming the abbreviations file along with the keyname. For example, `Mesa.proc' will expand the abbreviation for `proc' from the file `Mesa.Abbreviations' independent of the style in effect at the caret. (Fine point: Since the system interprets a period before the keyname to mean that you're specifying a particular abbreviations file, you cannot type a vanilla abbreviation after a period.)
Each definition in an abbreviations file consists of a separate branch. The top node of the branch holds the keyname followed by an equals sign and then the text expansion. The rest of the branch, if any, is copied after the caret node as part of expanding the abbreviation; if the text expansion following the keyname is empty, then the rest of the branch will be at the same level as the caret node, otherwise, the rest of the branch is nested underneath the caret node. Any text following the keyname is moved to the end of the last child node in the branch. The definition may also include a list of operations to be performed after the expansion has been inserted. These operations have the same format as those in EditTool and are placed in parentheses after the keyname and before the equals sign.
Delete Character or Word
BackSpace: CTRL-A, CTRL-H, or BS. Deletes the character to the left of the caret.
If the caret is at the start of a node, this does a Join command (q.v.).
BackWord: CTRL-W, or CTRL-BS. Deletes the word to the left of the caret.
DeleteNextChar: CTRL-SHIFT-A, CTRL-SHIFT-H, or SHIFT-BS. Deletes the character to the right of the caret up to the end of a node.
DeleteNextWord: CTRL-SHIFT-W, or CTRL-SHIFT-BS. Deletes the word to the right of the caret up to the end of a node.
Delete
As mentioned above, you can delete something by selecting it with CTRL held down. In addition, you can delete the current selection by hitting DEL.
Paste
Paste: CTRL-P. The most recently deleted text is copied to the caret. You can also use the EditTool to save the current selection to be pasted later.
Copy, Move, Replace, and Transpose
These operations are all carried out by making selections. They are described in detail in the previous section.
Insert matching brackets
CTRL-[ adds a matching pair of [..]'s to the ends of the selection. Similar CTRL commands exist for {, (, <, -, ', and ". CTRL-B inserts matching placeholder brackets .
Note: CTRL-' inserts a left single quote (code 140) and a right single quote (code 047); CTRL-" inserts the same character (code 042) at each end of the selection.
Case
All lower: CTRL-C. Makes the selection all lower case.
All caps: CTRL-SHIFT-C. Makes the selection all upper case.
First cap: CTRL-double C. Capitalizes the first word of the selection
Initial caps: CTRL-SHIFT-double C. Capitalizes each word in the selection.
Repeat
Hitting ESC will repeat the most recent non-empty edit sequence starting with the current selection. Edit sequences are separated by user-made selections. For example, if you select a word, delete it, type a new one, and then select something else, the edit sequence is delete followed by text entry. If you hit Repeat, the system will do a delete and retype the new word.
Auto-repeat is done by ESC-select: if you hold down the ESC key while making a selection, a Repeat will automatically be done as soon as the selection is completed. This is useful when you're doing a large number of repeats.
Undo
Hitting SHIFT-ESC undoes the most recent edit sequence and restores the selection to its prior state. If you want to undo more than just the most recent sequence, use the EditHistory tool which is described later.
Tree structure editing
As explained in the introduction, Tioga documents consist of a tree of nodes. The following commands let you break, join, and nest nodes in the tree.
Break: CTRL-RETURN — break node at insertion point to create a new node.
Join: CTRL-J — join node at insertion point with previous node.
Nest: CTRL-N — move selected nodes to deeper nesting level in tree.
UnNest: CTRL-SHIFT-N — move selected nodes to shallower nesting level in tree.
Break & Nest: CTRL-I — simultaneously insert a new node and nest it.
Break & UnNest: CTRL-SHIFT-I — simultaneously insert and unnest.
Looks
Characters have looks which are named by the lower case letters `a' to `z'. Looks are interpreted by the style to change the appearance of the text. For example, look `e' might stand for `emphasis' and might result in italic face in one style and bold face in another. Each character has a set of looks — thus it may have several looks simultaneously, but each look occurs only once. You can use the EditTool to read or change the set of looks for selected characters. The following keyboard commands are also available for dealing with looks.
Selection Looks
You can change the selection looks with the following commands. (Recall that the LOOK shift is the top blank key to the right of BS.)
LOOK-char to add to selection looks.
LOOK-SHIFT-char to remove from selection looks.
LOOK-space to remove all selection looks.
Caret Looks
Caret looks determine the looks of typed-in text. The caret picks up the looks of the adjacent selected text whenever a selection is made. Changing the selection looks also changes the caret looks. However, if you wish to change the looks of the caret without changing the selection looks, LEFT-click the character key twice in quick succession.
LOOK-char-char to add to caret looks.
LOOK-SHIFT-char-char to remove from caret looks.
LOOK-space-space to remove all caret looks.
Using Selections To Copy Looks
To copy the looks of some existing text to the primary selection, hit CTRL-Q, and then with the CTRL key still held down, select the text with the looks you want to copy. The source looks replace any looks the selection previously had.
Automatic Mesa formatting
The CTRL-M command scans the selection for Mesa keywords, comments, and procedure names and gives them looks k, c, and n respectively. (As a convenience during typein, the entire caret node is reformatted if the selection is a single character or less.) With the standard Cedar style, the keywords will then be displayed in small caps, the comments will be italic, and the procedure names will be boldface. We expect to provide more extensive reformatting capabilities in the future.
Formats
Just as characters have looks, nodes have formats. The `format' is the name of a rule in the style that tells how to modify various parameters when displaying the node. For example, a style for documents might contain formats for titles, headings, quotations, standard paragraphs, etc. The EditTool has facilities for reading and changing the format of a node, or you can use the commands described below. (By convention, the null format name is equivalent to `default'.)
Setting and inserting caret node format
CTRL-← will delete the word to the left of the caret and make it the format of the caret node.
In most cases you will give this command immediately after typing the format name, so the caret will naturally be in the correct place. However, to handle cases in which you select the name before hitting CTRL-←, the caret will automatically be forced to the right of the selection at the start of this command.
CTRL-SHIFT-← inserts the format name at the caret.
This gives you a simple way to find out the format of a selected node.
Using selections to copy formats
To copy the format of some exisiting node to the selection nodes, hit CTRL-F, and then with the CTRL key still held down, select the node with the format you want to copy.
The EditTool
The EditTool provides a variety of operations on Tioga documents.
The text fields in the EditTool follow the convention that clicking the field name with LEFT causes the contents of the field to be selected pending-delete while clicking with RIGHT causes the field to be cleared and selected.
Search and Substitute
Search
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.
Text — if this option is selected, match characters of target text when searching.
Looks — if selected, match looks of target text when searching.
Format — match format of target node.
Style — match style of target node.
Comment — match comment property of target node.
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:
1. Case of matching text
Match Case — matching text must have same case as target text.
Ignore Case — matching text does not have to have same case as target text.
2. Interpretation of target text
Match Literally — don't treat target text as a pattern.
Match as Pattern — do treat target as pattern. (Patterns are described below.)
3. Context of target text
Match Anywhere — ignore context of matching text.
Match Words Only — matching text must not have adjacent letters or digits.
Match Entire Nodes Only — matching text must span entire node.
4. Matching target looks
Subset as Looks Test — looks of matching text must include target looks.
Equal as Looks Test — looks of matching text must be identical to target looks.
Substitute
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.
If you pick Text and Looks, the matching text will be replaced just as if you had selected it with pending delete and made a source secondary selection of the replacement text.
If you pick only the Looks option, the matching text will have the target looks removed and the replacement looks added.
If you pick only Text, the replacement text will have the looks of the replaced text added to it. (Fine point: if the looks of the replaced text are not uniform, the looks of the first character will be used throughout.)
If you pick Format, the matching node will get the format of the replacement node. Similarly, picking Style causes the matching node to get the style of the replacement node, and picking Comment causes the matching node to get the same value of the Comment property as the replacement node.
The final three boxes in the Search&Substitute section give you further control over this operation.
1. First character capitalization of the replacement text
First cap like replaced — if the replaced text starts with a capital letter, force the first letter of the replacement to be a capital too.
Don't change caps — leave the replacement capitalization alone.
2. What is done to the matching text
Do Replace — do the usual substitute or replace.
Do Operations — instead of doing a replace, select the matching text and then do the operations currently in the `Operations' field of the EditTool.
3. Where the substitutions will take place
Within Selection Only — substitute is limited to current selection.
After Selection Only — substitute after selection to end of document.
In Entire Document — substitute in the entire selected document.
Case-by-Case Substitutes
In addition to doing global substitutes, you can decide on a case-by-case basis whether or not to replace the matching text by the new text. Use the search commands to find the first matching text. Then if you hit `Yes', the system will do a `Replace' followed by a search forward. If you hit `No', it will skip the `Replace' and simply do another search. Thus to selectively substitute, start with a search, then do `Yes' for the cases you want to change and `No' for the others. The `Replace' command simply does for the current selection what a substitute would do for a match. Finally, the `Count' command is available to tell you how many substitutions would take place without actually changing the document.
In order to do a search or substitute, you will typically need to fill in the Target or Replacement fields in the EditTool. Naturally, this changes the selection, and before you can do the operation, you must restore the selection to the place where you actually want it to take place. The system helps you with this by saving the primary selection if it is not in the EditTool when you LEFT-click either the Target or the Replacement button. The commands along the top of the EditTool — Search, Substitute, Yes, No, Replace, and Count — restore the saved selection if the primary selection is in the EditTool when they are clicked. The net effect is that if you start out with the selection in the right place, you can LEFT-click the Target or Replacement buttons, fill in the needed information, and then directly click one of the commands without needing to reselect since the system will do it for you.
Patterns for Search and Substitute
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.
Characters
 #  Match any single character.
 *  Match shortest possible sequence of characters.
 **  Match longest possible sequence of characters.
 '  Match the next character in the pattern exactly.
 ~  Match any character except the next one in the pattern.
Alphanumeric characters
 @  Match any single alphanumeric character (letter or digit).
 &  Match shortest possible sequence of alphanumeric characters.
 && Match longest possible sequence of alphanumeric characters.
Non-alphanumeric characters
 ~@ Match any single non-alphanumeric character.
 ~& Match shortest possible sequence of non-alphanumeric characters.
 ~&~& Match longest possible sequence of non-alphanumeric characters.
Blank characters
 %  Match any single blank character.
 $  Match shortest possible sequence of blank characters.
 $$  Match longest possible sequence of blank characters.
Non-blank characters
 ~% Match any single non-blank character.
 ~$ Match shortest possible sequence of non-blank characters.
 ~$~$ Match longest possible sequence of non-blank characters.
Miscellaneous
 |  Match start or end of node.
 {  Mark start of resulting selection.
 }  Mark end of resulting selection.
 <  Mark start of named subpattern.
 >  Mark end of named subpattern.
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
Target: WHILE <pred>[<arg>] DO
and the replacement is
Replacement: WHILE <arg> IS <pred> DO
then `WHILE blue[moon] DO' will be converted to `WHILE moon IS blue DO'.