EditorComfortsDoc.tioga
Copyright Ó 1985, 1986 by Xerox Corporation. All rights reserved.
Russ Atkinson (RRA) May 14, 1986 5:23:20 pm PDT
Spreitzer, December 10, 1985 4:08:45 pm PST
Doug Wyatt, December 9, 1986 5:02:12 pm PST
EDITOR COMFORTS
CEDAR 6.1 — FOR INTERNAL XEROX USE ONLY
Editor Comforts
-- A package to enhance the Tioga editor
Russ Atkinson
© Copyright 1985, 1986 Xerox Corporation. All rights reserved.
Abstract: This document describes a collection of facilities that generally fall under the category of creature comforts: they are not essential, but they make life more pleasant. These facilities are enabled by running EditorComforts.bcd, e.g. by including EditorComforts.bcd in the PreRun entry in your user profile or by including "Run EditorComforts.bcd" in the CommandTool.BootCommands entry. In addition, some of the facilities can be parameterized, or disabled, via various user profile entries described below.
Created by: Russ Atkinson, Warren Teitelman
Maintained by: Russ Atkinson <Atkinson.pa>
Keywords: Tioga
XEROX  Xerox Corporation
   Palo Alto Research Center
   3333 Coyote Hill Road
   Palo Alto, California 94304

For Internal Xerox Use Only
Overview
EditorComforts is a package that enhances various functions of the Tioga editor in the Cedar environment. These extensions are:
Extensions to file saving for the purpose of updating the "last edited" date traditionally at the head of a file.
The (C) menu button adds a Xerox copyright notice to files, or updates an existing Xerox copyright notice. Copyright notices are recommended for all files, and should be added if the files are the property of the Xerox Corporation.
Extensions to file saving for the purpose of maintaining a change log traditionally at the end of a source file. This optionally includes a master change log and a session change log. Change log entries can be forced by the Log button.
Extensions to abbreviation expansion for the purpose of automatically generating argument lists.
Extensions to searching, in that the previous search value is remembered for use when the current selection is empty.
Extensions to positioning, so that positions can be reported as well as set, and recognition of the fact that we are dealing with ranges of positions.
EditorComforts was originally called NewStuff, and the first version was created by Warren Teitelman.
Updating Last Edited Entry
When you left click Save on a Tioga document, EditorComforts will search for a comment containing a date and your name, and if found, will automatically update the date. The algorithm used is as follows: start searching at the beginning of the document looking at all comments, where a comment is either a tioga node with the comment property, or any line beginning with -- or //, (i.e. this feature also works equally well for documents that have not been converted to Tioga node structure). In each comment, look and see if the user's name appears, and if there is also a date. Stop searching at the first non-comment node. If a comment of the appropriate form was found, update the date of the last such comment (so that user can have a separate CreatedOn comment). Otherwise, provided that at least one comment was seen, insert a new comment of the form user, time, following the last "Last edited by:" comment, or following the last comment if there is none. If the user profile has an entry EditorComforts.LastEdited, then the contents of that entry is used instead of the user name for the comment, thereby allowing nicknames or full names. If the user profile has an entry EditorComforts.UpdateLastEdited: FALSE, then this feature will be disabled.
Xerox Copyright Notices
Clicking the (C) button causes a Xerox copyright notice to be inserted after the first non-blank line of the file being edited. Clicking (C) will also update such a notice if it does not contain the current year. A copyright notice is recommended for all files that are the property of the Xerox Corporation. The copyright message is
Copyright ý 1986 by Xerox Corporation. All rights reserved.
Updating Change Logs
A facility for automatically generating change log entries for documents that employ Tioga node structure is available through the Log menu button, which is added to the first menu line of all Tioga documents as a result of running EditorComforts.bcd. Left clicking Log will cause the system to create a change log entry at the end of the document being edited. The entry consists of a Tioga node of the same form as the "last edited" comment, followed by a nested node beginning with "changes to:", followed by a list of the items changed. PlaceHolders for comments are inserted following each item. (Filling in these comments is optional: any placeHolder in the change log entry that is not filled in will be automatically deleted when the file is saved.)
The changed list is generated as follows: for each Tioga node that has been edited, add an entry to the changed list, if one does not already exist, corresponding to the first (most tightly bound) type declaration that this node is under. Only consider type declarations which contain a block as part of its definition (i.e. local variable declarations of a procedure that are edited do not rate separate entries, local procedures do). If there is no such declaration, e.g. the edit is to the DIRECTORY list, or to some expression in the start code, etc., use the highest node that is not a comment. If there is such a declaration, and it is local to some higher declaration, indicate that declaration also when printing the change entry.
For example, if User edits the file Grumble.mesa by changing: (a) several of the DIRECTORY clauses, (b) the IMPORTS list, (c) the top level declaration for the type UnderLongString, and (d) the procedures EnsureInit, PutCardRope, and innerPut, the latter two of which are local procedures, the change log entry that would be produced would look like:
User, January 3, 1985 6:49:46 pm PST
general comments
changes to: DIRECTORY, IMPORTS, UnderLongString, EnsureInit, PutCardRope (local of Print), innerPut (local of PutRecord, local of Print)
Continuing an edit "session"
A new change log entry is created only once for a particular edit session. This change log entry is said to be active as long as the corresponding document exists, and the corresponding node is part of that document, i.e. has not been deleted. In other words, the system will continue to treat edits as part of the same session as long as the user edits in the same viewer (or a viewer created as a result of splitting this viewer), and as long as the corresponding change log entry still exists. In this case, when the user clicks Log or Save (see below), a new change log entry is not created, but instead the active change log entry is updated by appending those entries that were not previously written to it at the end of the entry.
Thus the user can edit comments in the change log entry and when that entry is subsequently updated, the comments will not be touched.
Often a single edit session will logically span several boot or rollback operations, e.g. the user makes some edits, recompiles, rollsback, reloads the file, discovers some additional problems which require more editing. In this case, it is desirable to have the latter set of edits look as though they had been performed in the same session as those performed a short while previously. In order to accomodate this behaviour, if a previous change log entry is found, and this entry is dated within 24 hours of the current time, the current set of changes will be merged with those in the previous entry, i.e. the effect is the same as though they occurred in the same edit session.
The test for whether or not such an entry exists is to search backwards from the end of the file looking at nodes with comment properties. If a node is found which contains a date, and one of the node's children begins with the characters "changes to: ", then the test succeeds. The test fails at the first non-empty, non-comment node.
The user can override the merging of change logs and force a new change log entry by middle clicking Log. Similarly, the user can explicitly request merging with the previous change log, even if more than 24 hours have elapsed (e.g. to continue Friday afternoon edits on Monday morning) by right clicking Log.
Note that if the user clears or destroys the viewer, and then subsequently opens another viewer on the same document, or if the user deletes the active change log entry from the document, the effect is the same as though the user had booted or rolledback, i.e. a new session is started unless the previous change log entry occurred within 24 hours, etc.
Saving the file
In many situations, the user does not want to insert any comments in the change log, but simply wants to save the file with the list of changes. Rather than forcing the user to first click Log and then click Save, in those cases where the user has already indicated that he wants a change log maintained for this file, either by virtue of having previously created one by clicking Log, or by an appropriate declaration in his user profile, the user can simply click Save. Thus
(a) If there is an active change log entry, left clicking Save will update it, i.e. is the same as left clicking Log and then doing the save.
(b) If the user has an entry in his profile of the form EditorComforts.UpdateChangeLog: addIfPrevious (the default), and a change log entry was inserted by this facility in some previous edit session, then merge the two entries if their times are within 24 hours, otherwise create a new entry.
(c) If the user has an entry in his profile of the form EditorComforts.UpdateChangeLog: createNew, and the file looks like a mesa file, then proceed as in (b).
The test for this is to search backwards from the end of the file for the first non-empty, non-comment node. This node must begin with the characters "END.". Note that this test will always fail for files that do not use Tioga node structure.
(d) Right clicking Save will simply cause the file to be saved without doing anything to the change log (or the last edited date), regardless of your user profile, and regardless of whether a change log entry is currently active.
Summary
Left Click Log
If there is an active change log entry, update it, otherwise if there is a change log entry in the file created within the past 24 hours, merge with this entry, otherwise create a new change log entry.
Middle Click Log
Create a new change log entry.
Right Click Log
Merge with previous change log entry if one exists,, regardless of when it was written, otherwise Create a new change log entry.
Left Click Save
If there is an active change log entry, update it, otherwise, if UpdateChangeLog = addIfPrevious, and there is a previous change log entry, create a new one (or merge with previous one if within 24 hours, otherwise, if UpdateChangeLog = createNew and file looks like a mesa file, create a new one or merge with previous one if within 24 hours.
Right Click Save
Just write out the file.
EditorComforts will never alter change log unless one of the following occurs:
(1) You explicitly click Log.
(2) You explicitly clicked Log once before in this edit session.
(3) Your user profile contains EditorComforts.UpdateChangeLog: addIfPrevious (the default), and there is already at least one change log entry there of the recognized form. In other words, in this mode, you have to start each file off with a change log the first time by explicitly middle clicking Log.
(4) Your user profile contains EditorComforts.UpdateChangeLog: createNew, and the file looks like a mesa file. In other words, in this mode, change logs will automatically be started for you, but only if the file looks like a mesa file with node structure.
The system will never add duplicate entries to the change log.
The system will never disturb any changes that you make by hand to your change log, e.g. editing comments.
Remember: this facility is designed to be used ONLY in conjunction with Tioga node structures. The change log will be singularly uninteresting for a flat structured document, since all of the changes will appear to be at the same place.
Master Change Log
A facility for generating a log of all of the files that you save during a session is automatically enabled when EditorComforts.bcd is loaded when there is a user profile entry EditorComforts.ChangesLog: name or EditorComforts.SessionLog: name This log is kept on the file name, which is created when it is first needed. Each time you save a file, the date, file name, and changes log entry that was inserted in your file via the facility Updating Changes Log discussed above, if there is such an entry, is added to this log.
Extensions to Abbreviation Expansion
CTRL-E can now be used following any expression whose value is of type procedure, record, error, signal, etc., i.e. any type whose syntax involves square brackets and named fields, to generate an appropriate "form" for that expression. For example:
Rope.Find{CTRL-E}
==>
Rope.Find[s1: ROPE, s2: ROPE, pos1: INT ← 0, case: BOOL ← TRUE]
IO.Error{CTRL-E}
==>
IO.Error[ec: IO.ErrorCode, stream: STREAM]
The user can move back and forth among the fields using {NEXT} (Spare2) and {SHIFT-NEXT} in the standard fashion. When finished with the form, he can type CTRL-NEXT which will have the effect of deleting any fields not filled in, plus advancing the caret to just beyond the terminating ']. For example:
Rope.Find{CTRL-E}r{NEXT}key{CTRL-NEXT}
==>
Rope.Find[s1: r, s2: key]
i.e., typing "r" filled in the first ROPE field, and typing "key" filled in the second ROPE field, and {CTRL-NEXT} deleted ", pos1: INT ← 0, case: BOOL ← TRUE" and moved the caret to after '].
Note that CTRL-E can also be used to construct forms when typing to the interpreter in a work-area (since typescripts are now editable).
Another useful application is typing CTRL-E following an expression whose value is a procedure type. The will cause the insertion of a comment describing the arguments and return values for the procedure type, and then an appropriate form for the procedure body. For example:
RedSave: Menus.ClickProc{CTRL-E}
==>
RedSave: Menus.ClickProc = {
[parent: REF ANY, clientData: REF ANYNIL, mouseButton: Menus.MouseButton ← red, shift: BOOLFALSE, control: BOOLFALSE]
Body
};
Since CTRL-E expansion involves the interpreter, it can be slow, especially the first time for a particular interface.
Remembering Previous Search
Whenever a Tioga document is searched via the Find, Word, or Def menu buttons, the target of the search is saved. If the target for this particular search, i.e. the current selection, is empty (i.e. a point selection), then the previous target is used instead. This enables searching for Foo, deleting it, and then searching for the next Foo by simply clicking the menu button again. It also enables searching for a particular target, changing the input focus in order to type something somewhere else, for example, to obtain a new viewer and load it with a particular file, and then searching again without having to reselect the target.
If you simply point and click in a viewer, you typically will obtain a character selection, rather than a point selection, unless you point at an empty node. One simple way to convert a character selection into a point selection is to simply type anything, e.g. a space.
Extensions to Positioning
Vanilla Tioga provides a button in the Places menu called "Position". EditorComforts extends the functionality of this button.
Position Ranges
In vanilla Tioga, a position is a character index into a text document (never mind that the position button displayed this as a range of four characters). EditorComforts recognizes that a position is a range of characters. Positions may now be specified in one of two ways: (1) the old way, which is a text string representing a number which is the index of the start of the range --- the end is 3 characters later, or (2) by a text string of the form "N1..N2", where N1 and N2 are the indices of the first and last character.
Reporting
When the Position button is clicked with the left mouse button, it behaves as before: the current Tioga selection is decoded as a position specification (may now use both forms of specification), and a feedback selection is made at the indicated range of characters in the document whose Position button was clicked. EditorComforts adds the inverse operation, reporting the indices for the current selection, in middle- and right-clicks on the Position button.
Middle-clicking the Position button causes a message to be displayed in the message window. This message tells what the range of indices are for the current Tioga primary selection. In some degenerate cases (selection covers 0 or 1 characters), the message will give only one number, otherwise it will give two.
Right-clicking the Position button causes the number(s) last displayed by middle-click to be inserted at the caret. They become the primary selection.
Both left- and middle-clicks need to know whether to count comment nodes. If the shift key is held down, they do; otherwise they don't.