
        A quick guide to G.Toal's ECCE-in-C for existing ECCE users.

Invocation:
   ecce {-from} infile {{-to} outfile}? {-log file}? {-size bytes}?

   Keywords are optional if the parameters are given in the order above.
   If you omit a parameter, you should give the next keyword explicitly.

         -from infile    This is a mandatory parameter, which is the file
                         you want to edit.  If you are creating a new
                         file, use:
                              ecce -from NULL: -to file.new
                         Unfortunately, not all operating systems support
                         named null files, so you may have to create an
                         empty file once which you can use in future, eg
                         on MSDOS you would create a file \NULL with nothing
                        in it, and then ecce -from \NULL -to file.new

         -to outfile     This is an optional parameter, which is the file
                         where you want the output to go.  Normally this
                         is not given and defaults to the input file.

         -log logfile    This is an optional parameter, and is a file where
                         a log of keystrokes is writen.  It can sometimes
                         be used to recreate an edit (by feeding into a
                         shell or command processor) if your machine crashes.

         -size bytes     This is an optional parameter telling the system
                         how much space ecce has available for the file
                         you want to edit.  It has a semi-sensible default
                         depending on which operating system ecce is running;
                         on MSDOS it is 128K, on the Archimedes it is 2Mb.
                            If you use secondary input or multiple contexts,
                         the size of the largest context and the edited file
                         together be less that this number.

Syntax:
   <+/->  This means that the command (eg M) can take a - which reverses
          in some way the normal sense of the command; ie M normally moves
          forwards so M- will move backwards.
             This version of ecce copies Richard Marshall's RED by making
          as many commands as possible accept -.  Occasionally the resulting
          command may be a little obscure, such as P- and G- (print and move
          up, get and move back!) but the consistency of commands makes the
          editor easier to learn and remember. (You can also explicitly
          give a + to these commands - it has no special effect.)

   <text> Commands which insert or search for text specify their text strings
          by enclosing them in valid string delimiters.

          The only delimiters guaranteed to be available are:
                 "         '     .     /      :      =          _
          (double quote, quote, dot, slash, colon, equals, underline)

  <range> Text location commands can have their searches limited to a
          specified number of lines, eg f/fred/ would normally search
          up to the end of the file -- but f4/fred/ would limit the
          search to the next four lines.  Note that the 'dangerous'
          commands U and D (which combine text searching with deletion)
          have a default range of one line; ranges are otherwise up to
          the end of the file.

<context number> Secondary input in this version of ecce is implemented
          by having a number of external 'contexts'.  Typically, you
          would put extract a section of text by using the Note and
          Abstract commands, eg N m10 A  would move a ten line piece of
          text into the main external context.  It could later be
          reinserted somewhere else in the file by the Here command, eg m0 H
             The <context number> comes into play if you want to keep
          more that one section of text:  you can number each context
          with a single digit identifier in the range 0 to 9 (if you
          don't mention a number, 0 is used), so our example above could
          be replaced by    M m10 A1  m0 H1

 <repeat> A simple command like M only does its action once, ie it moves
          down one line.  To make this more useful, you can put a repeat
          count after the command, so that M10 will move down ten lines.
             This repeat count is a general facility which can be applied
          to most commands, for instance f/fred/3 will find the third
          occurance of fred.
             There are two special repeat counts: '0' means 'lots', and
          '!' means 'even more lots'.  '!' was implemented to keep really
          old ecce purists happy -- but its use is to be deprecated: stick
          to '0' (or its historic equivalent '*') instead.

Commands:

   A<context number>                Abstract noted region to context
   B<+/-><repeat>                   Break lines (insert newline)
   C<+/-><repeat>                   Case flip (or case lock)
   D<+/-><range><text><repeat>      Delete the next occurance of text
   E<+/-><repeat>                   Erase characters
   F<+/-><range><text><repeat>      Find text
   G<+/-><repeat>                   Get lines (G- puts them in backwards!)
   H<context number>                Here (is where to insert the context)
   I<+/-><text><repeat>             Insert text
   J<+/-><repeat>                   Join lines
   K<+/-><repeat>                   Kill lines
   L<+/-><repeat>                   Left move
   M<+/-><repeat>                   Move down a line
   N                                Note this position for later Abstraction
   O  Not implemented.                Oh dear! This doesn't do anything?
   P<+/-><repeat>                   Print (and move)
   Q  Not implemented.                Quite what should this do too?
   R<+/-><repeat>                   Right move
   S<+/-><text>                     Substitute text
   T<+/-><range><text><repeat>      Traverse text
   U<+/-><range><text><repeat>      Uncover (by deleteing Up to) text
   V<+/-><text>                     Verify that the text is here
   W  Not implemented.                 Wait for this - it's reserved.
   X  Not implemented.
   Y  Not implemented.     These are reserved for macros (not yet implemented).
   Z  Not implemented.

Grouping:

   ( <command sequence> ) <repeat>      This repeats a group of commands.
                                        The description of how repeat counts
                                        affect a single command applies
                                        equally to a bracketed group.

   For historical reasons, { }, < > and [ ] also serve as brackets.
   These should not be used as their meanings may change in the future.

Conditionals:

   <command sequence>, <alternative 1>, <alternative 2>
   !                   !                ! And if both fail, try this
   !                   ! If it fails, try this next
   ! Try this one first

   <command>\                    \ makes the command appear to fail if
                                 it really succeeded, and appear to succeed
                                 if it really failed.

   <command>?                    ? says the command succeeded regardless of
                                 whether it did or not.

Special commands:
                                 Commands starting with % are special and
                                 cannot be grouped with other commands.
%L
                                 Searched text is translated to lower case,
                                 The case flip command (C) is modifed so that
                                 any text flipped is locked into lower case
                                 regardless of what it originally was.
%U
                                 Searched text is translated to UPPER case,
                                 The case flip command (C) is modifed so that
                                 any text flipped is locked into UPPER case
                                 regardless of what it originally was.
%N
                                 Searched text is translated to Neither case,
                                 ie left as Normal. (case sensitive)
                                 Case flipping is normal.
%E
                                 Searched text is found in either case,
                                 ie case insensitive.
                                 Case flipping is normal.
%V
                                 Prints the current version number of ECCE
                                 and date last edited.  Please quote this
                                 if reporting any bugs.
%W
                                 This Writes out the file (but doesn't close
                                 the edit). Useful on micros (or mainframes!)
                                 prone to crashing. (A side effect of %W is
                                 that if you are in a secondary context, you
                                 will be switched to the main context)
%C
                                 This Closes the edit, writing out the main
                                 edit buffer to the output file.
%A
                                 Abandon the edit without writing out files.
%S<context number>
                                 Secondary input:  there are two versions of
                                 the %S command: the simple one (with an
                                 optional context number) which switches to
                                 that context.  (If you are in a context
                                 already, a plain %S will switch you back to
                                 the main edit buffer)
                                    And...
%S<context number>=file          This version lets you look at another file
                                 while editing the main one.  You can make
                                 changes in this second (or third, fourth,...)
                                 buffer, but they will not be written back to
                                 the file.


----------

Implementation notes:
1) Secondary contexts are stored on disc under the names Note<n> where <n>
   is a context number.  This has a useful side-effect that contexts stay
   around between edits.  If the name of the file is chosen carefully (eg
   T#NOTE0 on emas) the file could be automatically deleted on log off or
   otherwise semi-regularly (e.g. by a unix daemon).

2) 8-bit data are not specifically supported yet, either as data in a file
   or as commands to ecce.  It is possible that on some machines they
   work all right as ecce stands, but this is just luck.

3) Some machines (MSDOS and probably VMS if anyone tries it) make a
   distinction in the C library between files open in "r" mode (normal
   text) and "rb" mode (binary files).  In unix-like systems (and EMAS)
   it makes sense to open files as binary because their newline character
   is sensibly the ASCII NL (10).  On others it does not, so MSDOS users
   are forced into text mode whether they want it or not.  They just have
   to hope that the text mode filtering does not upset too much else
   within their files.

Future plans:
1) Change the command-line interface so that new files can be created if
   they don't exist already.

2) Work out how much memory is spare at run time and use that unless
   the user overrides it (rather than the current fixed-size default).

3) Implement %X %Y %Z macros

4) Allow the syntax f<13> so that non-printing characters can be searched
   for.  This is going to be a bodge for single characters - it is not
   worth the effort in writing a complete meta-character string parser.

5) Have a % command to allow newlines in search/delete strings.  I have
   experimented with various non-standard ecce features (such as NOT moving
   the cursor if a search fails); I decided that useful as they may be,
   they still cause too much confusion to users ingrained with years of
   traditional ecce practise (unless you have to ask for them explicitly.)

6) The PANOS version uses lots of machine-dependent stuff for interrupts.
   Once PANOS is officially dead (am I the only user?) all this code can
   be removed.

7) The #ifdef stuff is VERY messy.  This needs rationalisation.  It would
   help if I could get a list of the #defines made automatically by each
   compiler on each machine on which it has been compiled.

8) Some ecces have a o/text/ command analogous to i/text/, which overwrites
   text, extending the line if need be.  I may add it IF anyone asks for
   it.

9) Some day (!!!) I would really like to hook my version of ecce into a
   good screen edit, as an 'ecce button' which invoked ecce recursively
   within the screen editors main editing loop (assumed, like emacs, to
   be in a lisp-like language).  The ecce command as invoked could then
   issue an I (insert) or O (overtype) command -- WITHOUT a text string
   argument -- which would in turn recursively invoke the screen editor!
      This would allow you to program complex ecce commands (such as
   repeated finds using say a V/.../ macro) but make the changes at the
   located text by hand on the screen.
      Don't sit up waiting for this, though...
