IE is a screen editor for Visual 200 terminals.

It is supported by Richard M. Marshall RMM, room 2607.

!<Introduction

   IE is a very simple to use editor, when sticking  to  the
straight  forward  commands.   To  start  with  all the user
really needs to know is that typing inserts  text  into  the
file, RETURN and DEL do what they do outside the editor, the
arrow keys move around, and that CPY closes the edit.

   Other   useful  basic  commands  to  get  to  grips  with
initially are HOME to move to the top of the file, and EF to
move to the foot of the file.   After  that  DL  for  delete
line,  IL  for  insert  line,  ST for search text and DC for
delete character.

   Given this basic set of commands you should  be  able  to
edit happily for a while, but will begin to find this rather
restrictive  and  difficult  to  use.   At  this  point  you
probably want to use the help facility and explore what some
of the other keys do as well.
!>
!< Buffers

   Text is stored in buffers, a buffer is  IE's  view  of  a
file  in  fact.   Normally only one buffer will be used at a
time.   This is the one that is loaded from the file on  the
command  line,  and  which  is written back when the edit is
closed.  This buffer is called MAIN.  It is possible however
to load an indefinite number of named buffers in, until  you
run out of virtual memory that is.

   Using  the  F11  key, a buffer can be loaded from a file,
and given a name; when the  buffer  is  loaded,  it  can  be
edited entirely independently of the MAIN buffer.  To return
to  MAIN,  or  any  other  buffer you have, use the F10 key.
This presents a list of what buffers are available.

   When the edit is closed with CPY, only  MAIN  is  written
out,  so  the  F12  key  is provided to output a buffer to a
file, and then continue editing it.

   If you want to  place  the  contents  of  a  buffer  into
another  buffer,  the  F13  key  provides  such  an  include
facility.   The contents of a named buffer are  copied  into
the current buffer, below the current line.

   To  copy  text about the place use Copy Position (CP) and
Delete And Copy (Convert DC).
!>
!<Macros

   It is possible in IE to define  ANY  control  key  except
ESC,  DEL  and  RETURN  to  be  a  string  of  characters or
commands.

   To define a key, press the ENTER  key,  followed  by  the
control character that you wish to define.   Then the letter
of the control character appears followed by  a  colon,  and
the user can type in what ever text or commands he likes see
the help information on ENTER for further details.
!>
!<Markers

   To  provide  some fast means of jumping around in a file.
A marker may be attached to any position in  the  file;  and
the name given for it can be used to jump to that position.

      F8 is used to set a marker.
      F9 is used to jump to a marker.

   See the help information on F8 and F9 for more details.

   Each buffer has an independent set of markers.
!>
!<Command Line

   The command line conforms with the APM PAM conventions.

      } IE <input>/<output>

   If  an output file is omitted, output will be to the same
as the input.

   To create a file, just give the file name and it will  be
created.

   If no file name is given, then the memory is examined.
!<-SILENT

   This suppresses the printing of messages such as "Reading
from FRED".  This is useful in command files.
!>
!<-MEMORY

   This  remembers what was last edited, so as to be able to
edit it again without having to give the file name.
!>
!<-PROFILE

A Profile file may be nominated by using the command option -Profile=<file> or
if a file called PROFILE.IE exists in the current directory this is used in its
place
!>
!<-READ
   No file is written on output.
!>
!<-LAST

   This edits the last file that was edited again.
!>
!<-CREATE

   This ignores any existing version of the input  file  and
creates a new one.
!>
!<-SAVE_POSITION

   This is used in conjunction with the memory  file.   When
an  edit  with -MEMORY is specified, or when no file name is
given and there is a memory file, the last  cursor  position
is  stored  if this option is given.   When the next edit of
the memory file is started, the initial cursor  position  is
that at the end of the last edit.

   The  qualifier  -TOP  suppresses the use of this position
memory.
!>
!<-TOP

   See -SAVE_POSITION.
!>
!>
!<Control Keys

!<DEL

   This deletes the character to the left of the cursor.  If
at the beginning of the line, however, the current  line  is
joined  onto the end of the line before unless the two lines
would be too long for the buffer.

   Note that if in CoverText mode, then the character to the
left of the cursor is overwritten  with  a  space,  and  the
length of the line stays the same.

   BS is a synonym for this
!>
!<RETURN

   This  breaks  the  current line into two - that is take a
new line.   The new line is auto indented, if that option is
enabled, to the same depth as the line before.
!>
!<LF

   The key is used to jump to a particular line of the file.
The prompt

   Line:

   will  appear  at  the top of the window.   If an unsigned
number is typed, then it is taken as an absolute line number
to jump to.   It can be signed with a + or a - to mean  move
on  so  many lines from the current line, or go back so many
lines from the current line.
!>
!<^@

   This is like LF except that it works for columns.
!>
!<^B

   This is a bracket matching command - if ^B is pressed  on
a  (,  the cursor is jumped onto the next MATCHING ).   This
also works backwards for ) jumping to the matching  (.   The
matches are as follows:
   (    )
   )    (   backwards
   [    ]
   ]    [   backwards
   {    }
   }    {   backwards
   <    >
   >    <   backwards
   "    "   forwards only
   '    '       "      "
   `    `       "      "
   %    %       "      "
   If  the  current character is NOT a valid bracket the BEL
is sounded.   If no matching bracket is found, a message  is
displayed on the top line of the screen.
!>
!<TAB

   The TAB key moves the cursor to the next TAB column.  The
width  of  these  columns  is set to be 3 by default but the
profile file can change this with  the  Width  command.   In
Insert Character mode, spaces are inserted until the current
position  is  on  a  column.   In Cover Text mode the cursor
simply moves up the column end.   In both modes the line  is
extended if the cursor moves off the end of the line.
!>
!<^C

   This Clears the broadcast window.
!>
!<^G

   This command is the same as F11 - Get buffer.
!>
!<^O

   This is the same as F12 - Output Buffer
!>
!<^P

   This  allows  the  user  to add control characters to the
file.    Control-P  followed  by  any  character  adds  that
character to the text without interpretation.
!>
!<^R

   This refreshes the screen, making no changes.
!>
!<^S

   This command is the same as F10 - select buffer
!>
!<^W

   This function deletes the current word.   The best way of
describing what form a word is defined to take is to try it!
!>
!<^X

   This, as normal, deletes back to the start of the line.
!>
!<^Y

   This aborts (cleanly) the edit.  N.B. you cannot continue
from this.

   Normally confirmation is  sought,  although  the  command
line option -NoConfirm switches this safety net off.
!>
!>
!<Function Keys

!<F0

   Word left.
!>
!<F1

   Word Right.
!>
!<F2

   Up to start of the line above.
!>
!<F3

   Down to start of the next line.
!>
!<F4

   Convert  the character under the cursor to lower case and
move right.
!>
!<F5

   Convert the character under the cursor to upper case  and
move right.
!>
!<F6

   Convert  the  character  under the cursor to the opposite
case and move right.
!>
!<F7

   Swap the two characters to the left of the cursor around.
!>
!<F8

   Set Marker:

   Pressing this key results in the prompt

      Set Marker:

appearing at the top of the window.  A text string should be
typed in response to  this.   This  name  is  then  used  to
identify  the  current  position in the file, and the F9 key
can be used to jump back to it.
!>
!<F9
   Jump to Marker.

   Pressing this key  results  in  a  list  of  the  markers
defined  with  the  F8 key, along with part of the line that
they mark being displayed, and the prompt:

   Jump to Marker:

   appearing at the top of the window.  A marker name should
be typed here, and you will be jumped to  exactly  the  same
place  where  the  marker  was set.   When the line with the
marker on it is deleted the marker disappears.
!>
!<F10

   This key is used to select which buffer to edit.

   A list of the names of the available buffers  is  printed
along  with the file names that they were loaded from.   The
prompt

            Buffer:  

then appears.   In response to this type  the  name  of  the
desired buffer.

   For terminals that do not have function keys, ^S performs
the same function.
!>
!<F11
   Get Buffer: This key loads a buffer from a file.

   First  a  buffer  name is prompted for, then a file name.
The file is loaded into a new buffer, and then  that  buffer
is selected.

   For terminals that do not have function keys, ^G performs
the same function.
!>
!<F12

   Output Buffer: This key outputs the current buffer into a
file.

   The  prompt  File  name for output: appears, and then the
file name should be given.  If the file does not exist, then
the prompt reappears.

   For terminals that do not have function keys, ^O performs
the same function.
!>
!<F13

   This includes another buffer in the current buffer.

   A buffer name is prompted for, and then  that  buffer  is
inserted below the current line.   The cursor is left on the
last line of the insertion.
!>
!>
!<Top Right Keys

!<Left arrow

   This moves the cursor one place to the  left,  unless  at
the start of the line where it does not move.
!>
!<Right arrow

   This  key moves the cursor one place to the right, unless
at the end of the line, where it does not  move  unless  the
FreeCursor option has been enabled.
!>
!<Up arrow

   This   key   moves   the  cursor  onto  the  line  above,
maintaining the column, unless at the top of the file.

   Note that there is a "buffer line"  at  the  top  of  the
window into which you normally do not move, rather that line
moves down to you, unless at the top of the file.
!>
!<Down arrow

   This key moves the cursor onto the line below the current
one, unless at the end of the file.

   Note  that  there  is  a buffer line, as described for Up
arrow.
!>
!<HOME

   This moves to the first line of the file.
!>
!<CL

   This is the CloneLine function, which duplicates the last
deleted line, and inserts it above the current line,  moving
the cursor onto it.

   N.B.  This is Convert HOME.
!>
!<CP

   This is CopyPosition.

   This  marks  a point in a buffer, for use with the Delete
and Copy function, which is Convert DC.

   When Convert DC is pressed, the line that the  cursor  is
currently  on  is  moved  to  above the line marked with CP.
This allows blocks of text to be moved around the file.

   To replicate a block of text,  create  an  empty  buffer,
using LoadBuffer (F11) from NL: (the null device).   Now use
CP to mark the buffer, and return to the source buffer.  Use
Convert DC to feed the block of text from the source  buffer
into the new buffer.  Now IncludeBuffer (F13) can be used to
copy the text as many times as is required.

   N.B.  This is Convert Down arrow.
!>
!>
!<Keypad

   This  area  of  keys at the right of the keyboard provide
the basic functions of the editor.   The names are  designed
to be as meaningful as possible, but a willing suspension of
disbelief may be needed at times.

!<IL

   This is the InsertLine function.  It inserts a blank line
above  the  current  line and moves the cursor onto it.   If
AutoIndent is enabled, then the line is automatically filled
with spaces to the same depth as the current line.
!>
!<Convert-IL

   Unused.

!>
!<IC

   This key sets the editor into InsertCharacter  mode.   In
this  mode,  ordinary  text  typed  on  the main keyboard is
inserted into the file and characters to the  right  of  the
current position are shunted along.
!>
!<Convert-IC

   This  key  puts  IE into OverWrite mode.   In this state,
text typed over writes, covers up, the text  already  there.
This  is  useful for writing over runs of spaces, such as to
the left of comments, but is not very useful normally.  This
is the opposite of InsertCharacter mode.
!>
!<ST

   SearchText

   This is IE's find command.

   When ST is pressed the prompt

         Search:

appears on the top line of the window.   To this text can be
typed,  terminated  by  RETURN.   This  is  followed  by the
message Searching.. to appear on the top line,  and  another
dot appears for every 128th line searched.
   Control  P can be used to put control characters into the
search text.
!>
!<Convert-ST

   This repeats the last search operation.
!>
!<DL

   Delete Line.

   This key deletes the current line.   Never fear,  Convert
DL can bring it back again.
!>
!<Convert-DL

   UnDelete Line, or Restore Line.

   This  command  rescues deleted lines.   All deleted lines
can be recovered, and this provides a  convenient  means  of
moving  lines around in the file.   Note the function of the
CL key differs from the Convert DL, as Convert DL will  only
recover  a  line once, and then the line deleted before that
will be recovered.
!>
!<DC

   DeleteCharacter.

   This deletes the character under the cursor.
!>
!<Convert-DC

   Delete and Copy

   This is used in conjunction with the CP key.

   See the information on CP for further details.

!>
!<CT

   ChangeText.

   This is a find/substitute command.   When CT  is  pressed
the prompt

   Change:

   appears  on the top line of the screen, and a search text
should be provided.   When RETURN has terminated that  text,
the prompt

   To:

   appears.   To this type the text that the next occurrence
of the first text should be changed to.   If this definition
does  not  suit you, then it is possible through the SetMode
facility and the UserProfile to stop the search part of  the
command,  and  only do the substitute part.   This should be
used in conjunction with the ST command.
!>
!<Convert-CT

   This repeats the last ChangeText.
!>
!<EL

   End of Line.

   This command moves the cursor to the end of  the  current
line.

!>
!<Convert-EL

   Erase to end of Line.

   This  deletes  all text following and under the cursor on
the current line.
!>
!<EF

   End of File

   This moves to the end of the file.
!>
!<Convert-EF

   Erase to end of File

   This command deletes all the following lines of the file,
after asking for confirmation.
!>
!<EP

   End of Page

   This moves the cursor to the end of the last line of  the
page, scrolling another line on the bottom if possible.

   This  is  useful  in conjunction with Convert PRT to page
through the file.
!>
!<Convert-EP

   Start of the page (Reverse of EP).

   This moves the cursor to the  top  line  of  the  screen,
scrolling on another line at the top if possible.

   This  is  useful  in conjunction with Convert PRT to page
back up through the file.
!>
!<0

   Move to Start of Line.

   Moves to column 0 of the screen.
!>
!<CPY

   Copy Out

   This closes the edit, writing out the buffer MAIN to  the
file name specified on the command line.
!>
!<Convert-CPY

   Abort the edit, do not write any buffer out.
!>
!<PRT

   RePrint  the page, using the current line as the top line
of the new page.

   This can be used with EP to step through the file page at
a time.
!>
!<Convert-PRT

   Scroll back screen (No significance in the name).

   This redraws the screen with  the  current  line  as  the
bottom of the screen.  This command is useful in conjunction
with  Convert  EP to step page at a time backwards through a
file.
!>
!<-

   Interact Mode

   This presents a menu of functions, which can be  selected
by the first letter of the name of the option.
!<Help

   This  displays  one page of information about the keypad,
function keys etc.
!>
!<Profile

   This prompts for a file name,  and  this  is  used  as  a
profile file, as in the normal startup profile.
!>
!<Set Modes

   This  allows  the  user  to  set  the  various  IE  modes
interactively. This enables the following options to be set:

                              Show TAB
                           Auto Indent
                       Auto Line Break
                      Case Sensitivity
                 Search before Replace
                           Free Cursor
                            Write Back
                                  Tick
                             Beep Mute
                             TAB Width
                           Beep Column
                          Maximum Line

   The up and down cursor keys can be used to  move  between
entries,  wrapping  round at the top and bottom of the list.
When on an option pressing D (or d) resets the  option  back
to  the  default, Y sets it to Yes and N sets it to No if it
is a Yes/No option.   Typing a digit allows you  type  in  a
number,  using  DEL and ^X if needed.   If a silly number is
typed, the value is set to the default again.
!>
!<Files

   This prompts

      File spec:

   This the command acts like the Files program, listing the
files in the current directory.   Any file spec can be given
after  the prompt and the files will be listed page at time.
Pressing RETURN in response to the command is equivalent  to
the  file  spec  []*.*;*,  that  being  all the files in the
current directory.

   The list of files is paged to fit on the current  window,
and when the end of a page is reached the prompt:

   RETURN to continue, ^Y to abort, F for new file spec

   will  appear.   This  will  also happen at the end of the
directory, or at the end of each directory in  the  case  of
wild  card  directories.    Control  Y  returns  control  to
Interact Mode, and F prompts for a new file spec.
!>
!>
!<ENTER

   This key can be used to define control keys to be text or
command strings.

   When ENTER is pressed, the prompt

      Press key to be defined:

   appears on the top line of the window.   In  response  to
this type a control character.  Any character other than ESC
and RETURN can be defined.

   After  pressing the desired character, type the text that
you wish the key to represent.   Commands may  be  typed  as
well, although they are not very sensibly echoed at present.
Terminate  with  RETURN,  and  use  Control P to add strange
control characters, such as RETURN to the text.

   If you wish to remove  a  definition,  ENTER  <character>
RETURN does this.
!>
!>
!<User Profile

   The user profile file automaticily sets up the IE options
and macros every time the editor is used.

   The general form of statements is:

       Name = Y

         or                      and               Name = number

       Name = N

   Spaces  may  be  freely  inserted  into  the names of the
options if wanted.
!<AutoIndent

   When this mode  is  set  the  Insert  Line  and  CR  line
insertion  actions  result  in the same level of indentation
(number of spaces) being put at the front of the new line as
were on the old line.

   Form:

      AutoIndent = Y

By default AutoIndent is on.
!>
!<AutoLineBreak
   An  option  is   available   where   lines   are   broken
automatically  as  they are typed in.   The line break is at
the start of the last word on the line.

   Form:

      AutoLineBreak = Y

By default AutoLineBreak is off.
!>
!<ShowTAB
   When the source file contains TAB  characters  these  can
often be very confusing.   If the ShowTAB option is enabled,
then the space on the screen covered by TABs is  filed  with
the graphics dot-dot character.

   Form:

      ShowTAB = N

   By default ShowTAB is off.
!>
!<TABWidth

   On  input,  the  TAB  key jumps to the end of a column of
user  definable  width.    This  is  normally  3   for   Imp
programming,  but use of the TABWidth option in your profile
file can change it:

   TABWidth = 8

!>
!<Free cursor
   If this is switched on, the cursor  is  allowed  to  move
outside the text, this is very useful for drawing tables and
boxes.  It is OFF by default.

   Free cursor = Yes to switch it on.

!>
!<SearchBeforeReplace
   Normally,  when  you  use  the ChangeText key, the prompt
Change: appears which is for a piece of text to  search  for
before  substituting.   If  SearchBeforeReplace is set to No
with this option, then the To: text is  substituted  at  the
current  cursor  position - normally where you last searched
to.

   SearchBeforeReplace = N

   By default this is On
!>
!<Write Back
   If buffers other than MAIN have been changed and this option
is YES then the user is asked if it is desired for the buffers
to be written back.  If the response to the question is Y then
a prompt appears for the file name to write to, pressing RETURN
in response to this causes the file to be written ack to the
source file.  If the file was created then the prompt will
perist until a file name is given.
!> 
!<Beep Mute
   This is an option for people with sensitive ears.
!>
!<Tick
   This is for insatiable clock watchers on VAX - but not on the APMs yet.
!>
!<Comments

   Just to show what a  non-hacker  you  are,  you  can  add
comments  into  your  profile  -  introduced  by  ! or { and
terminated by the end of line.
!>
!<Window size

   The commands

      WindowTop = <number>
      WindowBottom = <number>

specify the top and bottom lines of the window on the screen
to use.   These should be in the range 0  to  23,  with  Top
smaller than Bottom.  The defaults are

      WindowTop    = 0
      WindowBottom = 23

   as this uses all the available screen area.
!>
!<Macros

   To define a control key to be equivalent to some text, or
some commands, the following command can be used:

   ^(LETTER) = (MACRO)

   If  there  is a space after the '=' then that is ignored,
but all other characters after that are significant.

   Example:

      ^A = %constant %integer

         is the same as:

      ^A=%constant %integer

   This is equivalent to the interactive use  of  the  ENTER
key.
!>
!<Example

   Here is an example profile file:

        {Profile for Imp programming}
        Auto Indent = Yes
        Auto Line Break = No
        TAB Width = 3
        Show TAB = Yes
        ^A = %constant %integer
        ^B = %integer %function
        ^C = %record %format

!>
!<Your own profile

   {This is left as an exercise for the reader}

!>
!>
!<Restrictions on the APM
The only restriction is that on a half-megabyte machine the usable file length
is limited to about 1500 lines.  Use the monster machine in the machine halls
if you need a bigger file at the moment.
!>
!<Calling IE from programs
IE is an %external %routine and may be called from other programs that need to
perform editing.   The first call to IE must be preceded by a call of the
%external %routine Set Up Terminal and the last one must be followed by a call
of Reset Terminal.   If your program performs ANY terminal IO between calls of
IE it is essential that you call Reset and then Set Up again or your program
will not work.

It is also possible to get IE to display a message in the Broadcast Window when 
the edit starts up - very useful for displaying error reports when calling IE
from a compiler.

Notice that IE makes use of Imp Input and Output stream 3 - any other file
on this stream will always be lost during an IE edit.

The following declarations are available in IE:IE.INC, and the object files are
preinstalled in the system startup.
!PAGE
%constant %integer abort
      ! If the user aborts his edit or a fatal condition arises IE
      ! %signals abort.
   
%constant %string (15) Version
      ! This is the version code of the editor that you will be using.

%constant %integer Silent
%constant %integer Confirm
%constant %integer Deaf
%constant %integer Reset Heap
   ! These are options for use when calling IE
   !    Silent     - suppresses the printing file loading/writing messages
   !    Confirm    - asks if the user really wants to before Aborting
   !    Deaf       - suppresses any broadcast messages appearing
   !*   Reset Heap - this causes IE to restore its claimed heap space         *
   !*                at the end of an editing session.  When used stand alone *
   !*                it does not bother but any other program using the heap  *
   !*                or likely to call the editor more than once MUST supply  *
   !*                this option.                                             *

!PAGE
%external %routine %spec IE editor %alias "IE_EDITOR" %c
                                   (%string (127) in file, out file,
                                    %integer window top, window bottom,
                                    %integer %name start line, start pos,
                                    %string (127) profile,
                                    %integer options)
   ! This is the editor itself, the parameters aree as follows:
   !    In File       - The source file, creates output if null
   !    Out File      - The output file, read only if null
   !    Window Top    - Top line of the screen to use 0 to 12
   !    Window Bottom - Bottom line of the screen to use
   !    Start Line    - Line of file to start on, returns line at end (starts at
   !                    line 1.
   !    Start Pos     - Column of line to start on, returns position at end
   !                    (starts at 1)
   !    Profile       - Profile file - no profile if null
   !    Options       - Bits set as above

!PAGE
%external %routine %spec set up terminal %alias "IE_SET_UP_TERMINAL"
%external %routine %spec reset terminal %alias "IE_RESET_TERMINAL"
   ! These control the terminal settings, as described above.

!PAGE
%external %routine %spec Receive Broadcast %alias "IE_BROADCAST" %c
                                           (%string (255) Message)
   ! If this is called before IE Editor itself the Message will appear as a
   ! broadcast message at the top of the screen when the edit starts up.
   ! Very useful when integrating the editor into a compiler.