1 VECCE E C C E F O R V I D E O S This version of ECCE combines the capabilities of a conventional context editor with many of the features of a screen editor. It is supported by the Department of Computer Science and comments are welcomed. EMAS users please view the important points in the section on IMPLEMENTATIONS. Hamish Dewar April 1983 For information on a particular command type INDIV followed by the name of the command. For a percent command type SPECIAL followed by the name. 2 INTRODUCTION ECCE is a text editor. Under the control of commands entered from a terminal keyboard, it carries out modifications to a body of text held in a computer file. This text file may be, for example, a source program in some high-level language, or tables of results generated by a statistical package, or data intended as input to a user's program; it may simply be material which is held in the computer filing system solely for the purposes of editing and listing. The differences between these kinds of text files are not in any way significant to the operation of the Editor. What ECCE cannot do is edit files which are not composed of lines of text, such as executable code files. 3 Text_files A text file consists of a number of lines, each line containing a number of characters. The characters making up a line are either printing characters or space characters. There is no need when typing in lines on a computer terminal, any more than on a conventional typewriter, to 'space' after the last printing character on a line, in order to pad lines out to a particular fixed length; RETURN suffices to mark the end of the line. The Editor regards lines as being of variable length, usually ending with the last printing character. Hence 'white' space at the right-hand end of a line is not part of the line, in the way that space at the left or within the line is, being made up of individual space characters (corresponding to depressions of the space-bar). Although these make no impact on the printed page or video screen, they are just as significant for editing as other characters. For example, the line: longing for those wide open spaces would look like this if the spaces were replaced by ampersands: &&&longing&&&for&those&&wide&open&&&&&&spaces A blank line is an empty line; that is, it contains no characters, not even spaces. Blank lines are just as significant for editing as other lines. The main function of the Editor is to enable the terminal user to make alterations to a file held within the computer system, but it may also be used to create a new file from scratch or simply to inspect a file without altering it. 3 The_file_pointer The operation of the Editor is directed by a series of commands which are carried out one after the other in the order typed. The effect of most commands depends partly on the position of a notional pointer which identifies the 'current position reached' in the file. Initially the file pointer is positioned at the start of the first line in the file. It may be moved along lines and down from one line to the next. It may be positioned at the start of any line, between any two characters on a line, or at the end of a line. It may also be positioned at the very end of the file, that is, after the last line of text. Many commands have no effect other than that of re-positioning the file pointer. The usual direction of movement is forwards, that is, from left to right along a line and downwards from one line to the next, but there are also commands which move the pointer backwards in the file. Commands which simply move the file pointer around will be called location commands; commands which actually change the material in the file will be called alteration commands. The typical pattern of use of the Editor is to go progressively through the file, using whatever location commands are most convenient to reach the next point at which a correction is required, and then use one or more alteration commands to effect the correction. 3 Feedback ECCE commands are usually typed on-line, that is, in interactive mode. After the execution of each complete command, some feedback is provided to the user. This enables the user to confirm whether the command has had the effect intended, before issuing the next command. The nature of the feedback depends on whether the Editor is being used from a hard-copy (printing) device or from a video terminal. As editors are increasingly being accessed in the latter way, the emphasis in most of this document is on that case. It is hoped that users of hard-copy devices (or videos used as hard-copy devices) will be able to ignore or re-interpret parts of the description which are not relevant to this mode of access. 4 Video In the case of videos, feedback is in the form of a 'window' displaying a group of consecutive lines in the file. As successive commands are executed, the window is updated so that it always includes the current line and so that the position of the pointer is indicated. Unfortunately video terminals vary considerably in terms of their capabilities and the way they are controlled. In consequence the fashion in which the window is updated and the pointer is displayed varies from terminal to terminal, and a particular implementation of the Editor will support only a particular selection of video terminals; others may have to be used as if they were hard-copy devices. The size of the window used for video feedback varies between a minimum and maximum number of lines, within a screen region which may be specified by the user. Whenever editing moves to a fresh site in the file, the display is completely re-written, with a minimum size window. Moving off the bottom or top of the window causes the window to be extended, when this is possible. A line which exceeds the window width is truncated rather than wrapped round on the display. The invisible characters can still be edited. Use the %R command to display the ends of long lines. For purposes of printing or display, the end of the file is shown as an extra line, beyond the last genuine line, in the form: **END** This line does not actually exist in the file and therefore cannot be edited. 4 Hard-copy_feedback In the case of printing terminals (or videos used as hard-copy devices), the feedback consists of printing out the current line, with the position of the file pointer indicated by insertion of a circumflex character (up-arrow on some terminals). However, this extra character is not included when the pointer is at the start of the line. Thus: here the file pointer is splitting ha^irs and: here it is at the end of the line^ but: here it is at the start of the line With slow terminals, it can be excessively time-consuming if the current line is printed out after every command is executed and there are options which may be selected to reduce the frequency of output. 3 Editing_modes There are two modes in which the Editor may be used from a video terminal, and the user may switch freely between them. They are command mode and data-entry mode. In data-entry mode the video cursor indicates the position of the Editor's file pointer and text typed at the keyboard goes directly into the file. There are two varieties of data-entry mode, REPLACEMENT, in which new material overwrites the existing text and INSERTION in which new material is inserted into the existing text. The only keys which have a command significance in data-entry mode are the control keys described in the following section. In command mode, the full range of VECCE commands is available. The Editor prompts for input in the command region of the screen and interprets the text typed as an editing command. However, in command mode (in most implementations), the actual video cursor is pre-empted for use in the command region of the screen and a variety of alternative means are used to indicate the position of the Editor's file pointer within the file region. This may be in the same form as the video cursor but the choice is limited by terminal capabilities. Often reduced or increased intensity has to be used; in this case, a vertical bar is displayed if the character to the right of the pointer is a space or the pointer is at the end of the line. For terminals lacking the capability to highlight an arbitrary character position in any way, the pointer is shown as a circumflex (or other marker character) temporarily overwriting the character to the left of the pointer, and an extra column is added at the left of each line for use when the pointer is at the start of the line. 3 Control_keys It is part of the philosophy of ECCE that all the editing commands should be accessible from any terminal, using just conventional printing characters and the line-terminator RETURN. No assumption is made about the availability of special control keys on the terminal keyboard. However, where a terminal is fitted with special keys, such as cursor controls, function keys, or switchable numeric pad, these keys are usually available as more convenient ways of entering frequently required commands. Alphabetic keys used in conjunction with the CONTROL shift available on most terminals may also be used in this way. All such keys, or key combinations, will be referred to as control keys. The particular advantage of control keys is that they are immediate in their effect; they do not require a following RETURN. Technically, these keys are MACROS. Macros are described in detail in a separate section but the basic principle is that a single key can be made to stand for an arbitrary command or command sequence. Initial definitions for some of the keys are pre-set on entry to the Editor; the interpretation of these may be freely altered, and others defined, at any time. This is part of a general capability to extend the repertoire of the Editor by means of user-defined commands. Because of the fact that the interpretation of control keys is not fixed and because of the considerable variation in what is available on different terminals, it is not possible to provide an enumeration of their functions here, despite the fact that they often provide the most convenient access to certain editing facilities. One control key which is always available is RETURN, which when used by itself in command mode is defined to cause a Move to the next line in the file. If cursor control keys are available, these will in general be associated with the Editor commands Cursor Up, Cursor Down, Cursor Left and Cursor Right. In many implementations the LF key is defined to cause repetition of the last command and the TAB key to cause a move to the next word in the file. It should be noted that the possibility of using control keys depends on appropriate support being available in the terminal handling software, so that they may not be usable in all modes of connection. In addition, some control keys have a reserved significance for the operating system and it is advisable to find out what these are sooner rather than later. One function which, as an exception to the general rule, cannot be invoked except by a control key is that of switching between command mode and data-entry mode. The restriction is solely to ensure that if data-entry mode can be entered, it can be left, since in this mode, none of the printing characters has a command significance. The key enquiry command (%Q) which is described in the section on MACROS provides a means of investigating the significance of both control and ordinary keys. 2 BEGINNERS To begin with, the Editor will seem a clumsy tool, particularly for those with limited typing experience. Changes which could be marked up on a document in no time take an age to translate into sequences of editing commands to achieve the desired effect. Fluency comes with practice, although editing remains a fiddling business, and mistakes are inevitable. Happily most mistakes are easily recovered from, and in the exceptional case where an edit goes disastrously wrong (for example unintentionally scrambling half the file), the editing session can always be abandoned without losing the original file, so that only the editing time is wasted. With experience, it becomes quite straightforward, and habitual, to edit a file 'sight unseen'. However, for initial learning, it is sensible to use as test data a file with known contents. The following procedure is a possible learning programme: (a) Beg or borrow a copy of some text file for experimentation. A suitable length is 30 to 100 lines of text. (b) Obtain a printer listing of the file. (c) At the terminal give the appropriate command to call the Editor to edit the test file (see next section). (d) Use the %Q command to explore the significance of the individual keys, particularly any control keys. (e) Initially use only the location commands to move about the file without altering it in order to gain familiarity with the effect of these commands in detail. (f) Mark up the listing of the file with a few typical 'corrections'. (g) Move back to the top of the file and start applying the corrections one by one from beginning to end. (h) When all the corrections have been applied, close off the edit. (i) Obtain a printer listing of the revised file for re-assurance that the corrections have really taken effect. There are quite a number of individual commands in ECCE, and each has some utility in particular cases. But there are only seven or eight which have a high frequency of use and indeed all editing can be done in terms of these. To begin with it is recommended that attention is confined to the following commands: Move (and Move back) \ cursor movement \ or control key Get and Kill / equivalents Insert and Erase / Find Substitute When these have been mastered, others can be added to the repertoire as the need for them is felt. There are often several ways of achieving the same effect with the Editor. The experienced user usually chooses one that involves least typing, but agonising over the choice can waste more time than is saved. 2 CALLING_THE_EDITOR The precise syntax for calling the Editor depends on which machine it is running on. Previous versions of VECCE had a common syntax (which still applies to the 2900 and APM versions) but the EMAS/370 and VAX/VMS versions are now fully consistent with the usual calling sequence on that machine. Options are specified by keywords on the command line, for example "-PRE=file" for APM, ",PRE=file" for 370/EMAS and "/PRE=file" for VAX/VMS. (a) To edit an existing file called "CURTEXT" so that the new file created will also be called "CURTEXT": VECCE CURTEXT This is the standard updating procedure. (b) To edit an existing file called "OLDTEXT" in such a way as to create a new file called "NEWTEXT": VECCE OLDTEXT/NEWTEXT on 2900 and APM VECCE OLDTEXT,NEWTEXT on EMAS/370 VECCE OLD.TXT NEW.TXT on VAX/VMS (c) To create a new file called "PROG34" from scratch: VECCE .N/PROG34 (see (b) for 370 and VMS syntax) However on the EMAS/2900, EMAS/370 and VAX/VMS versions an attempt to edit a file which does not exist will automatically create one of that name. The ".N" (.NULL for EMAS) stands for a null file, so that technically this is a special case of (b) above starting with an empty old file. The first editing command when creating a new file would normally be "G*" (see Get below) (d) To inspect an existing file called "RESULTS" without altering it: VECCE RESULTS/.N or equivalently VSHOW RESULTS Again this is a special case of (b) with a null new file. Alteration commands may be issued which change the editing buffer, but the changes are not written back to any file. (e) To edit an existing file "PROG" together with a secondary input file "SPECS" in order to create a new file "FULLPROG": VECCE PROG,SPECS/FULLPROG on 2900 and APM VECCE PROG,FULLPROG,sec=SPECS on EMAS/370 VECCE PROG FULLPROG/sec=SPECS on VAX/VMS In all cases where reference is made to a new file being created, the effect is to supersede any existing file of the same name, whether that file has been specified as an input to the Editor or not. (f) examples including option specifiers: VECCE CURTEXT-MINWIN=12-WTOP=6 on 2900 and APM VECCE CURTEXT,MINWIN=12,WTOP=6 on EMAS/370 VECCE CURTEXT/MINWIN=12/WTOP=6 on VAX/VMS VECCE CURTEXT-NOMATCH-PRE=WPCOMMANDS etc 3 Old_and_new_files While it is natural to speak of using the Editor to alter or modify a file, it is important for some purposes to understand that the Editor does not literally modify an existing file. What it does is produce a completely new file from the old one. Each editing session creates a fresh file, though in most cases the bulk of the material in it is copied verbatim from the old one. Very typically, at the conclusion of an editing session, the new file created supersedes the old one, so that the file-name which previously designated the old file now designates the new one. In this typical case, the effect is similar to what would happen if the Editor did actually alter the old file. However, the following consequences indicate why it is necessary to make the distinction: (a) if an editing session is abandoned, rather than being terminated normally, no new file is created and the old file remains unaltered; (b) the Editor can be called in such a way that the new file is given a different name from the old file so that the old also continues in existence at the end of the editing session; (c) on systems which automatically preserve earlier generations of like-named files, the old file also survives (though an earlier version may be purged). 3 Secondary_input The requirement often arises to incorporate into one file part or all of another file. Many computer systems provide a command to handle the particular case of concatenating complete files, either through the provision of a special utility program or as an option within a Copy or Transfer utility. The secondary input facility in ECCE provides a more general capability. In general terms the facility permits the user to switch from the main file to an alternative file and there select portions of that file to be incorporated into the file being edited. The file to be used for secondary input is nominated at the time the Editor is called, along with the old and new file-names. Alternatively, the file to be used can be specified in the course of the edit, by means of the "%S" command. 3 File-names_and_options Up to three file-names may be given when calling the Editor: the name of the file to be edited, the name of a secondary input file, and the name to be given to the edited file when the editing session is closed. These parameters have to be presented in the call command in the order just given. In addition it is possible when calling the Editor to select a number of Options which control or qualify the fashion in which the Editor operates, for example, what size of display window it is to use. Some option parameters have variable values (such as the height of the window) and others are simply selectors (such as whether case-distinctions are to be treated as significant when matching letters of the alphabet). Options are introduced by a qualifier symbol and a keyword; for a parameter with a variable value, this is followed by an equals-sign and a value. Examples of complete option specifications, using the dash (minus) as the qualifier symbol, are "-MINWIN=12" and "-MATCH". Some of these options may also be varied during the course of the edit by means of the Environment command ("%E"). 2 COMMAND_FORMATS When the Editor is called, it positions its file pointer at the start of the first line in the file to be edited and presents the initial display. At the outset, it is in command mode and expects command input to be typed on the command line. The response may take one of three forms: typing a command line followed by RETURN typing a Special command followed by RETURN pressing a control key (including plain RETURN) A command line consists of one or more editing commands, optionally separated by spaces. A command line is terminated by RETURN and errors noticed while typing it may be cancelled by means of the DEL key. 3 Special_commands Special commands are distinguished by starting with the prefix "%" (percent-sign) followed by a letter. They are used to select options and set modes which modify the effect of subsequent editing commands. Note also the special command ! (exclamation mark) which is used to introduce a system command to be called. This interpretation only applies when the character appears at the BEGINNING of a command. The most essential Special command is the Close command "%C" which is used to close off the edit. The Special command "%H" (for Help) provides general Help information on the Editor and its use, and the Special command "%Q" (for Query) allows the user to explore the significance of individual keys. Details of the Special commands are given in the major sections SPECIAL COMMANDS and MACROS. 3 Control_keys Where a control key has been defined as a command, the effect of pressing the key is effectively the same as if the command sequence for which the key stands had been typed in followed by RETURN. Note, however, the important difference mentioned under 'repetition'. RETURN by itself counts as a control key with the fixed significance of M (Move). One control key has the effect of switching between command mode and data-entry mode. In data-entry mode, only control keys (including RETURN) can be interpreted as commands, since any printing characters and spaces typed in this mode are treated as data to go into the file, overwriting any text already present at the current position. 3 Command_types There are just two formats for individual editing commands, one for those commands which are accompanied by a text string as parameter and one for those which are not. A command which has no text parameter takes the form of a single character or a single character followed by a minus sign. For most commands the single character is a letter, which is mnemonic for an imperative verb. For example, the Move command is denoted simply by "M" (or "m") and the Move back command by "M-" (or "m-"). A command with a text parameter takes the form of a single letter (or letter followed by minus) followed by whatever string of characters the user wants to specify, enclosed within delimiter characters. For example, "F/cat/" is an instance of the Find command with "cat" as its parameter, and "S.dog." is an instance of the Substitute command with "dog" as its parameter. The user has a choice of several characters for use as delimiters; the oblique stroke and the period illustrated above are popular because of typing convenience, but any character which has no defined significance to the Editor may be used. The opening and closing delimiter for any one parameter must be the same, and the delimiter must be chosen to be distinct from any of the characters which require to be included in the text string. Strings may include any printing characters and spaces, but not line-breaks. The commands which take a text parameter fall into two groups: text-matching commands and text-insertion commands. There is some relaxation of the format rules for the parameters for the latter (Insert, Overwrite, Substitute and Get); details are given in the description of the Insert command. There are a number of alternative ways of specifying a text parameter: by one of the six text parameter macro letters (X,Y,Z,x,y,z); by the ditto symbol("); by the exclamation-mark (!). The first of these is described in the section on Command and Text Macros. The ditto symbol indicates that the text string to be used is the same as the last string used in a command of the same group (matching or insertion). Using an exclamation-mark in place of a text string indicates that the actual text to be used is not provided within the command, but is to be requested at the time the command is executed. In this case, when the text is requested, it should be typed without delimiters and terminated by RETURN. (For the interpretation of exclamation-mark within command macro sequences, see MACROS). Note however the distinct use of the exclamation point as the first character on a command line to execute a host operating system command. 3 Case_distinctions In commands, the upper-case letters 'A' to 'W' have a fixed significance as basic editing commands. Initially the lower-case letters 'a' to 'w' have the same meaning as their upper-case counterparts, but this is not fixed and may be changed by re-definition as command macros. The letters 'X' to 'Z' and 'x' to 'z' have no fixed significance to the Editor and are available for definition as text or command macros. Within text strings, case distinctions are always significant for insertions, but are normally ignored for text matching purposes, so that, for example, the string "the" would be considered to match "The" as well as "the" (not to mention "tHe" and so on). However, there is an Option (NOMATCH) which may be selected to prevent this indiscriminate matching. 3 Multiple_commands When more than one command is typed on a line, they may be, but need not be, separated by spaces. The commands are executed in order from left to right. One point of putting several commands on one line is to control the frequency of feedback. Another is to produce a useful unit for repetition. 3 Syntactic_errors Before proceeding to execute a command line, the Editor checks that the format of each command in it is correct, for example, that a text matching command is accompanied by a text parameter. If not, an error report is made indicating the nature of the error and no attempt is made to execute any of the commands making up the line. Note the contrast between the treatment of this kind of error and the effect of failures in executing well-formed commands. 3 Failure_conditions The specification of the individual commands defines not only what happens when the command is carried out but the condition under which the command cannot be carried out -- the failure condition. In the simple case, a failure in command execution counts as an error and a report is made. Any subsequent commands in a command sequence are not executed, but the effect of any earlier commands in a command sequence is not undone, nor that of successfully completed cases of a repeated command. There may also be partial execution of the failing command itself, as defined in the individual descriptions which follow. Failure conditions can be utilised to control command execution in a number of ways, of which the most important is mentioned in the next paragraph. For a few commands, mainly those represented by a character other than a letter, there is no failure condition. 3 Repetition_numbers Any command may be followed by a repetition number (a decimal integer) indicating that the command is to be repeated the number of times specified. For example, "M5" means Move five times, and "I/ /20" means Insert a space twenty times, that is, in effect, insert twenty spaces. An asterisk may be used in place of a repetition number with the significance: repeat the command until it fails. For typing convenience, the digit zero may be employed in place of an asterisk. For example, the command "E*" (or "E0") means Erase repeatedly until the failure condition for Erase is met, that is, Erase up to the end of the line. 3 Repetition_of_last_command Instead of typing in a new command at any point, the user may instead type simply a repetition number. This causes the last genuine command line to be executed again the number of times specified. The whole command line, which may consist of a sequence of several commands, is repeated. In this context, neither Special commands nor control key commands count as genuine command lines, nor do they cause the last genuine command to be lost (although some Special commands may cause the record of it to be erased from the screen). The control key Linefeed is generally defined to have the significance of repeating the last command once. 2 INDIVIDUAL_EDITING_COMMANDS 3 M___Move The Move command causes the file pointer to be moved from its current position to the start of the following line. Attaching a repetition number to a Move command provides a means of moving forward a fixed number of lines. For example, the command "M99" issued at the start of the file, causes the pointer to be moved to the start of the hundredth line in the file. The command fails if the file pointer is at the very end of the file, that is, beyond the last line of text. It is legitimate to Move from the last line in the file to the end-of-file position, but then further Moves will fail. 3 M-__Move_back This command causes the file pointer to be moved from its current position to the start of the previous line. The command fails if the current line is the first line in the file, the pointer being moved nonetheless to the start of this line. 3 }___Cursor_Down This command is similar to the Move command, except that the pointer is moved to the column position in the following line corresponding to its position in the current line. The command is typically the definition of a cursor control key. With this and the other cursor movement commands, the resulting line position may be beyond the end of the line (that is, to the right of the last printing character). This is often a temporary state en route to another position, and so the fact that the cursor is out in space does not of itself imply any extension of the line, but if any text is entered in this situation, the gap between the existing end of the line and the file pointer is first filled with spaces. The command fails when the file pointer is on (or beyond) the last line of the file. 3 {___Cursor_Up This command is similar to the Move Back command, except that the pointer is moved to the column position in the previous line corresponding to its position in the current line. See the notes on Cursor Down (above) The command fails when the file pointer is on the first line of the file, and the pointer does not move. 3 R___Right-shift This command causes the file pointer to be moved right one character position. The command fails if the file pointer is at or beyond the end of the current line. Hence "R*" takes the pointer from anywhere within the line to the right hand end of the line. 3 L___Left-shift This command causes the file pointer to be moved left one character position. The command fails if the file pointer is at the start of the current line. Hence "L*" takes the pointer from any position to the start of the line. 3 >___Cursor_Right This command is similar to the Right-shift command except that it permits the file pointer to be moved beyond the end of the line, that is, beyond the rightmost character on the line. See the notes on Cursor Down. The Cursor Right command fails if the file pointer is at or beyond the maximum line length defined by WIDTH. 3 <___Cursor_Left The Cursor Left command is identical in effect to the left-shift command. It is provided for reasons of symmetry. 3 H___Cursor_Home This command is used in conjunction with the cursor movement commands {, }, < and > and is best defined to be a control key. Its effect is to repeat the last executed of these commands until the cursor has moved as far as it can go in that direction. That is if the last command was '<' the cursor moves to the beginning of the current line, and if it was '>' to the end. Following a '{' the cursor moves to the top of the screen and following '}', to the bottom. A special case is made when 'H' follows '{' or '}' and the cursor is already at the top or bottom of the screen. In that event the file pointer moves up or down by one whole screen (strictly speaking, by the current value of MINWIN). The command fails if the cursor reaches the beginning or en of the file. 3 F___Find_Text The Find command causes the Editor to search forward in the file for the first occurrence of the specified text string. The search starts at the current position of the file pointer, except that an occurrence just at the file pointer which has already been matched, either by Find or by Uncover or Verify, is ignored. For example, adding a repetition count to a Find command, as in "F/cat/3", will locate the third occurrence of the sequence "cat". The repetition does not have to be in the form of a count attached to the original command. For example, it is a common experience to discover, after a Find has been executed once, that the character sequence chosen in fact appears earlier in the file than the intended position. In this case the Find command can simply be repeated, by typing 1 as a repetition command, until the desired occurrence is reached. By default the search continues to the end of the file. The scope of the search may, however, be limited to a particular number of lines counting from (and including) the current line, by specifying the number of lines between the command letter and the quoted text. For example, "F9/cat/" limits the scope of the search to the current line and the next eight. The command fails if there is no occurrence of the specified sequence of characters within the scope of the search. Where the scope is more than one line, the file pointer is moved to the start of the last line searched (end-of-file in the case of unlimited scope). Where the scope is one line, the file pointer is not moved. 3 F-__Find_back The Find back command is similar in effect to Find except that the search proceeds backwards through the file. The number of lines to be searched may be specified between the minus and the text parameter; by default the search continues to the start of the file. The command fails if there is no occurrence of the specified text within the scope of the search, the file pointer ending up at the start of the last line searched. 3 T___Traverse_Text The Traverse command causes the first occurrence of the specified text to be located and the pointer to be positioned at the right-hand end of the occurrence, rather than at the start as with Find. The search proceeds as for Find except that the default scope is confined to the current line and that an occurrence of text already matched is not ignored. The command fails if there is no occurrence of the text string within the scope of the search. Pointer movement in the case of failure is exactly as for Find. 3 V___Verify_Text The Verify command neither moves the file pointer nor alters the content of the file. It succeeds if the sequence of characters immediately to the right of the file pointer matches the text specified; otherwise it fails. The Verify command only has a use in conjunction with programmed commands (see the section on this topic). 3 D___Delete_Text The Delete command causes the first occurrence of the specified text to be located and then deleted, leaving the file pointer at the site of the deletion. The search proceeds as for Find, except that the default scope is confined to the current line, rather than the rest of the file, and an occurrence of text already matched is not ignored. The command fails if there is no occurrence of the specified text within the scope of the command. Pointer movement in cases of failure is exactly as for Find. 3 I___Insert_Text This command has the effect of inserting the text specified to the left of the file pointer. The text parameter which follows the letter "I" may take any of the following forms: quoted text between delimiter characters a text macro letter ('X'-'Z' or 'x'-'z') the ditto character the exclamation-mark The last-mentioned case ("I!") provides a direct-entry capability for inserting a text string within a line. The text to be inserted is requested when the Insert command is executed, with the video cursor at the position of the file pointer. The normal way of terminating the text is with RETURN; if any other control key is used as a terminator, it causes the command sequence currently being executed to be abandoned and the control key to be treated as a new command. This applies also to the use of this form for the other insertion commands (Overwrite, Substitute, and Get). For the direct-entry form, in most implementations, a certain amount of space is opened up at the position of the file pointer to permit the text to be typed in. Then when the terminating key is pressed, the line is closed up again. In some implementations, no space is opened up, and the line automatically accommodates each character as it is typed. For typing convenience, the Editor relaxes some of the syntactic rules for all the insertion commands (Insert, Overwrite, Substitute and Get), but not for the text matching commands. The closing delimiter in the case of quoted text may be omitted if the text string is the last thing in a command line and the exclamation-mark indicating the direct-entry case may be omitted provided that no ambiguity could arise (that is, provided the immediately following character is not one of the text macro letters). Specifying a repetition count with Insert is a convenient way of inserting multiple characters, typically spaces. Insert fails if adding the text would cause the part of the line to the left of the pointer to exceed the maximum line length (as defined by WIDTH). 3 O___Overwrite_with_Text The Overwrite command provides a means of replacing existing text on a one-for-one basis by new text. It differs from Insert in that one character is deleted from the file for each character added, except that if the end of the line is reached, it functions identically to insertion. The possible forms of text parameter are as for Insert. The exclamation-mark form ("O!" or just "O") again provides a direct-entry capability for a single piece of text. It is useful only in command mode, since data-entry mode provides that capability all the time. The failure condition is the same as for Insert. 3 S___Substitute_Text The Substitute command causes the text matched by an earlier Find (or Uncover or Verify) to be deleted and the text specified as parameter following the "S" to be inserted. The operation of substitution involves two text strings, one to be removed, the other to be inserted. In ECCE the first of these is established by one command, typically a Find, and the second is specified as the parameter to Substitute. Thus, for example, "F/this/ S/these/" will alter the first occurrence of "this" to "these". One advantage of splitting the function between two commands is that they can be issued independently and the effect of the Find checked before giving the Substitute. Substitute fails if the last positioning action was not a Find, Uncover or Verify, or the effect of inserting the text would exceed the maximum line length permitted by the Editor. 3 G___Get_Text The Get command causes the text specified to be inserted as a complete line above the current line. The file pointer is moved to the start of the current line if it is not already there, but this remains the current line. The Get command is the way in which complete lines are inserted in a file. The most frequently used form is "G!" (or "G"). In this case the text is not embedded in the command as a text string, but is requested when the Get is executed by the Editor. A repeated Get expects a fresh line each time; it does not cause the first line typed to be inserted again. Thus "G!5" (or "G5") causes five lines to be requested and inserted, in the order typed, above the current line. The Get command fails if the line typed in starts with a colon. The failure condition is an arbitrary convention, which may be used to cause a repeated Get to terminate. In particular, it permits the use of "G!*" (or "G*") to insert an indefinite number of lines (which it would be inconvenient to have to count). 3 K___Kill_Line The Kill command "K" causes the whole of the current line to be deleted. The file pointer is left positioned at the start of the following line. Kill does not simply erase all the characters on a line leaving it blank; it removes the line altogether. Kill followed by Get (eg "KG" or "K2G3") is a common command sequence when replacing a number of complete lines by other complete lines. The command fails if the file pointer is at the end of the file. 3 K-__Kill_Line_back The Kill back command "K-" causes the whole of the line before the current line to be deleted. The file pointer is moved to the start of the current line. The command fails if the current line is the first line in the file, the pointer being moved nonetheless to the start of this line. 3 E___Erase_Character The Erase command "E" causes the character immediately to the right of the file pointer to be deleted The command fails if the file pointer is at or beyond the end of the current line. Hence "E*" erases all characters on the line to the right of the pointer. 3 E-__Erase_Character_back The Erase back command "E-" causes the character immediately to the left of the file pointer to be deleted. The command fails if the pointer is at the start of the line. Hence "E-*" erases all characters to the left of the pointer. 3 C___Case-change_Character If the character immediately to the right of the file pointer is a letter of the alphabet, the Case-change command alters it to the corresponding letter in the other case, so that upper is mapped to lower and lower to upper. Whether the character is a letter or not, the pointer is moved one position to the right. The command fails if the pointer is at or beyond the end of the current line. Hence "C*" changes the case of all letters to the right of the pointer on the current line. 3 U___Uncover_Text The Uncover command causes the first (or next) occurrence of the specified text to be located and all the material between the position of the file pointer at the start of the command and the occurrence of the text to be deleted. The text itself is not deleted. The search proceeds as for Find, except that the default scope is confined to the current line. The Uncover command is applicable where it is most convenient to specify a deletion as 'up to' a particular character or sequence of characters. With an explicit scope, Uncover can delete part of the starting line, a number of complete lines, and an initial part of the line in which the string is located. The command fails if there is no occurrence of the text string within the scope of the search. In the case of the default scope (current line only), the pointer is not moved and the line is not changed. In the case of a multi-line search, failure results in deletion of all material between the initial position of the pointer and the start of the last line searched, which is where the pointer ends up. An unlimited search can be specified by means of "U*". 3 B___Break_Line This command causes the current line to be split in two at the position of the file pointer; the second part becomes the current line. Break creates two lines from one. One of its uses is to split lines which may have become undesirably long as a result of insertions. Break with the pointer at the start of a line creates a blank line above the current line. There is no natural failure condition for this command; implementations generally impose an upper limit on the number of times it may be repeated. 3 J___Join_Two_Lines This command causes the following line to be appended to the current line, that is, it creates one line from two. The command fails if the current line already exceeds the length defined as the maximum line width. In the case of failure the pointer is positioned at the end of the current line. 3 G-__I-__Insert_and_Get_back The commands "I-" and "G-" re-introduce material which has been deleted from the file, the insertion being made at the position at which they are executed, which may or may not be the position at which the material was deleted. The order of recovery is the reverse of the order of deletion, and, in tune with this, these commands leave the file pointer in front of, rather than after, the newly inserted material. The use of these commands at a different site from that at which the material was deleted is the basic technique in ECCE of moving blocks of text from one position to another. The command "I-" restores a single deleted character from the last alteration site in the file. The last alteration site is the position in the file at which a sequence of contiguous insertions and deletions was last carried out. All the material deleted at this site is eligible for insertion. It fails if there are no remaining deleted characters from that site. For example, the command "I-0" brings in at any point all the text deleted at the last alteration site, and the sequence "ERI-" (Erase, Right, Insert back) reverses the order of a pair of characters. The command "G-" restores a complete deleted line. All complete lines deleted from the file at any time in the course of the edit are available for recovery, not just those removed at the last alteration site. It fails if there are no further deletions to be restored. For example, "KMG-" (Kill, Move, Get back) reverses the order of a pair of lines. 3 O-__Overwrite_back The command "O-" is an 'undo' command which can both restore material just deleted and remove material just inserted. It operates at the last alteration site in the file, irrespective of the position of the file pointer at the time the "O-" is executed. The last alteration site is the position in the file at which a sequence of contiguous insertions and deletions was last carried out. All the material deleted at this site is eligible for re-insertion, and all the inserted material is eligible for removal. Each execution of the "O-" command removes a single inserted character or line break and/or restores a single deleted character or line break. It fails if neither of these operations is possible. Hence "O-*" removes the effect of all the alterations at the site. 3 P___Print The Print command is used solely to achieve feedback from the Editor. It causes the current line to be displayed, and, if repeated, causes a Move to the following line. 3 N/N_-__Next_or_previous_unit The Next command "N" locates the next word or matching punctuation symbol in the file to the right of the file pointer. If the character currently to the right of the pointer is a letter or digit or a space, or the pointer is at the end of the line, the pointer is moved to the beginning of the next word, where a word is defined as a sequence of alphanumeric characters (letters or digits) not preceded by an alphanumeric character. If the character is a left bracket (round, square or curly), the pointer is moved to the corresponding right bracket, taking account of nested occurrences of bracket symbols. If the character is any other symbol, the pointer is moved to the next occurrence of that symbol. In all cases, the unit located is regarded as having been matched by a text search (so that Substitute is valid, for example). The command fails if there is no occurrence of the appropriate kind of unit before the end of the file. The Next back command "N-" locates the previous unit in the file, a unit being defined as for Next (above), with the role of left and right brackets reversed. It fails if there is no unit of the appropriate kind before the beginning of the file. 3 Q___Query_Spelling The Query command is used to invoke a check on the form of the text starting at the current position of the file pointer. The nature of the check currently implemented is a simple spelling error detection. This is done by comparing words with entries in a limited dictionary of written English. The command fails if the check fails. Repeated execution implies advancing to the next unit for checking. Hence the command "Q*" causes the check to be performed on successive words until one fails, or the end of the file is reached. 3 #n__Move_to_line_number_n This command causes the file pointer to be moved from its current position to the start of the line specified. Lines are numbered from 1 at the start of the file and the numbers relate to the current state of the file, not its state at the start of editing. If no line number is specified in the command, one is requested at the time the command is executed. The command is executed as a Move or Move back as appropriate, and fails as for Move if the line number is too big. Note that the parameter is not a repetition count. 3 +n__Increment_number_by_n The Increment command (plus-sign) is used to add the value specified by to the first number to the right of the pointer on the current line. For this purpose, a number is any sequence of decimal digits, or a single letter. This command is most useful when it is required to adjust more than one number by a constant amount. The value 1 is understood if is omitted. The form "+-" may be used to specify a negative increment. Letters are included to cover the case where they are used to 'number' paragraphs. The command fails if there is no number to the right of the pointer on the current line, or the increment specified would take the item out of range. Note that the parameter is not a repetition count. 3 A___Adjust_line_length The Adjust command is provided to simplify the task of maintaining a reasonably uniform line length within running text. In brief, it has the effect of breaking over-length lines and extending under-length lines by bringing up words from succeeding lines. The line length applied is as defined by the parameter WIDTH, and the left margin as defined by MARGIN The detailed specification which follows is quite complicated. The main points to note are: a single Adjust will make the current line an acceptable length and leave the file pointer at the start of the (perhaps revised) following line; A* will (try to) produce adjusted lines up to the end of a paragraph, a paragraph being understood to terminate with a blank line (or end of file). (a) If the end of the file has been reached, the command fails with no effect. (b) If the current line (to the right of any margin) is blank, it is not changed and the file pointer is moved to the start of the following line. (c) If the length of the current line exceeds the defined maximum line length, the line is broken at the rightmost space character to the right of the file pointer which leaves a line not exceeding the maximum length, and a new line is formed from the latter part of the original line, with an added margin of spaces if MARGIN is non-zero. The file pointer is left at the effective start of the new line. The command fails if there is no space character satisfying the condition specified. (d) If the length of the current line is not greater than the maximum length, 'words' from succeeding lines are appended to the current line until either doing so would exceed the maximum length or a line which is blank to the right of the margin (or end of file) is reached. The latter case is a failure condition, but in all cases the file pointer ends up at the start of the line following the adjusted line. For the purposes of Adjust, a word is defined to be any sequence of characters terminated by a space or end of line. Appending a word implies inserting a space plus the word at the end of the first line, and removing the word plus its terminating space from the second line (removing the whole line in the case that the word is the only word on the line). 3 @n__At_column_position_n @n The purpose of the 'at' command is to enable text to be aligned to a particular column position. The effect is that the part of the current line to the right of the file pointer is aligned to the column position specified by . This is achieved by the insertion or deletion of spaces to the left of the file pointer. In the event that aligning to the column position specified would cause the length of the line to exceed the defined maximum line length, is reduced to prevent this. Columns are numbered from zero upwards, so that, for example, @40 has the natural interpretation of placing text half-way along an 80-column line. Spaces to the right of the file pointer are not affected by this command, and only space characters immediately to the left of the file pointer are removed in seeking to align leftwards. Using "@" with a large has the effect of right-aligning the text following the pointer. The @n command fails if space-deletion fails to achieve correct alignment. Note that the number is not a repetition count. 3 ^___Set_Marker Execution of the Set Marker command (caret or circumflex by itself) causes the current position of the file pointer to be noted for future reference The marker set by this command may be utilised, and cancelled, by any of the following commands: the Define Macro command the Revert to Marker command the Switch Inputs command A marker is also cancelled if the text surrounding it is deleted from the file. 3 ^n__define_Macro_'X'...'z' The Define Macro command (caret with accompanying number) serves to define one of the six text macro letters ('X','Y','Z','x','y','z') as selected by (1 to 6 respectively). For example "^2" is used to define 'Y' and "^6" to define 'z'. The effect is to define the letter selected to stand for the sequence of text between the set marker and the current position, or, if no marker is set, the text just matched by a text matching command. Any existing definition of the letter is lost, and the marker is cancelled. Although text parameters typed within commands cannot, for syntactic reasons, contain line breaks, there is no such restriction on the definition of macro letters by means of this command, subject to an overall limit on length imposed by the implementation. However, multi-line text strings are valid only for the insertion group of commands, not for the text matching group. It is immaterial whether the marker is ahead of the current position or vice versa. The command fails if no marker is set and the file pointer is not at a matched text position. For convenience, with a marker set, a second Set Marker command (that is, simple caret without accompanying ) is interpreted as Define Macro defining 'X'. 3 =___Revert_to_Marker The Revert command (equals-sign) has the property of restoring the file pointer to the position established by the last executed Set Marker. The marker is cancelled. The command fails if there is no marker set. 3 |___Toggle_Destruction_mode Successive execution of this command (vertical bar) alternately enters or leaves a special mode of operation called Destructive mode. In this state, any of the movement commands may be used in a destructive sense, that is in such a way as to delete all the material from the starting position to the position after executing the move. Existence of the state is indicated by a special prompt. Note that actual alteration commands are disallowed in this mode. The mode is most useful in conjunction with some of the more specialized movement commands such as Next, Cursor Down and Query. 3 $___Switch_Inputs This command is used to switch from the main file to the secondary input or back again. Having switched to secondary input, any of the location commands may be used to move about within that file, but alteration commands are not valid. The current position in the two files is independent and is preserved when a switch is made between the two. When this facility is used, a separate window is created out of the screen region used for file display, to show the current part of the secondary input file. Apart from providing the facility simply to inspect another file while editing, the main use of secondary input is to enable material from the second file to be incorporated in the first. One way of doing this is to Define text macros to represent pieces of text in the secondary file and use these as parameters for Insert after switching back to the main file. To provide a more convenient way of handling the most common requirements, the convention is also adopted that if a set marker is outstanding when a switch is made from secondary input to the main file, the text from the position of the marker up to the current position within the secondary file is immediately inserted in the main file. For example, incorporating the whole of a secondary file in the main file can be achieved by moving to the appropriate point in the main file and then giving the commands (separately or as one command line): $ ^ M* $ that is, Switch to secondary input, Set Marker, Move to end of file, Switch back to main file. Any marker set in the main file is cancelled on switching to secondary input. 3 ~___Toggle_INSERT_mode This command switches the editor between REPLACE and INSERT modes. In INSERT mode text typed while in DATA ENTRY mode is inserted at the file pointer rather than replacing existing text. The screen feedback for the I! command is also handled in accordance with the current setting. 2 OPTIONS This section describes the various options which may be selected to control or qualify the operation of the Editor. The initial parameters in the list marked with an asterisk can be specified only in the command line when the Editor is called (see CALLING THE EDITOR); that is, once established, they cannot be changed. The others may be freely altered at any time, by means of the Environment command "%E"(below). The syntax for specifying an option depends on the machine being used. For APM and EMAS/2900, options are introduced by a minus sign, on EMAS/370 a comma (are parameters specified by keywords) and on VAX/VMS by a slash, ie as qualifiers. The examples below assume APM syntax. 3 PRE____Pre-definition_file This Option is provided to make it possible to specify a file of editing commands which are to be obeyed at the outset of the editing session. Its main use is to permit frequently used definitions to be recovered from a file, but the file may contain any editing commands and may in fact comprise a complete edit ending with the Close command ("%C"). Values for this parameter must be valid file-names. Although PRE may be specified at the outset only, the %G command (Get editing commands from file) is available at any time. Examples: -PRE=WPPREDEF -PRE=ECUU99.PROJ_DEF1 3 LOG____Log_File * LOG=logfile If this option is present, a complete record of all editing commands entered in a session is preserved in "logfile". This can then be executed using the command option "PRE=logfile" or the special command "%G logfile" to replay the edit. This feature is a safeguard against system crashes. In case of a crash the output file is lost, but the log file can be used to re-create it up to the point of the crash. (Note that on EMAS/370 the output file WILL BE saved in VECCE#SAVEn in the case of a communications failure, though not a processor crash.) There is a special keyword for 'logfile' on EMAS systems only. If the log file is specified as ".JOURNAL" the log is directed to the system journal, and can be retrieved and edited using the VRECAP command. The logfile is also useful if your edit has gone disastrously wrong. In that case you can abort the edit with %A, edit the log file and remove everything after and including the command which did the damage. On replay you will get the file just before the erroneous command and can try again. (**Note** You can recover text deleted by K or E using the G- and I- commands, which is simpler than using the logile!) 4 Using_%B_and_Logfiles After a %B command is executed, a new logfile is started. On machines which do not keep multiple versions the old log is lost. Thus the log records the edit from the backup point. HOWEVER the editor must be in EXACTLY the same state when attempting to execute the logfile as just after the %B command. In particular all editor options set by %D, %L, %M, %E must be identical and THE FILE POINTER MUST BE IN THE SAME PLACE. It is recommended that the first command issued after a %B is M-0 to locate the file pointer and that if you changed any options, note the values. If you do not get the state exactly right before executing the log file you are likely to corrupt your file. You have been warned. 4 Format_of_logfile All input typed to the editor is stored in the logfile, including commands in any PRE file. Text typed on the command line is entered as seen, and control keys are represented by a special code which is composed only of printable characters. Values less than 32 are entered as '&'value+64, so that A becomes &A and is &[. A translation is applied to all control sequences by the low-level software, so that the entry in the logfile may not be the same as the actual control character or escape sequence. In particular becomes &J and &M. You can always identify the meaning of a sequence using the %K command. For example %K&[A defines cursor up ({) on DEC terminals and %K&I () usually means N. When reading from a command file, the editor can not enter DATA ENTRY mode, so text typed in this mode is added to the file using the I! or O! commands. Technically, an unused control sequence is defined to be I! or O!. This sequence is then executed and the text follows. Finally the control sequence is deassigned. 3 TTYPE__Terminal_type Most versions of VECCE determine their terminal characteristics from the operating system. The terminal type must therefore be set up as each operating system requires, ie by TERMINALTYPE on EMAS and SET TERMINAL on VAX/VMS. This is the default but it can be overriden by the parameter TTYPE,which informs the Editor what type of interactive terminal is being used and hence defines the terminal characteristics, including the screen length and screen width. Values for this parameter are numbers in the ERCC enumeration; the default value is the system-defined TERMINALTYPE, and in general this should be appropriate. Examples: -TTYPE=12 -TTYPE=13 {VT100} {Esprit} 3 Window_dimensions * WTOP -- window top Default: 0 Range: 0..VROWS-1 * WROWS -- window rows Default: VROWS-2 Range: 1..VROWS-2 * WLEFT -- window left Default: 0 Range: 0..VCOLS * WCOLS -- window columns Default: VCOLS Range: 0..VCOLS * CTOP -- command top Default: WROWS Range: 0..VROWS-2 * CLEFT -- command left Default: 0 Range: 0..39 * CCOLS -- command columns Default: VCOLS Range: 40..VCOLS These parameters define the two screen regions to be used by the Editor. The 'top' values are in terms of row numbers ranging from zero at the top of the actual screen to VROWS-1 at the bottom; VROWS is typically 24. The 'left' values relate to columns, numbered from zero at the left of the actual screen to VCOLS-1 at the right; VCOLS is typically 80. The first four define the total extent of the screen region to be used for displaying the file being edited. The window height, as defined by WROWS, may be anything from one row up to the full screen height less two rows. A one row window obviously gives a rather blinkered view of the file. The width of the window, as defined by WCOLS, may be anything from one column to the full screen size. A one column window is obviously daft. The parameters CTOP, CLEFT and CCOLS define the position and width of the two-row region used for commands and reports. CTOP specifies the first of the two rows. The minimum width for the command region, as defined by CCOLS, is 40. Usually when the Editor is called directly by the user from system command level, it is appropriate for these two regions to occupy the full screen, but when the Editor is called from within another package or if the user wants to preserve other information on the screen, a smaller effective screen area may be specified. The Editor neither clears nor wittingly modifies areas outside the regions specified by these parameters. With the default values, the command region occupies the last two rows on the screen and the file window the remainder. 3 Effective_window * MAXWIN -- maximum window Default: WROWS Range: 1..WROWS MINWIN -- minimum window Default: ? Range: 1..WROWS The purpose of these Options is to make it possible to control the volume of text which is transferred to the screen at any one time to show the state of the file. The number of lines used within the available window area is allowed to vary between the limits specified by MINWIN and MAXWIN. The principle is that when the focus of editing moves to a completely new site in the file, only MINWIN rows are displayed in the lower part of the available window area. During local manoeuvres, this minimum display is extended as appropriate up to the selected maximum. (What operations permit extension depends on the video characteristics and the position and width of the window). MAXWIN determines the maximum number of lines to be used for the time being, the remainder of the The MAXWIN parameter selects the amount of the file window which is to be used at the outset, the remainder being reserved for secondary input, or subsequent expansion through increasing MINWIN. When a secondary input file is being processed, it has its own varying size window at the top of the overall file display region defined by WTOP and WROWS, originally as determined by MAXWIN (or a default value if MAXWIN is zero). When a new MINWIN value is selected (by %D or %E), it alters the secondary input value if secondary input is selected at the time, rather than the main file MINWIN value. Whenever an increased minimum value is selected for secondary input, this has the effect of constraining the maximum size of the main file's effective window, and conversely. Where there are no performance restrictions imposed by communication or processing systems, the upper limit value (WROWS) is usually appropriate for MINWIN. The default value is chosen according to the system. 3 WIDTH__Text_line_width The parameter WIDTH specifies the maximum line length to be used in connection with the Adjust and 'At' commands (and for failure conditions in the case of Insert and Join). The initial default value is 80. The parameter MARGIN specifies a left margin position, which defines the effective start of the line. This determines where the file pointer is placed following a Move or Move back command, and is also relevant to the operation of the Adjust command. WIDTH is inclusive of MARGIN. The initial default value is zero. 3 MATCH__Letter-case_matching When matching text strings in the course of executing any of the commands Find, Delete, Traverse, Uncover or Verify, the Editor may or may not ignore case distinctions between letters. By default it ignores them. This mode of matching may be switched off by selecting the option NOMATCH and re-established by selecting the alternative option MATCH. When it is switched off, letters in text parameters are matched exactly as typed against letters in the file. The setting of this mode does not affect text parameters for the insertion commands, which are always inserted exactly as typed. 3 MARK___Displaying_pointer This parameter controls how the current position of the file pointer is displayed when the Editor is in command mode. The options are HILIGHT or MARK. HILIGHT implies use of whatever capability a video has for distinguishing arbitrary characters, for example, reduced or increased intensity, underline, or (preferably) reverse video. Its use may require particular switch settings or intensity adjustments on the terminal. MARK implies the technique of overwriting the character immediately to the left of the current position with a distinguished character (splodge or tilde). An additional column is inserted at the beginning of each line in this mode, for use when the pointer is at the beginning of the line. MARK is appropriate for terminals which have no means of highlighting individual character positions. 3 EARLY__Updating_strategy The default strategy for updating the window is to do so only when the material in it is changed or the file pointer is moved outside it. Selecting EARLY causes the window to be extended or refreshed when the bottom line is reached rather than when it is passed. The default may be restored by selecting LATE. 3 TAB_EXPAND__Display_of_TAB_chars By default any tab characters (ASCII 9) present in the file are displayed as a sub, '_'. However they are sometimes used in place of spaces, to indicate that the text following the tab should be aligned at a particular column. Selecting the expansion mode will display the file with text correctly aligned to the pre-set tab positions. The tab settings are displayed and altered by the %T command. Tab characters may be used as the text parameter of VECCE commands by defining a control key (usually the tab key) to be a text macro with the value of a tab character. This key may then be used to enter a tab when prompted by any of the commands I!, O!, F!, or in DATA ENTRY mode. Unfortunately this can not be used to supply a parameter along with a command on the command line. For this purpose, it is necessary to define a printing character (lower case letter or X,Y,Z) as the text macro. The commands %K= and %K X= will make the necessary definitions. For more detail see the chapter on macros. When in expansion mode the screen display will look as if all the tabs had been replaced by a number of spaces, but some editing commands will behave differently. In particular it is not possible for the file pointer to be in the 'middle' of a tab, and there will be several locations on the screen which do not correspond to characters in the file. The effect of this is that when moving along a line using the R, L, > or < commands the file pointer will appear to skip to the next tab column. The cursor movement commands { and } behave differently in expansion mode. Instead of moving from the Nth real character on one line to the Nth on the line above or below, the effect is to move to the same screen column on the new line, regardless of the number of file characters. However, if the screen position immediately above or below the current one is one of the virtual spaces associated with a tab, the file pointer will move to the following tab position. Therefore it may not be possible to move the file pointer vertically except when it is at a tab column. The effect of inserting or overwriting text may also be different in tab expansion mode. The effect is to update the screen display in a sensible fashion, which will in general give a different result to what would be obtained without tab expansion. Most users will not need to know the details. 3 Save_Options This parameter applies to only EMAS/370 versions of VECCE and can only be issued as part of the command line calling VECCE. Its effect is to save the values of the parameters on th rest of the line in the processes profile information. Those values then become the default for future calls of VECCE. The syntax is ,SAVE=YES. 3 Overwrite Because EMAS/370 does not keep earlier versions of files VECCE will normally ask you for confirmation if the effect of th command would be to overwrite an existing file. The parameter ,OVERWRITE=YES suppresses this. 2 SPECIAL_COMMANDS The most important Special command is the Close command "%C" which is the normal method of closing off the edit and making permanent the changes to the file. If for any reason it is desired to ABANDON the edit without giving effect to the changes, the Abandon command "%A" should be used instead. The variant "%Ci" is used to invoke IMP syntax checking before finally closing the file. See also the section on MACROS for the Special commands "%Q" (Query key definition) and "%K" (define Key). 3 %C__Close_Edit Close the edit and return to command level. A new filename may be specified on the same line as %C, and if that is done the edit will be written to this file rather than the one specified when VECCE was called. 3 %A__Abandon_Edit Abandon the edit and return to command level without writing the output file. If the file has been altered you will be asked whether you really wish to lose the changes. 3 %B__Backup %B or %B output_file On execution of a %B command the current state of the edit is saved in a file. By default the output file is that specified when entering VECCE, but can be changed by explicitly specifying a filename to %B. Periodic use of this command is recommended during long edits to guard against system crashes. Note that on execution of %B all stored deleted text is lost and can not be recovered. 3 %E__modify_Environment %E The Environment command "%E" switches the Editor into a mode in which the various options described above may be modified. It cycles through the list of options displaying the current value and permitting an alternative value to be specifed. The RETURN key is used to move on to the next in the list and colon is used to return to editing. For a numeric option, a number must be typed to specify a new value; for a yes/no option any response other than RETURN or colon is sufficient to alter the setting. 3 %D__set_Display_size %D This command provides an alternative means of setting MINWIN, without entering Environment setting mode. When used by itself, without , it leaves MINWIN un-altered but re-writes the display. It should be used if for any reason the window has been corrupted (by an operator message, for example). 3 %L__set_Line_width/Margin %L %M These commands provide an alternative means of setting WIDTH and MARGIN. The parameter WIDTH specifies the maximum line length to be used in connection with the Adjust and 'At' commands (and for failure conditions in the case of Insert and Join). The initial default value is 80. The parameter MARGIN specifies a left margin position, which defines the effective start of the line. This determines where the file pointer is placed following a Move or Move back command, and is also relevant to the operation of the Adjust command. WIDTH is inclusive of MARGIN. 3 %S__define_Secondary_input %S file-name As an alternative to specifying a secondary input file at the time of calling the Editor, a command of the form "%S" followed by a file-name may be given during the course of editing. This establishes the named file as the secondary input and switches to it. Any existing secondary file is discarded. In some implementations, the amount of information which can be added from a file specified in this way may be limited, compared with what can be inserted when the secondary input file is specified at the outset. 3 %G__Get_commands_from_file %G file-name The parameter PRE noted above permits an initial set of commands to be read from a file. The %G command allows a command file to be nominated at any time during the course of editing, for example, to allow a different set of macros to be set up, or to invoke a complex but stereotyped sequence of editing operations. It is even possible that the file of commands itself contains a %G command. Such recursion is permitted up to a depth of (approximately) 15. 3 %P__Put_key_definitions_to_file %P file-name This command allows all the key definitions which have been made since the start of the current editing session to be saved in a specified file for subsequent recall (as PRE or via %G). Definitions of control keys are represented in a coded form, using only printing characters. 3 %R__Right_shift_display %R If some lines are longer than your terminal can accommodate, the %R command allows them to be seen. %Rn shifts the display by n columns to the right. The value of n can be positive or negative and its effect is cumulative, that is %R10 followed by %R30 is equivalent to %R40. %R0 or %R will restore the display to its leftmost position. 3 %T__Set_Tab_Positions %T=t1,t2,t3, ....,t15 or %T ? This command sets the columns that text following a tab character is aligned to. The parameters t1,..., t16 must be integers and given in order of increasing value otherwise the command fails. It is not necessary to specify all 15 values; any left out will take the value of the last one typed. The form with a question mark as parameter displays the current values. Note that for text to be aligned to tab positions, the TAB EXPANSION mode must be selected (by %E or specified as a command option/qualifier). 3 %W__Wipe_record_of_deleted_lines %W The fact that the Editor retains a record of all lines deleted from the file, against the possibility of later re-insertion, can sometimes be a nuisance, since lines that are definitely not wanted again may get in the road of those that are. The Wipe command "%W" causes the record of the last deleted lines to be lost so that they become irrevocable. It may be necessary to use Wipe in order to bring in a large amount of data for a secondary input file to replace a large chunk deleted from the main file. 3 %Ci__IMP_syntax_checking %Ci or %CI These variants of the Close command are used to invoke a check on the syntax of an IMP program file before it is finally closed. The first form (lower-case 'i') signifies that a return is to be made to the editor whenever an error is detected; the second form (upper-case 'I') implies checking through the entire file without interaction. The dialect of IMP which the checker accepts is the agreed common subset of EMAS IMP80 and VAX/VMS IMP77. Some, but not all, of the features which are peculiar to one of these dialects are also accepted, in general with a "Non-standard" warning. The checker detects most of the faults which would be reported by the compilers, though there may be minor discrepancies due to organisational differences and some of the table limits are inevitably different. This is a novel feature and feedback from users would be helpful in refining it. 3 Execute_system_command If ! is entered on the command line, is passed to the host operating system for execution. For example !files on EMAS will execute the command 'files'. Note that on VAX/VMS !spawn can return you to command level in a 'spawned' process. When you log off you will be returned to VECCE. 2 MACROS The upper-case letters 'A' to 'W' and the punctuation symbols have a fixed significance to ECCE. All the lower-case letters, and the upper-case letters 'X' to 'Z', are available for definition as macros, that is as abbreviations for sequences of characters. So also are the control keys. 3 Command_and_text_macros The printing keys mentioned have a significance as macros only within commands, since in data-entry mode or within text strings they stand for themselves. Any of them may be used in a position where a command letter is expected and may stand for any sequence or partial sequence of commands. The letters 'X' to 'Z' and 'x' to 'z' have two additional properties: first, they may be used in a position where a text parameter is required; and, second, they may be defined to stand for a text sequence appearing in the file being edited, or the secondary input file, using the Define Macro ("^") command. Initially the lower-case letters 'a' to 'w' are defined to be equivalent to their upper-case equivalents. Where command letters appear within a macro definition, it is sensible to use the upper-case form if it is intended to utilise the basic meaning of that command letter, lest the lower-case form should have been re-defined. The control keys are always interpreted as macros, in one of two ways, depending on how they have been defined. One form of definition forces interpretation of the sequence of characters for which the key stands as a command sequence; the other causes the use of the key to be equivalent to typing the characters explicitly as part of the text being entered. The distinction is indicated when defining one of these keys by using a colon to define a command sequence and an equals-sign to define a direct replacement sequence. One particular use of text macros is to enable non-printing characters to be manipulated. Using the %K command, one of the printing characters x, y or z or any control key may be defined to represent the non-printing character typed after the 'equals' sign. The macros x, y or z can then be used as parameters to any command requiring one, eg Fx, and the control-key can be typed in data entry mode to enter it into the file or in response to any command with an exclamation mark as a parameter. Note that the content of a command macro is interpreted, not when the definition is made, but when the macro is used. 3 Exclamation-mark_in_macro When an exclamation-mark is used in place of a text parameter within a sequence invoked as a command macro, the effect is to cause the actual text parameter to be sought at the point following the macro call. Here again any of the forms of text parameter -- delimited string, text macro letter, ditto, or exclamation mark -- are valid. 3 Key_enquiry_command %Q The Special command "%Q" is provided as a way of finding out the current significance of any key. It may be used as a one-shot command or to cause entry to Enquiry mode. The first involves pressing the key about which information is required immediately after the "%Q" (followed by RETURN if not a control key). The second is indicated by typing just "%Q" followed by RETURN. In this case the Editor continues to prompt for keys to be explained until a colon is typed; as before an immediate-action key does not require a following RETURN. For any basic editing command letter, a brief indication of the meaning of the letter is given. For a key defined as a macro, the current definition of that macro is printed out; for a multi-line sequence, only the first line is printed out. 3 Key_definition_command %K The Special command "%K" is used to define or re-define keys. Like "%Q," it may be used as a one-shot command or to enter a Key-definition mode. In the first case, a single definition is entered along with the "%K", while in the definition mode, the Editor continues to prompt for definitions until a colon is typed. Each definition takes the form of the key to be defined followed by a colon or equals sign followed by the text making up the definition. When a control key is being defined, depression of the control key in the course of the definition causes an asterisk to be echoed. Use of the colon rather than equals-sign as separator indicates that a control key is being defined to stand for a command sequence rather than a direct replacement text string. To cover the case where it is realised after typing in a command that it could usefully have been defined as a macro, an alternative form of definition is provided to define the key to be the text of the last explicitly typed command line. This is: key to be defined followed by the ditto symbol ("). 3 Use_of_command_macros After the definitions %K x=F/basically/ %K y=MR*I/ : the following equivalences would apply xS/actually/ -> F/basically/S/actually/ M-10 x T/y/ I/,/ -> M-10 F/basically/ T/y/ I/,/ ycomment/ -> MR*I/ :comment/ A command macro letter may abbreviate any initial part of a command sequence; the last example illustrates a case where it includes the opening delimiter for a text string and a fixed initial part. The effect of typing a macro character (letter or control key) is always literal substitution of the sequence of characters for which it stands. Where a macro letter is defined to be a complete group of two or more commands it is always sensible to include parentheses in the definition, as in "%K z=(F.error.I.**.)" rather than just "%K z=F.error.I.**.", so that if a repetition count is attached to the macro letter, it will apply to the whole sequence and not just the last component (see next Section). The definition of one macro may include a reference to another, but any form of circular definition is invalid and an occurrence of any of the macro letters within text delimiters always stands for itself. One common case where temporary macros can be useful is when some but not all occurrences of a text string, say "max", have to be changed to something else, say "count", inspection being required to determine which. With the two definitions %K x=F/max/ %K y=S/count/x "x" can be used to find the first occurrence of "max" and thereafter "y" or "x" depending on whether a change is required or not. Macro definitions persevere until the end of the editing session or until the relevant key is re-defined. 2 PROGRAMMED_COMMANDS This section describes facilities for constructing more powerful commands from simple commands. So far, the only form of compound command structure introduced has been the facility to type more than one command in a single command line, with the consequential capability of repeating the complete sequence by subsequently typing a repetition number instead of another command. 3 Caution The structuring facilities described in the following paragraphs can be used to carry out some quite complicated operations, but commands making heavy use of them tend to become rather difficult to understand. It is not sensible to try to devise a programmed command of any significant complexity while working at the terminal. Contemplation in tranquillity is required. Some users note in a log-book those which they have found useful in the past. 3 Command_sequences Any sequence of commands may be enclosed in parentheses and treated as a single command. In particular this permits a repetition count to be attached to a sequence of commands. For example, the command "(F.integer.I.%.)3" has the effect of inserting a percent sign in front of the next three occurrences of "integer". Compare "F.integer. i.%.3" which inserts three percent signs in front of the first occurrence of "integer" only, and "F.integer.3 i.%.3" which does the same in front of the third occurrence only. For this simple case, it would be almost as convenient to type the pair of commands as one command line, and then type a 2 to repeat it twice more, but that option would not cover cases where the bracketed sequence is just part of a complete command line. A command sequence fails when any component of it fails, so that an asterisk attached to a bracketed command sequence specifies indefinite repetition until one of the contained commands fails. As a check against infinite looping, a limit of 10,000 iterations is applied to the repetition of bracketed commands. 3 Alternative_command_sequences Another form of compound command is one providing a number of alternatives. This consists of two or more individual commands or command sequences separated by commas. Execution starts with the first command and if that alternative is completed without failure, the other alternatives are ignored. If any of the commands making up the first alternative fails, then the second alternative (following the first comma) is executed, and so forth. Only if a failure occurs on the last alternative is the whole compound command considered to have failed. For example, it might be required to include, as a component of a more complex command, an instruction to position the pointer at the next space on the line, or at the end of the line if there is no space to the right of the pointer. The command "(F1/ /, R*)" could be used for the purpose. Consider also the problem of interchanging two text strings, say "basically" and "actually", throughout a complete file. Obviously, the commands (F/basically/S/actually/)* M-* (F/actually/S/basically/)* would end up with all occurrences of both words converted to "basically". One solution would be to convert all occurrences of the word "basically" to some unique sequence of characters, make the other change through the file, and finally convert the unique character sequences to "actually". A preferable approach, using alternative sequences, permits this kind of edit to be made progressively on a single pass through the file. First consider the sequence "(R,M)". Right-shift fails only when the pointer is at the end of a line, so that this sequence performs a Right-shift except at the end of a line, when it performs a Move. The Move, and hence the compound command, fails only at the end of the file. Accordingly this is a command which makes it possible to 'inch' through a file on a character by character basis. The case under consideration can be handled by expanding this sequence to include alternatives to test for the two text strings and make the necessary change, leading to: (V/basically/S/actually/, V/actually/S/basically/, R, M)* This framework, using a set of Verify commands together with the 'inching' sequence "R,M", is one that can be used for a variety of different requirements. 3 Inverted_failure_condition If a command, simple or bracketed, is followed by the symbol '\', the failure condition for the command is inverted so that successful execution causes a failure and unsuccessful execution does not. This in no way alters what the Editor attempts to do by way of carrying out the command, which has its customary effect, if any, except that it is deemed to have failed when it has not, and conversely. This curious effect is sometimes useful, most obviously with the Verify command. For example, "V.+." makes it possible (in effect) to make the following command conditional on there being a plus-sign immediately to the right of the pointer; "V.+.\" to make the following command conditional on there not being a plus-sign immediately to the right of the pointer. 3 Cancelled_failure_condition If a command, simple or bracketed, is followed by the symbol '?', any failure condition arising in the execution of the command is cancelled, that is, any further action is taken on the basis that the command succeeded. As with inversion, this in no way alters the effect of the command itself. For example, suppose it was required to insert an ampersand in front of each line in a file which started with a exclamation-mark. The sequence "(V/!/ I/&/ M)*" is not adequate since the part within brackets will fail on any line not starting with an exclamation mark and cause termination of the whole sequence. It is only the failure of the Move which should cause failure of the sequence. Bracketing the Verify and the Insert and appending a question-mark achieves the desired effect: ( (V/!/ I/&/)? M)* 3 Further_examples The examples which follow either might be useful in themselves or illustrate general techniques. Many such commands are not rigorous, but depend on the originator of the document maintaining a consistency of style in terms of such matters as the inclusion or omission of spaces. (a) (MR)* Find first blank line (MR\)* Find first non-blank line The command Right-shift fails at the end of the line. Immediately after a Move, it will fail only if the line is blank. Hence (MR)* causes Moves to be executed until either the end of the file or a blank line is reached. Inverting the failure condition on R locates the first non-blank line, but note that a final L is required if the pointer is to end up at the start of the line. (b) (RI. .)* E- Double-space a line This sequence inserts a space to the right of each existing character (including spaces) on the line. The final E- removes the last space inserted, because trailing spaces can be a source of confusion. (c) (R* (L D/ /)* M)* Delete trailing spaces This command will eliminate any trailing spaces that may have crept into the file. On each line, the pointer is moved to the end and then successive attempts are made to Left-shift and Delete a space. (d) ( (RLI/ /4)? M)0 Create left margin (of 4 spaces) The obvious command would be simply "(I/ /4M)0", but that would add spaces to blank lines, which is undesirable. Hence the "RL" to check that the line is not blank. (e) F.sin.(V.sin(.,S.evil.) Replace selected occurrences The form of this command illustrates the case where it is required to pick out certain occurrences of a word for alteration but not others. A programmer has inadvertently employed "sin" as a variable in a program which also makes use of the mathematical function "sin(...)". The command sequence locates an occurrence of "sin", then verifies that it is followed by a left parenthesis by "V.sin(." or else changes it to "evil". 2 IMPLEMENTATIONS One of the objectives of the design of ECCE is that it should not be system-dependent, but should be implementable on a range of machines. This video version as described in earlier sections is implemented uniformly on EMAS 2900, VAX/VMS and the Computer Science Department's Advanced Personal Machine. The syntax checking capability is a by-product of work on the programming environment for the APM. The detail of some features, for example those involving naming of files, is inevitably bound up with a particular operating system. The performance of the editor as seen by the user is also affected by the system, and, more especially, the mode of connection. 3 Mode_of_connection The most important factor affecting editor performance is the mode of connection of the user's terminal. In general, the more direct the connection, the better the performance will be. ECCE has a number of options which make it possible to exercise some control over the frequency of interaction and the volume of data transferred. In addition to affecting the responsiveness of the editor, an indirect connection over the network involves an increased possibility of unintended modification of the data stream sent to the terminal, leading to an erroneous screen image which does not match the state of the file. It may also rule out the use of cursor controls and function keys. If the screen image looks curious at any time, the "%D" command should be used to re-display it. 3 Network_Terminal_Controllers (PADs) Most remote terminals in the ERCC network and on JANET will be connected via Packet Assembler/Disassemblers (PADs). Unlike the old TCP's a PAD does not have a mode which allows the transmission without echoing of escape sequences (which are produced by control keys on many terminals). Therefore VECCE drives such terminals in NATIVE mode. Since at present VAX/VMS terminals are always connected in native mode VECCE takes no action, but the EMAS implementation explicitly sets the PAD into native mode. Should the PAD's be enhanced in such a way as to permit escape sequences to be transmitted without echoing, VECCE could be modified to take advantage of that mode as it does NOT assume single-character interaction. 3 Supported_Terminals The VAX/VMS version of ECCE derives its terminal characteristics from the system database and only requires the correct terminal type to be set. New terminals can be added by writing a TERMTABLE.TXT description and adding it as described in the DEC RTL manual in the section on the SMG$ routines. Termtable descriptors currently exist for all DEC terminals and for Hazeltine Esprit's, Newbury 7000 and 8000's and BBC Micro's using XTALK. The list of terminals currently supported as videos in the EMAS implementation of ECCE is as follows (ERCC enumeration): code terminal highlight part-screen scroll 6 Perkin-Elmer Bantam - - 7 Lynwood reverse - 8 DEC VT52 - - 10 ADM-3A - - 11 Visual 200 reduced yes 12 VT105 reverse yes 13 Hazeltine Esprit increased yes 15 Newbury 8000 underline yes 16 Pericom reverse yes 20 Volker Craig 404 - - 21 ICL KDS7362 reduced yes 22 Hazeltine Esprit II increased yes 23 Hazeltine Esprit III increased yes 24 ADM-5 - - 25 Visual 50/55 reduced yes 27 Datatype X5A reverse yes 28 ANSI reverse yes 31 Wyse 132 col reverse yes 32 Wyse 75/85 reverse yes 33 VT100 reverse yes Note that all DEC-like terminals are not exactly equivalent as regards the provision of an 'insert' mode. VT200-like terminals such as the Wyse, Datatype X5A, Pericom have this mode whereas some VT100 - like models which conform to the ANSI standard do not. It is therefore important to make sure the terminal is set correctly. Probably the easiest method of finding out a terminal's capability it to inform VECCE that it is, for example, a WYSE and see if INSERT mode and I! work correctly.