!TITLE CALLING THE EDITOR
       These examples assume that the EMAS option NOBRACKETS is
       selected.

   (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)
!PAGE
   (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

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
               VECCE CURTEXT-NOMATCH-PRE=WPCOMMANDS

!<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:
!PAGE
    (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).
!>
!<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.
!>
!<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").
!>
!>