\documentstyle[a4,12pt]{article} \begin{document} \author{Hamish Dewar} \title{ECCE} \maketitle \parskip .1 in \setcounter{secnumdepth}{10} \parindent 0in \section{Preamble} \hspace*{1.1 in} E C C E \hspace{0.2 in} F O R \hspace{0.2 in} V I D E O S \hspace*{0.2 in} This version of ECCE combines the capabilities of a conventional context editor with many of the features of a screen editor. It is available on EMAS and VAX/VMS as well as the APM. \hspace*{0.2 in} The APM version does not at present include Spelling checking (Q), syntax checking (\%Ci), or built-in help (\%H). \\ \hspace*{2.7 in} Hamish Dewar April 1983 \section{INTRODUCTION TO TEXT EDITING} 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. \subsection{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: \hspace*{0.2 in} longing \hspace{0.2 in} for those wide open \hspace{0.4 in} spaces would look like this if the spaces were replaced by ampersands: \&\&\&longing\&\&\&for\&those\&\&wide\&open\&\&\&\&\&\&spaces \hspace*{0.2 in} 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. \hspace*{0.2 in} 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. \subsection{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. \subsection{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. \subsubsection{Video feedback} 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. 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: \hspace*{1.1 in} **END** This line does not actually exist in the file and therefore cannot be edited. \subsubsection{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. \small\tt \begin{verbatim}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 \end{verbatim}\rm \normalsize 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. \subsection{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 command mode, the ordinary printing keys are used to enter strings of characters to be interpreted as editing commands; in data-entry mode, these keys are used to enter text as part of the file. In the latter mode, the actual video cursor indicates the position of the Editor's file pointer, by highlighting the character immediately to the right of the pointer; (recall that the Editor's pointer is understood to lie between a pair of characters). 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. \subsection{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 data-entr 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. \section{ADVICE FOR 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: \small\tt \begin{verbatim}(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. \end{verbatim}\rm \normalsize 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: \small\tt \begin{verbatim} Move (and Move back) \ cursor movement \ or control key Get and Kill / equivalents Insert and Erase / Find Substitute \end{verbatim}\rm \normalsize 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. \section{CALLING THE EDITOR} \small\tt \begin{verbatim} (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 (c) To create a new file called "PROG34" from scratch: VECCE .N/PROG34 The ".N" 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 Again this is a special case of (b) with a null new file. Alteration commands are dis-allowed in this mode of operation. (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 \end{verbatim}\rm \normalsize 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. \small\tt \begin{verbatim} (f) examples including option specifiers: VECCE CURTEXT-MINWIN=12-WTOP=6 VECCE CURTEXT-NOMATCH-PRE=WPCOMMANDS \end{verbatim}\rm \normalsize \subsection{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: \small\tt \begin{verbatim} (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). \end{verbatim}\rm \normalsize \subsection{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. \subsection{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"). \section{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: \hspace*{0.5 in} typing a command line followed by RETURN \\ \hspace*{0.5 in} typing a Special command followed by RETURN \\ \hspace*{0.5 in} 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. \subsection{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. 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. \subsection{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. \subsection{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: \hspace*{0.3 in} by one of the six text parameter macro letters (X,Y,Z,x,y,z); \\ \hspace*{0.3 in} by the ditto symbol("); \\ \hspace*{0.3 in} 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). \subsection{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. \subsection{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. \subsection{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. \subsection{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. \subsection{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. \subsection{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. \section{INDIVIDUAL EDITING COMMANDS} \subsection{Move (forward one line) M} The Move command causes the file pointer to be moved from its current position to the start of the following line. \hspace*{0.3 in} Attaching a repetition number to a Move command provides a means \\ \hspace*{0.3 in} of moving forward a fixed number of lines. For example, the \\ \hspace*{0.3 in} command "M99" issued at the start of the file, causes the pointer \\ \hspace*{0.3 in} 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. \hspace*{0.3 in} It is legitimate to Move from the last line in the file to the \\ \hspace*{0.3 in} end-of-file position, but then further Moves will fail. \subsection{Move back (one line) \hspace{0.3 in} M-} 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. \subsection{Cursor Down \hspace{0.9 in} \}} 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. \hspace*{0.3 in} The command is typically the definition of a cursor control key. \\ \hspace*{0.3 in} With this and the other cursor movement commands, the resulting \\ \hspace*{0.3 in} line position may be beyond the end of the line (that is, to the \\ \hspace*{0.3 in} right of the last printing character). This is often a temporary \\ \hspace*{0.3 in} state en route to another position, and so the fact that the \\ \hspace*{0.3 in} cursor is out in space does not of itself imply any extension of \\ \hspace*{0.3 in} the line, but if any text is entered in this situation, the gap \\ \hspace*{0.3 in} between the existing end of the line and the file pointer is \\ \hspace*{0.3 in} first filled with spaces. The command fails when the file pointer is on (or beyond) the last line of the file. \subsection{Cursor Up \hspace{1.1 in} \{} 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. \hspace*{0.3 in} 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. \subsection{Right-shift (one char) \hspace{0.2 in} R} 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. \hspace*{0.3 in} Hence "R*" takes the pointer from anywhere within the line to the \\ \hspace*{0.3 in} right hand end of the line. \subsection{Left-shift (one char) \hspace{0.3 in} L} 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. \hspace*{0.3 in} Hence "L*" takes the pointer from any position to the start of \\ \hspace*{0.3 in} the line. \subsection{Cursor Right \hspace{0.9 in} $>$} 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. \hspace*{0.3 in} 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. \subsection{Cursor Left \hspace{0.9 in} $<$} The Cursor Left command is identical in effect to the left-shift command. It is provided for reasons of symmetry. \subsection{Find TEXT \hspace{1.1 in} F} 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. \hspace*{0.3 in} For example, adding a repetition count to a Find command, as in \\ \hspace*{0.3 in} "F/cat/3", will locate the third occurrence of the sequence \\ \hspace*{0.3 in} "cat". The repetition does not have to be in the form of a count \\ \hspace*{0.3 in} attached to the original command. For example, it is a common \\ \hspace*{0.3 in} experience to discover, after a Find has been executed once, that \\ \hspace*{0.3 in} the character sequence chosen in fact appears earlier in the file \\ \hspace*{0.3 in} than the intended position. In this case the Find command can \\ \hspace*{0.3 in} simply be repeated, by typing 1 as a repetition command, until \\ \hspace*{0.3 in} 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. \hspace*{0.3 in} For example, "F9/cat/" limits the scope of the search to the \\ \hspace*{0.3 in} 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. \subsection{Find back TEXT \hspace{0.7 in} F-} 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. \subsection{Traverse TEXT \hspace{0.8 in} T} 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. \subsection{Verify TEXT \hspace{0.9 in} V} 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. \hspace*{0.3 in} The Verify command only has a use in conjunction with programmed \\ \hspace*{0.3 in} commands (see the section on this topic). \subsection{Delete TEXT \hspace{0.9 in} D} 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. \subsection{Insert TEXT \hspace{0.9 in} I} 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: \hspace*{0.5 in} quoted text between delimiter characters \\ \hspace*{0.5 in} a text macro letter ('X'-'Z' or 'x'-'z') \\ \hspace*{0.5 in} the ditto character \\ \hspace*{0.5 in} 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). \hspace*{0.3 in} For the direct-entry form, in most implementations, a certain \\ \hspace*{0.3 in} amount of space is opened up at the position of the file pointer \\ \hspace*{0.3 in} to permit the text to be typed in. Then when the terminating key \\ \hspace*{0.3 in} is pressed, the line is closed up again. In some \\ \hspace*{0.3 in} implementations, no space is opened up, and the line \\ \hspace*{0.3 in} 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). \hspace*{0.3 in} Specifiying a repetition count with Insert is a convenient way of \\ \hspace*{0.3 in} 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). \subsection{Overwrite with TEXT \hspace{0.4 in} O} 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. \hspace*{0.3 in} The possible forms of text parameter are as for Insert. The \\ \hspace*{0.3 in} exclamation-mark form ("O!" or just "O") again provides a \\ \hspace*{0.3 in} direct-entry capability for a single piece of text. It is useful \\ \hspace*{0.3 in} only in command mode, since data-entry mode provides that \\ \hspace*{0.3 in} capability all the time. The failure condition is the same as for Insert. \subsection{Substitute TEXT \hspace{0.7 in} S} 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. \hspace*{0.3 in} The operation of substitution involves two text strings, one to \\ \hspace*{0.3 in} be removed, the other to be inserted. In ECCE the first of these \\ \hspace*{0.3 in} is established by one command, typically a Find, and the second \\ \hspace*{0.3 in} is specified as the parameter to Substitute. Thus, for example, \\ \hspace*{0.3 in} "F/this/ S/these/" will alter the first occurrence of "this" to \\ \hspace*{0.3 in} "these". One advantage of splitting the function between two \\ \hspace*{0.3 in} commands is that they can be issued independently and the effect \\ \hspace*{0.3 in} 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. \subsection{Get TEXT (one line) \hspace{0.4 in} G} 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. \hspace*{0.3 in} The Get command is the way in which complete lines are inserted \\ \hspace*{0.3 in} in a file. The most frequently used form is "G!" (or "G"). In \\ \hspace*{0.3 in} this case the text is not embedded in the command as a text \\ \hspace*{0.3 in} string, but is requested when the Get is executed by the Editor. \\ \hspace*{0.3 in} A repeated Get expects a fresh line each time; it does not cause \\ \hspace*{0.3 in} the first line typed to be inserted again. Thus "G!5" (or "G5") \\ \hspace*{0.3 in} causes five lines to be requested and inserted, in the order \\ \hspace*{0.3 in} typed, above the current line. The Get command fails if the line typed in starts with a colon. \hspace*{0.3 in} The failure condition is an arbitrary convention, which may be \\ \hspace*{0.3 in} used to cause a repeated Get to terminate. In particular, it \\ \hspace*{0.3 in} permits the use of "G!*" (or "G*") to insert an indefinite number \\ \hspace*{0.3 in} of lines (which it would be inconvenient to have to count). \subsection{Kill \& Kill back \hspace{0.5 in} K K-} 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. \hspace*{0.3 in} Kill does not simply erase all the characters on a line leaving \\ \hspace*{0.3 in} it blank; it removes the line altogether. Kill followed by Get \\ \hspace*{0.3 in} (eg "KG" or "K2G3") is a common command sequence when replacing a \\ \hspace*{0.3 in} number of complete lines by other complete lines. The command fails if the file pointer is at the end of the file. 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. \subsection{Erase (one char) \hspace{0.5 in} E E-} 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. \hspace*{0.3 in} Hence "E*" erases all characters on the line to the right of the \\ \hspace*{0.3 in} pointer. 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. \hspace*{0.3 in} Hence "E-*" erases all characters to the left of the pointer. \subsection{Case-change (char) \hspace{0.5 in} C} 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. \hspace*{0.3 in} Hence "C*" changes the case of all letters to the right of the \\ \hspace*{0.3 in} pointer on the current line. \subsection{Uncover TEXT \hspace{0.9 in} U} 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. \hspace*{0.3 in} The Uncover command is applicable where it is most convenient to \\ \hspace*{0.3 in} specify a deletion as 'up to' a particular character or sequence \\ \hspace*{0.3 in} of characters. With an explicit scope, Uncover can delete part \\ \hspace*{0.3 in} of the starting line, a number of complete lines, and an initial \\ \hspace*{0.3 in} 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. \hspace*{0.3 in} An unlimited search can be specified by means of "U*". \subsection{Break (line in two) \hspace{0.4 in} B} 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. \hspace*{0.3 in} Break creates two lines from one. One of its uses is to split \\ \hspace*{0.3 in} lines which may have become undesirably long as a result of \\ \hspace*{0.3 in} insertions. \\ \hspace*{0.3 in} Break with the pointer at the start of a line creates a blank \\ \hspace*{0.3 in} 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. \subsection{Join (two lines) \hspace{0.6 in} J} 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. \subsection{Insert/Get back \hspace{0.5 in} I- G-} 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. \hspace*{0.3 in} For example, the command "I-0" brings in at any point all the \\ \hspace*{0.3 in} text deleted at the last alteration site, and the sequence "ERI-" \\ \hspace*{0.3 in} (Erase, Right, Insert back) reverses the order of a pair of \\ \hspace*{0.3 in} 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. \hspace*{0.3 in} For example, "KMG-" (Kill, Move, Get back) reverses the order of \\ \hspace*{0.3 in} a pair of lines. \subsection{Overwrite back \hspace{0.7 in} O-} 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. \subsection{Print \hspace{1.3 in} P} 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. \subsection{Next/previous unit \hspace{0.3 in} N N-} 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. \subsection{Query Spelling \hspace{0.7 in} Q} 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. \subsection{Move to line number n \hspace{0.3 in} \#n} This command causes the file pointer to be moved from its current position to the start of the line specified. \hspace*{0.3 in} Lines are numbered from 1 at the start of the file and the \\ \hspace*{0.3 in} numbers relate to the current state of the file, not its state at \\ \hspace*{0.3 in} the start of editing. If no line number is specified in the \\ \hspace*{0.3 in} 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. \hspace*{0.3 in} Note that the parameter $<$n$>$ is not a repetition count. \subsection{Increment number by n \hspace{0.3 in} +n} The Increment command (plus-sign) is used to add the value specified by $<$n$>$ 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. \hspace*{0.3 in} This command is most useful when it is required to adjust more \\ \hspace*{0.3 in} than one number by a constant amount. The value 1 is understood \\ \hspace*{0.3 in} if $<$n$>$ is omitted. The form "+-" may be used to specify a \\ \hspace*{0.3 in} negative increment. Letters are included to cover the case where \\ \hspace*{0.3 in} 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. \hspace*{0.3 in} Note that the parameter $<$n$>$ is not a repetition count. \subsection{Adjust line length \hspace{0.5 in} A} 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 \hspace*{0.3 in} The detailed specification which follows is quite complicated. \\ \hspace*{0.3 in} The main points to note are: \\ \hspace*{0.3 in} a single Adjust will make the current line an acceptable length \\ \hspace*{0.3 in} and leave the file pointer at the start of the (perhaps revised) \\ \hspace*{0.3 in} following line; \\ \hspace*{0.3 in} A* will (try to) produce adjusted lines up to the end of a \\ \hspace*{0.3 in} paragraph, a paragraph being understood to terminate with a blank \\ \hspace*{0.3 in} 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. \hspace*{0.3 in} For the purposes of Adjust, a word is defined to be any sequence \\ \hspace*{0.3 in} of characters terminated by a space or end of line. Appending a \\ \hspace*{0.3 in} word implies inserting a space plus the word at the end of the \\ \hspace*{0.3 in} first line, and removing the word plus its terminating space from \\ \hspace*{0.3 in} the second line (removing the whole line in the case that the \\ \hspace*{0.3 in} word is the only word on the line). \subsection{At column position n \hspace{0.3 in} @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 $<$n$>$. 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, $<$n$>$ is reduced to prevent this. \hspace*{0.3 in} Columns are numbered from zero upwards, so that, for example, @40 \\ \hspace*{0.3 in} has the natural interpretation of placing text half-way along an \\ \hspace*{0.3 in} 80-column line. Spaces to the right of the file pointer are not \\ \hspace*{0.3 in} affected by this command, and only space characters immediately \\ \hspace*{0.3 in} to the left of the file pointer are removed in seeking to align \\ \hspace*{0.3 in} leftwards. \\ \hspace*{0.3 in} Using "@" with a large $<$n$>$ has the effect of right-aligning the \\ \hspace*{0.3 in} text following the pointer. The @n command fails if space-deletion fails to achieve correct alignment. \hspace*{0.3 in} Note that the number $<$n$>$ is not a repetition count. \subsection{Set Marker \hspace{1.0 in} $\hat{ }${}} 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: \hspace*{0.3 in} the Define Macro command \\ \hspace*{0.3 in} the Revert to Marker command \\ \hspace*{0.3 in} the Switch Inputs command A marker is also cancelled if the text surrounding it is deleted from the file. \subsection{Define Macro 'X'...'z' \hspace{0.2 in} $\hat{ }${}n} 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 $<$n$>$ (1 to 6 respectively). For example "$\hat{ }${}2" is used to define 'Y' and "$\hat{ }${}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. \hspace*{0.3 in} Although text parameters typed within commands cannot, for \\ \hspace*{0.3 in} syntactic reasons, contain line breaks, there is no such \\ \hspace*{0.3 in} restriction on the definition of macro letters by means of this \\ \hspace*{0.3 in} command, subject to an overall limit on length imposed by the \\ \hspace*{0.3 in} implementation. However, multi-line text strings are valid only \\ \hspace*{0.3 in} for the insertion group of commands, not for the text matching \\ \hspace*{0.3 in} group. \\ \hspace*{0.3 in} It is immaterial whether the marker is ahead of the current \\ \hspace*{0.3 in} position or vice versa. The command fails if no marker is set and the file pointer is not at a matched text position. \hspace*{0.3 in} For convenience, with a marker set, a second Set Marker command \\ \hspace*{0.3 in} (that is, simple caret without accompanying $<$n$>$) is interpreted \\ \hspace*{0.3 in} as Define Macro defining 'X'. \subsection{Revert to Marker \hspace{0.6 in} =} 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. \subsection{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. \hspace*{0.3 in} Note that actual alteration commands are disallowed in this mode. \\ \hspace*{0.3 in} The mode is most useful in conjunction with some of the more \\ \hspace*{0.3 in} specialised movement commands such as Next, Cursor Down and \\ \hspace*{0.3 in} Query. \subsection{Switch Inputs \hspace{0.8 in} \$} 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): \hspace*{1.0 in} \$ $\hat{ }${} 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. \section{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). \subsection{Pre-definition file \hspace{0.3 in} *PRE} 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: \hspace{0.3 in} -PRE=WPPREDEF \hspace{0.3 in} -PRE=ECUU99.PROJ\_DEF1 \subsection{Terminal type \hspace{0.7 in} *TTYPE} The parameter TTYPE 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: \hspace*{0.9 in} -TTYPE=12 \hspace{0.5 in} -TTYPE=13 \\ \hspace*{0.9 in} \{VT100\} \hspace{0.7 in} \{Esprit\} \subsection{Window dimensions \hspace{0.4 in} *WTOP, *WROWS, etc} \small\tt \begin{verbatim}* 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 \end{verbatim}\rm \normalsize 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. \subsection{Effective window \hspace{0.5 in} *MAXWIN, MINWIN} \small\tt \begin{verbatim}* MAXWIN -- maximum window Default: WROWS Range: 1..WROWS MINWIN -- minimum window Default: ? Range: 1..WROWS \end{verbatim}\rm \normalsize 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. \subsection{Text line width \hspace{0.5 in} WIDTH, 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. The initial default value is zero. \subsection{Letter-case matching \hspace{0.2 in} MATCH/NOMATCH} 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. \subsection{Displaying pointer \hspace{0.3 in} HILIGHT/MARK} 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. \subsection{Updating strategy \hspace{0.4 in} LATE/EARLY} 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. \section{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). \subsection{modify Environment \hspace{1.1 in} \%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 modifiable 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. \subsection{set Display size $<$n$>$ \hspace{0.9 in} \%Dn} This command provides an alternative means of setting MINWIN, without entering Environment setting mode. When used by itself, without $<$n$>$, 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). \subsection{set Line width/Margin $<$n$>$ \hspace{0.6 in} \%Ln / \%Mn} 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. \subsection{define Secondary input \hspace{0.8 in} \%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. \subsection{Get commands from file \hspace{0.8 in} \%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. \subsection{Put key definitions to file \hspace{0.5 in} \%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. \subsection{Wipe record of $<$n$>$ 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 $<$n$>$ 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. \subsection{IMP syntax checking \hspace{1.0 in} \%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. \section{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. \subsection{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 ("$\hat{ }${}") 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. Note that the content of a command macro is interpreted, not when the definition is made, but when the macro is used. \subsection{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. \subsection{Key enquiry command \hspace{0.6 in} \%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. \subsection{Key definition command \hspace{0.4 in} \%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 ("). \subsection{Use of command macros} \small\tt \begin{verbatim} 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/ \end{verbatim}\rm \normalsize 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 \hspace*{0.6 in} \%K x=F/max/ \\ \hspace*{0.6 in} \%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. \section{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. \subsection{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. \subsection{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. \subsection{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 \hspace*{0.3 in} (F/basically/S/actually/)* \\ \hspace*{0.3 in} M-* \\ \hspace*{0.3 in} (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: \hspace*{0.3 in} (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. \subsection{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. \subsection{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: \hspace*{0.3 in} ( (V/!/ I/\&/)? M)* \subsection{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. \small\tt \begin{verbatim}(a) (MR)* Find first blank line (MR\)* Find first non-blank line \end{verbatim}\rm \normalsize 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. \small\tt \begin{verbatim} (b) (RI. .)* E- Double-space a line \end{verbatim}\rm \normalsize 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. \small\tt \begin{verbatim}(c) (R* (L D/ /)* M)* Delete trailing spaces \end{verbatim}\rm \normalsize 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. \small\tt \begin{verbatim}(d) ( (RLI/ /4)? M)0 Create left margin (of 4 spaces) \end{verbatim}\rm \normalsize 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. \small\tt \begin{verbatim} (e) F.sin.(V.sin(.,S.evil.) Replace selected occurrences \end{verbatim}\rm \normalsize 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". \section{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. \subsection{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. \subsection{Network Terminal Controllers} New software on some of the Terminal Controllers on the ERCC network provides a much improved screen handling mode which the editor uses if available. On other TCPs, as an interim measure, interference with data may be reduced by entering TCP Graph mode and input of control characters may be enabled by entering Z mode. With the old TCP software, the screen image is particularly susceptible to corruption as a result of typing ahead; this should be avoided as much as possible. ****** \hspace{0.3 in} NB ***** In order to permit the use of Escape sequence controls, while the editor is being run the system Attention character is changed from Escape to Null, which is keyed by CONTROL+@. Any use of this Attention character cancels video mode, so that it should be used only in extremis. \subsection{Supported Terminals} The list of terminals currently supported as videos in ECCE is as follows (ERCC enumeration): \small\tt \begin{verbatim} code terminal highlight part-screen scroll 6 Perkin-Elmer Bantam - - 8 DEC VT52 - - 11 Visual 200 reduced yes 12 VT100 reduced yes 13 Hazeltine Esprit increased yes 15 Newbury 8000 - yes 20 Volker Craig 404 - - 21 ICL KDS7362 reduced yes \end{verbatim}\rm \normalsize \section{ Quick Summary of ECCE commands} This summary is not exhaustive. \small\tt \begin{verbatim}Command format: e :n/newfile Edit a new file (.n on ECSVAX) e oldfile Edit an existing file e oldfile/newfile Edit an old file into a new one. Getting out once in: %c Leave editor under control, updating the edited file %a Abort from editor leaving edited file untouched %d %d Redraw screen. (You can redraw it lines high) Basic editing commands: In the summary below is any number. may be 0 meaning "do it as far as you can in that direction". text is just an arbitrary text string. m m- move forwards/backwards lines (also etc.) l Move left characters in line (also use key) r Move right characters in line (also use ) f/text/ f-/text/ Find next occurrence of "text" (case-blind) s/text/ Substitute "text". Use after "find" i/text/ Insert "text". If /text/ is omitted, takes input from keybd. e e- erase characters forwards/backwards from cursor g "get" i.e. insert lines of text. (I inserts WITHIN line) g- "unkill" last lines killed. Use this to move text. k kill (delete) lines of text u/text/ Uncover text. Deletes up but not including "text" b Break line at cursor j Join lines # Place cursor at start of line Secondary files: %s filename Split window and put a second (read-only) file in top window ^ Set marker for copying text $ Switch between secondary and main file. Text between "^" marker and cursor will be copied across to first file. "Video mode" commands Switches between... COMMAND mode (ECCE takes keyboard input as commands) REPLACE mode (Anything typed will overwrite what's there) INSERT mode (Anything typed will be inserted) The next two commands emulate the video mode commands but stop at or a cursor movement. i Insert. Takes typed input from keyboard o Replace. Overwrites text with text from keyboard. \end{verbatim}\rm \normalsize \vspace{.75in} view:ecce printed on 16/02/89 at 20.32 \newpage \tableofcontents \end{document}