          Documentation for the Ex Editor by Emmet P Gray


BACKGROUND :
  The Unix operating system comes with a crude line editor called 'ed'.
  It is not unlike the 'ED.COM' command in CP/M.  The Berkeley release
  of Unix (version 4.x bsd) contains a much improved version of the
  editor called 'ex' written by Mark Horton.  This program is modeled after
  his, in that it has a subset of his original commands, and that the
  command syntax is similar.  Additional information on the use of 'ex'
  can be obtained from books on Unix.  I recommend "Unix Primer Plus" by
  Waite, Martin, and Prata.

PURPOSE :
  The purpose of this program is to have a 'transportable' editor between
  machines running Unix, CP/M, and TRSDOS.  "I hate to have to learn
  another editor!"

REQUIREMENTS :
  The program is written in BASIC and supports the Radio Shack Model III,
  Radio Shack Model 4, and any CP/M system with MicroSoft's MBASIC-80
  version 5.2x.  The program takes up about 9k of memory.

FEATURES :
  This is a 'line editor' which means commands are made relative to line
  numbers rather than positions on a screen.  Features are : appending
  to an existing file, changing a line(s), deleting a line(s), editing
  an existing file, inserting a line(s), printing all or part of a file,
  inserting/appending from another file, substituting a part of line(s),
  writing all or part of a file to disk.  All commands are entered and
  executed from the editor's prompt ':'.  In addition, most of the commands
  can be performed conditionally (for example, delete all lines
  that contain the string "Page").

COMMANDS :

  APPEND
  The editor uses the computers memory as a text buffer area before
  putting anything on disk.  When you enter the editor, the buffer is
  empty.  To start creating a new file you must APPEND to the buffer.
  This is done by typing the letter 'a' at the editor's prompt ':'.
  The editor will respond with the number '1' indented to the right 5
  spaces.  To create a file, just type as if you were on a typewriter.
  Notice that the editor will prompt you with a new line number after
  you hit <enter> or <carraige return>.  To stop APPENDING, enter a
  period '.' as the first character on a line.  The command prompt ':'
  will reappear.  The APPEND is also used to continue adding lines to
  an existing file.  If a file already exists in the buffer when 'a'
  is pressed, the editor will prompt you with the next line number.
  The editor will prompt you for data only with a line number prompt.

  EDIT
  To make changes to a file that already exist on disk, use the 'e'
  command.  The EDIT command puts the file in the buffer, replacing
  the buffer's previous contents.  To EDIT a file named "report",
  type 'e report'.  The space between the file name and the command
  is required.  The normal way your computer address the different
  drives is also supported (example on a TRS-80, 'e report:1' would
  get the file from the top drive).

  CHANGE
  To make a change to an entire line (or a group of lines), use to 'c'
  command.  The CHANGE command prompts you with a line number that
  already exists, and allows you to enter new data in its place.  To
  CHANGE the data in line 12, enter '12c'.  Upper or lower case is not
  significant, but their must be no space between the line number and
  the command.  To CHANGE all of lines 12, 13, and 14 type '12,14c'.
  The two numbers separated by a comma represent the upper and lower
  range of line numbers affected.  In this case, the editor would
  prompt you with line 12, then line 13, and then line 14.  To 'abort'
  the CHANGE command, enter a '.' at the beginning of a line.

  DELETE
  To remove an entire line (or a group of lines), use the 'd' command.
  To DELETE line 43 type '43d'.  To DELETE lines 1 through 5, type
  '1,5d'.  DELETES are not reversible, and should be used with caution.

  INSERT
  To place a new line in between existing lines, use the 'i' command.
  The INSERT allows for new text lines to be placed anywhere in the
  buffer.  To INSERT a line between lines 105 and 106, type '106i'.
  Notice that the line number specified is the new line 106, the old
  line 106 will be renumbered as 107 (and all other lines greater than 106
  will be renumbered accordingly).  To INSERT more that one line, just
  continue typing lines at the line number prompts, all higher numbered
  lines automatically get renumbered.  To stop INSERTING or to 'abort'
  the command, just enter '.' at a line number prompt.  The INSERT
  command take only one 'argument' (one line number) no matter how many
  lines are being INSERTED.

  PRINT
  To display all or part a file on the screen use the PRINT 'p' command.
  To PRINT lines 50 through 70, type '50,70p'.  You may stop the
  PRINTING at any time by pressing the <enter> or <carraige return> key.
  You can also "step" through a file one line at a time by just pressing
  the <enter> or <carraige return> key at the ':' prompt.  Line numbers
  are shown on the screen, but are not really a part of the file (and
  do not exist in the disk file or in memory).

  QUIT
  To QUIT an editing session and return to BASIC, enter 'q'.  All
  contents of the buffer are lost.  If you have changed your buffer
  contents and neglected to write the file to disk, the editor will
  remind you, and ask that you verify the command.

  WRITE
  The WRITE command places all or part of the buffer contents on disk.
  To WRITE the entire buffer to a new file called "report/txt", just
  enter 'w report/txt' at the command prompt.  Notice the lack of line
  numbers implies that all lines are to be used.  To write only lines 3
  through 10 to the file, enter '3,10w report/txt'.  If the file already
  exists on the disk, the editor will warn you and ask that you verify
  the command to overwrite the old disk file.  To append the contents of
  the buffer to an existing disk file, type the character '>'
  immediately before the file name (no spaces).  For example, if an
  existing file on the disk is called "testfile" and you intend to
  add the contents of the buffer to the disk file, you would enter
  'w >testfile'.  File names (with or without the '>' character) are
  always separated from the command with a space.  Spaces are not allowed
  in any other circumstances.  Just like BASIC's save command, the
  buffer contents are copied to the disk but not removed from memory.

  READ
  The READ command is a cross between the INSERT and EDIT commands.
  It allows you to insert lines into the buffer from an existing disk
  file.  This is useful if you have to insert several identical lines
  into 3 or 4 different places in the buffer.  For example, if you are
  preparing a long list of data in columns, and want to insert column
  headings at the top of each page.  You would first create the headings
  and WRITE the one line to a file (call it "headings").  Then you could
  insert the one line disk file into the buffer at line 35 by typing
  '35r headings'.  Using the READ and WRITE commands, you can easily
  move paragraphs from one place to another in your buffer.  As in
  BASIC, the READ command does not remove the information from
  the disk, it mearly copies it to the buffer.

  SUBSTITUTE
  This command allows you to make changes within a line (or lines)
  without having to retype the entire line.  The SUBSTITUTE command
  searches for a pattern you provide, and if the pattern matches, makes
  changes as you specify.  For example, if you misspelled the word
  "house" in line 5 (you spelled it "hosue" instead), you would
  SUBSTITUTE the "su" in "hosue" for "us".  This is done by entering
  '5s/su/us/'.  The slash '/' character is used to identify the
  pattern to be matched and the pattern to be substituted.  As you
  may have noticed, the first pattern is the one tested for a match,
  and the second one is the one to be changed.  To make changes on
  several lines you would enter '3,55s/su/us/'.  The editor will tell
  you how many substitutions were made (there may not have been a
  match on every line between 3 and 55).  If there is more than one
  match on a line, only the first match is acted upon unless you
  specify a 'g' as the trailing character in the command.  This 'g'
  signifies 'global' searching and will perform the substitutions
  for all matches on a line (rather than just the first match).
  The command would look like this '3,55s/su/us/g'.

  GLOBAL
  This is a very powerful command and is a strong point of this editor.
  It allows you to combine two commands together and to make the completion
  of one command conditional on another.  For example, if you wanted to remove
  any line with a page number in it (to delete the bottom of every page), you
  would enter '1,100g/Page/d'.  The use of the slash '/' is similar to the
  SUBSTITUTE command, but the second parameter, the 'd', is a command (not
  a replacement string).  In this example, any line between 1 and 100 with the
  string "Page" in it will be removed.  All other lines are left intact.  The
  GLOBAL comand can work in conjunction with the following commands : READ,
  SUBSTITUTE, WRITE, CHANGE, DELETE, and PRINT.  Another example of
  GLOBAL command is to use it like a 'find' command.  To find every
  line with the string "Mr. Smith", you would enter '1,122g/Mr. Smith/p'.
  This example does not alter the buffer, it just prints the lines found.

SHORTCUTS :
  There are 2 line abbreviations supported by the editor, these are :
  '$' for the last line in the buffer and '.' for the current line.  They
  can be used in place of line numbers inside the command line.  For
  example, to print an entire file enter '1,$p' or to delete from
  line 8 to the current line number, enter '8,.d'.  There are also 2
  character abbreviations, namely '^' and '$'.  The first character
  represents the beginning character in a line, and the '$' represents the
  last character in a line.  Note : In the Model III version, the '^'
  character is a ']'.  To indent an entire paragragh, you would enter
  '6,17s/^/     /'.  The '^' will always match the first character and
  the 5 spaces will be substituted BEFORE that character.  To append to
  the string "moved to town" at the end of line 17, you would enter
  '17s/$/moved to town/'.  Again, the '$' will always match the last
  character in a line and the string will be subtituted AFTER that
  character.

  Most commands (with the exception of the WRITE command) that accept a line
  number in the command line will assume the value of the current line number
  if the line number is missing.  For instance, the sequence '5p' followed
  by 's/123/345/' will substitute "123" for "345" on line 5, since the
  SUBSTITUTE command assumed the current line number of 5.

  The SUBSTITUTE command has a special character, the backslash '\'.
  It is used to remove the special meaning of the '/' character (which
  is used to separate the search and replace strings).  For example, if you
  wanted to SUBSTITUTE the string "1/2" for "1/3" in line 6, you would enter
  '6s/1\/2/1\/3/'.  The '\' character will not be placed in the buffer, its
  only purpose is to prevent the editor from "confusing" a real '/' from a
  part of the command

  When editing an existing file using the EDIT command, the file name given
  is retained for use in the WRITE command.  For example, after editing
  a file called "file1" with 'e file1', a 'w' alone will perform the same
  as 'w file1'.  The file name is echoed by the editor (with the number
  of lines) in either event.

SHORTFALLS :
  Since the editor dynamically changes line numbers after INSERT or DELETE,
  there is often a minor delay on the return of the command prompt.  Because
  of this, INSERTS or DELETES at the top of large files take more time than
  those performed at the bottom of the file.

  There is no provision in the editor for sending a file to a printer.  Most
  operating systems have utilities that can perform this function.

  The editor is designed to function with ASCII files only.


Questions, comments, and/or reports of bugs are welcome !

	Emmet P Gray
	72176,2445


