E       C      C      E
                      EEE     C      C      EEE
                      E       C      C      E
                      EEEEEEE CCCCCC CCCCCC EEEEEE .
          This is a quick guide to the early versions of ECCE, such as those
          implemented on the PDP8 and on the PDP9 around 1970.
          The PDP8 version ran completely stand-alone (no operating
          system required) and edited from a paper tape reader on input
          to a paper tape punch on output, using a dumb teletype for
          console I/O.  All the peripheral driving was done within the
          editor itself.
          An earlier version, written in the high-level Imp language,
          which was a derivative of Atlas Autocode, ran on PDP9/15 systems
          which added disk I/O, and later versions of Ecce written in
          a wide array of languages have been ported to almost all
          known computer systems, and are still in daily use by
          Edinburgh University graduates world-wide!
          This document gives a introduction to the ECCE command structure
          but does not attempt to replace the full manual which you can
          find in the Edinburgh Computer History archives.
          There is also a Unix man page available.
     B<repeat>                        Break lines (insert newline)
     D<range><text><repeat>           Delete the next occurance of text
     E<+/-><repeat>                   Erase characters
     F<range><text><repeat>           Find text
     G<repeat>                        Get lines
     I<text><repeat>                  Insert text
     J<repeat>                        Join lines
     K<repeat>                        Kill lines
     L<repeat>                        Left move
     M<+/-><repeat>                   Move down a line
     P<repeat>                        Print (and move)
     R<repeat>                        Right move
     S<text>                          Substitute text
     T<range><text><repeat>           Traverse text
     U<range><text><repeat>           Uncover (by deleting Up to) text
     V<text>                          Verify that the text is here
     <+/->  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.
     <text> Commands which insert or search for text specify their text strings
            by enclosing them in valid string delimiters.
            The delimiters available are:
            ! . # $ % & ' + / < = > @ [ ] ~
    <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.
   <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.
               The special repeat count of "*" means 'lots'. It can also
            be entered as "0" to save the use of the shift key :-)
     ( <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.
     <command sequence>, <alternative 1>, <alternative 2>
     !                   !                ! And if both fail, try this
     !                   ! If it fails, try this next
     ! Try this one first
     You are not limited to three tests - you can have as many comma units
     as you can sensibly make use of.
     <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.
                                   This Closes the edit, writing out the main
                                   edit buffer to the output file, or in the
                                   case of the PDP8, punching out the remaining
                                   part of the file before exiting.
  The following three commands had to do with the limited window of the
  file which could be held in store, and the tedious business of re-punching.
  %H                               Hold
    %H (Hold) created a pseudo end-of-file condition on the portion of the file
    which was then in store, preventing eg Find operations from causing further
    reading which would generally provoke punching some text from the top of
    the buffer.
  %R                               Release
    %R (Release) removed the end-of-file condition, allowing further input.
  %P                               Punch
    %P (Punch) allowed explicit control of output when finished editing a
    section of the file, i.e. you could force the text before the current
    point in the buffer to be punched, thus creating more buffer space to
    edit text further down the file.
  NOTE:  with the exception of the three commands above, the description
  of Ecce in this document also exactly matches the implementation of
  Ecce (written in Imp) for the PDP9/15 systems, and indeed the version
  implemented in Javascript at the head of this web page.  For comparison
  purposes, the original Imp version can be seen here:
  and a literal C translation of the above - which you can compile and run
  today - can be found here:
  This Javascript version of ECCE is almost completely compatible with the
  above, except that it cannot load files from or save files to disk.  It
  is actually a machine translation of yet another version of ECCE, this
  time one written in a simple language called LC.
  The LC version was used recently as an example sample program for a
  compiler class.
  A more modern C reimplementation suitable for use on Unix or DOS/Windows
  systems is available at SourceForge.  The modern version extends ECCE slightly,
  for example by allowing commands such as F-/text/ to search backwards
  in a file.  It also supports multiple buffers (known as 'contexts')
  and does not suffer the size limitations of older versions.  It is this
  version we recommend if you wish to use ECCE on a day to day basis.
  There is also a derivative of the modern C version which integrates with
  the EMACS editor, allowing you to enter complex programmed commands within
  EMACS by typing ^E followed by the ecce command.  This is an ideal editing
  environment, which uses a screen editor for things at which screen editors
  excel, and ECCE for things which screen editors handle poorly.
     It is quite easy to learn how to use ECCE - half a dozen commands can get
  you started, and the rest can be learned as you go along.  Lets look at some
                 p               Print the current line
                 m               Move down a line
                 g               Get a new line
                 k               Kill the current line
  'Move' is obvious...
  'Get' gives you a ':' prompt, and you type a line of text at it.
  When you press return, that line is inserted in your file.
  'Kill' deletes the entire current line.
  Two more concepts are needed and you will be able to edit any file with these
  commands:  firstly, if you put a number after a command, the command will be
  executed that number of times, e.g.
                   p23            Print the next 23 lines
                   m10            Move down ten lines
                   g5             Make space for and accept 5 new lines of text
  Secondly, the two commands which can be done in reverse (Move and Erase)
  will do so if invoked with a '-', as in:
                    m-10           Move back up 10 lines
     These are the simplest commands of ECCE, and lets you get started editing a
  file.  Here are a few others which are self-explanatory and the sort of thing
  you will be used to in any modern command-line editor.
                   i/text/         Insert a text string here in the line.
                   f/text/         Find the quoted text.
                   r               Move Right one character on the current line
                   l               ditto Left
                   e               Erase one character on this line
  Similarly, all these can take repeat counts where appropriate:
                   f/text/4        Find the 4th occurance of "text"
                   r40             Move Right 40 characters
  And can be strung together quite happily:
                   m23 f/text/ p3
    Where ECCE comes in to its own is in its more advanced features:
                     Failures, Conditionals, and Repeat groups.
     Any of the commands above can fail - for instance, if you try to print 25
  lines, and you are only ten lines from the end of the file, then the print
  command will fail with an error after those ten lines have been printed.
     The smart bit about ECCE is that it allows you to test for such a failure,
  and if one has happened, lets you do something else instead.  The epitome of
  this condition testing is the Verify command:
                     v/text/       Verify that the quoted text is at the
                                   current point in the line.
  This command does nothing at all if the text is present, and does nothing but
  issue a failure message if it is not!
     However, rather than print a failure message and abandon the command, we
  can test whether the command worked and do something else instead.
                      v/text 1/ i/First text: /, i/Not first text: /
     Finally the above can be executed multiple times by enclosing any
  command in brackets, such as:
                     r0   (l  v/ / e)*
  which will remove all trailing spaces from a line, and
                    m-* (r0  (l v/ /e)* m, m)*
  will remove all trailing spaces from all lines in the file.
  Experienced ECCE users will have a repertoire of these combined sequences
  which they can routinely use to perform complex edits.  For instance the
  following will align all "//" comments in a C++ file to column 50:
                      (f.//. l50m, l0f1.//. i/ /50l0r50(v/ /e)0 m, m)0
  Once you get to the stage that you understand the line above on first
  reading, you can award yourself an Ecce Certificate of Merit, and
  I have nothing more I can teach you!
  Ecce was written by Hamish Dewar
  This document was written by Graham Toal