5.  The EDITOR

The EDITOR has  a  primary  mode  called  the  COMMAND  mode.   All
commands in the EDITOR start from this mode.  In fact, one can view
it as the only mode, with  the  ADD/INSERT,  EDIT,  and  ASM  modes
simply  being  commands with sub-options.  However, rather than fly
in the face of popular convention, we will refer to these  commands
as  "modes."  The important thing to remember is, where and what we
are doing at a particular instant  in  time,  not  what  some  nit-
picking purist calls our position in space and time.

5.1  Command Mode

For many of the commands in this section, only the first letter  of
the  command  is  required,  the  rest being optional. The required
command characters are shown in upper case and the optional ones in
lower case.

In some commands you must specify either a line number, a range  of
line numbers, or a range list. A line number is just that; a number
that exists as a line number for the data  set  (source  file).   a
range  is  a pair of numbers separated by a comma (14,20).  A range
list   is   a   series   of    ranges    separated    by    slashes
(14,20/26,32/88,99).

Several commands allow the specification of a  string.  The  string
must  be  delimited (set off) by a non-numeric character other than
the slash.  Such a delimited string  is  called  a  "d-string"  The
usual delimiter is either a single or double quote mark (' or ").

For those commands involving a d-string, the character "^"  (carot)
acts  as  a wild card. Therefore, "Jon^s" will match both Jones and
Jonas.

Line numbers in the editor are provided  automatically.  You  NEVER
type them when entering text; only when giving commands.  If a line
number in a range exceeds the  number  of  the  last  line,  it  is
automatically  adjusted  to  the  last line number.  This is a very
helpful attribute for those cases where you wish to modify a  range
from  some point to the end of the data set and you do not know (or
care to know) the last  line  number.  Assuming  the  data  set  is
approximately  200 lines long and you wish to change some string of
text from the 42nd line to the end of the  data  set;  specify  the
range as "42,999."

A final point. The EDITOR automatically replaces spaces in comments
and  ASCII  strings  with inverse spaces. When listing, it converts
them back, so you never see them as  inverse  on  the  screen.  Its
purpose  is  to  avoid  inappropriate tabbing of comments and ASCII
strings when they are listed.  (Arn't you glad we  told  you  about
something  you  have  no  control over and didn't worry about until
this comment? It's nice to spread a little doubt and  gloom  around
to the troops.)

In the case of ASCII strings added to the source via "ASC" commands
(see  the Assembler), the inverse space conversion takes place only
if the delimiter is either the single or double quote (' or "). For
those  cases  where  the  delimiter  can  be neither, the following
procedure may be followed.

Edit the line and replace the first delimiter with a  single  quote
and  Type:<R>.   Re-edit  the line and change the delimiter back to
the desired one.

May we now present the commands? (did I hear modes?)

5.1.1  HImem

HI expression
Where expression is a decimal or qualified ($)  hexidecimal  number
that  specifies the end address +1 of the source, and the beginning
of the object (OBJ).  It must fall in the range of 2305 ($901)  and
38995  ($9853).   See  the  memory  map  that applies to your Apple
system in the Technical notes  section  of  this  manual.   HI(mem)
defaults  to  $8000  and does not need to be set unless you need to
adjust for large source that generates small OBJ.  All in  all,  it
should seldom (never?) need setting.

5.1.2  NEW

Deletes  the  present  source  file,  resets  HIMEM  (MERLIN's  not
Apple's) to $8000 and starts fresh.

5.1.3  PR#(0-7)

Same function as in BASIC. Mainly used for  sending  an  editor  or
assembly  listing listing to a printer.  Do NOT use this command to
select an 80 column card. See the VIDeo command for that function.

5.1.4  USER

USER does a JSR to $3F5 (this is  the  Applesoft  ampersand  vector
location,  which  normally points to an RTS).  The designed purpose
of this command is for the connection of  user  defined  (supplied)
printer  drivers.  This  printer  driver  must  not  use  zero page
addresses except for the I/O pointers  and  locations  $60  through
$6F. Ignoring this rule can (will) cause Merlin grevious trouble as
it is a heavy user of zero page locations.

This Editor command should not be confused with the Assembler "USR"
command which is used for different purposes.

5.1.5  TABS

Allows setting the number of successive  columns  for  tabbing  and
optionally, a tab character. These tabs are for the EDITOR and have
no effect on the assembler listing.  Up to nine tabs are  possible.
An example of the command is:


        TABS 5,10,15,20,25,30,35,40,45,<:>

The above will cause tab stops to be set for columns 5, 10,...   In
addition,  the tab character is set to be the colon (:). This means
that whenever a colon is typed and the cursor is less  than  column
45;  it  will  be  tabbed  to the next greatest tab stop. After the
cursor reaches column 45, a colon will not cause a tab to occur.

Entry of "TABS<R>" will cause all tabs to be set to zero.

If you do not specify a  tab  character,  the  the  last  one  used
remains in effect.

It must be kept in mind that the assembler regards the space as the
only  acceptable  (tab)  character  for  the  separation of labels,
opcodes, and operands. Use of some other character will  cause  the
SDS death song to play when you attempt an assembly.

5.1.6  LENgth

This gives the decimal length (in bytes) of the  source  file,  and
the  number  of  decimal  bytes  remaining  before  MERLIN's  HIMEM
(usually $8000).

The EXEC menu gives the hexadecimal start  address  and  length  of
source.  See the "Where" command for more in this thrilling story.

5.1.7  Where, WO, and O Commands

Where line nimber
prints in hexadecimal, the location in memory of the start  of  the
specified source line.

"WO and O" are the same command. They (it?) print  the  hexadecimal
address of the end of source.

These three (two?) commands, the LENgth command and the  EXEC  menu
(where  the  start  address  for  the  source  and  its  length are
displayed) are interrelated.

5.1.8  MONitor

MON exits to the monitor. You must re-enter by either  ^C,  ^B,  or
^Y. These re-establish the important zero page pointers from a save
area inside MERLIN` itself. Thus, ^Y will give a correct entry even
if you have messed up the zero page pointers while in the monitor.

DOS is not connected when using MON.

MON is provided for  experienced  Apple  programmers,  and  is  not
recommended to beginners.

Also, you may re-enter the EDITOR directly with an "0G" This entry,
unlike  the  others, will use the zero page pointers at $0A through
$0F instead of the copies saved upon exit.  Therefore, you must  be
sure that they have not been altered.

Since the ^Y, etc. method is always available, I'm not  quite  sure
why  I  told you about this 0G nonsense; you are just going to hurt
yourself and then come crying to me.

5.1.9  TRuncON

TRuncON is an immediate command that sets a flag for the  List  and
Print commands. This flag, when set, will terminate printing of all
lines with a space followed by a semicolon.  This  is  intended  to
make  it  easier  to  read  source  listings  on an Apple 40 column
screen.

TRuncON should not be confused with the TR command. The TR  command
goes in the source listing and is a command for the assembler.  See
the Assembler section for TR command usage.

5.1.10  TRuncOFF

TRuncOFF resets the truncation flag such that List and  Print  will
print  the  entire  line. TRuncOFF is the default condition for the
flag and it is reset on entry to the EDITOR mode  from  either  the
EXEC or Assembler modes.

Keep in mind that the what the preceding said;  "if  you  exit  the
EDITOR and then re-enter, TRuncOFF will be the default condition.

As with TRuncON, do not confuse this command with the Assembler  TR
command.

5.1.11  Quit

Exits to the EXEC mode.

5.1.12  ASM

This passes control; to the Assembler, which attempts  to  assemble
the source file. First you are presented with an "update the source
(Y/N)?" message.  If you answer "N" the assembly will proceed.

However, if you answer "Y", you will be placed in the EDIT mode  in
the  first  line in the source that contains a "/". When you finish
editing this line and hit return, assembly will begin.  If there is
no  line  with  a  "/"  or  while in the EDIT mode you Type:^C, the
assembly will be aborted and you will return to the EDITOR with all
I/O hooks established by "PR#n, etc. disconnected.

The idea behind the "/" convention, is to allow you to  keep  track
of  multiple  versions  of  a  program.  There  is no way (darn) to
permanently disable this annoying message  with  the  configuration
program.

5.1.13  Control-D (^D)

During the second pass of the assembly (the second pass is when the
listing  is being sent to the screen), if you Type:^D, the printing
of the listing is toggled such that it will either stop or  resume.
Since  this  command  toggles  the flag controlled by the Assembler
pseudo-op "LST", there exists an interaction such that the  listing
can start or stop subsequent to your issuing a keyboard ^D. Another
^D on your part will re-establish the wanted state.

5.1.14  Delete

This command deletes the specified line(s).  If LNn =  line  number
n, then Delete has the following forms:

D LNn                   Delete the line number.

D LNn,LNm               Delete line number n through m.

D LNn,LNm/LNo,LNp,...   Delete  line  number  n  through  m  and  o
                        through p,...

When N lines are removed, all subsequent lines move "up"  N  lines.
This  means  they  change!  Therefore, in the case of a range list,
you must specify the higher numbered range first (or have a strange
brain that likes computing the changed line numbers).

5.1.15  Replace

Replace has two forms:

  1.  R line number

  2.  R line number N through M

This command deletes the line number or range, then places  you  in
the Insert mode at that location.

5.1.16  List

If LN = line number then List has four forms:

L                  No parameters, list the entire source file.

L LN               List the single line number.

L LNn,LNm          List line number N through M.

L LNn,LNm,LNo,LNp  List line number N through M then O  through  P.
                   Note:  there  is  no requirement as to higher or
                   lower line numbers as is the case with Delete.

This command lists the specified portion(s) of the source file with
line  numbers  shown  on  the left. Control characters are shown in
inverse unless the listing is being  sent  to  a  printer  or  some
nonstandard output.

The listing can be aborted by a ^C or the slash (/) key.

The listing can be temporally stopped by hitting the space bar;  it
can  then  be advanced a line at a time by subsequent operations of
the space bar.  After being stopped by the space  bar,  it  can  be
restarted  by the operation of any other key.  This space bar pause
also works during the assembly and during the  symbol  table  print
out.

5.1.17  . (period)

Lists the source starting at the beginning of  the  last  specified
range. For example, If you type "L10,100" then lines 10 through 100
will be listed.  If you then type ".", the listing will start again
at line 10 and will continue until stopped or the end of the source
is encountered ( the end of a range is not remembered).

5.1.18  /[line number]

The slash continues listing from the last line  number  listed,  or
when  a  line  number  is  specified,  from that line.  The listing
continues to the end  of  the  source  file  or  until  stopped  as
explained under the List command.

5.1.19  Print

This command has the same format as List:

P          Print the entire source.

P LNn      Print line number N.

P LNn,LNm  Print line number N through M.

P LNn,LNm/LNo,LNp Print line number N through M, O through P.

Print is identical to List except line numbers are not  printed  as
the leftmost column.

5.1.20  PRinTeR [command]

The PRTR command is for sending a listing to a  printer  with  page
headers and provisions for page boundary skips.  Default parameters
may be set up using the configuration program  (see  the  Technical
section, "Configure ASM Program").  The syntax of PRTR is:

        PRTR slot# "[string]"[page header"]

If the slot number is greater  than  7,  a  "JSR  $#F5"  (ampersand
vector) is performed and it is expected that the routine there will
connect a printer driver by putting the address of same in  address
$36, $37 (high low format).

Note that the page header is optional and if  omitted,  the  header
will  consist of page numbers only.  However, the initialization is
not optional and  must  be  specified.  If  no  special  string  is
required  by  the  printer,  use  either  an unrecognizable control
character (unrecognizable by the printer) or the  NULL   string  (a
fancy  way  of  saying  two double quotes with nothing between). If
NULL specified, a  carriage  return  will  be  used.   Examples  of
initialization  strings  are  "^Q" for IDS printers, or "^I80N" for
most Apple cards.

The   exception   arises.    PRTR   0,   with   no   setup   string
required/allowed,  will allow you to see where page breaks occur in
the assembly.  If you are using an 80 column card, use PRTR  3  for
this function or die.

No output is sent to the  printer  until  a  List,  Print,  or  ASM
command  is  issued.  (Not  true,  the  printer is tickled with the
initialization string.  In any case, why would  you  issue  a  PRTR
command  if  you wern't going to issue a subsequent List, Print,...
command? Strange statement.)

5.1.21  Find

See the introduction to this  section  for  the  definition  of  d-
string, range, range list.

Find has the following formats:

F                        Lists all occurrences of string.

F(range)"d-string"       Lists  all  occurrences  of  d-string   in
                         range.

F(range list)"d-dstring" Lists all occurrences of string  in  range
                         list.

Find may be aborted  by typing either a  ^C  or  /.   The  ^L  will
toggle  the  case  so you can find strings with lower case strings.
In the case of Apple  //e,  you  can  use  either  the  lower  case
keyboard or the ^L method.

5.1.22  Change

Change has the following formats:

C"d-string1"d-string2"[line/range/range list]

this command changes occurrences  of  the  first  d-string  to  the
second. If none of the optional line formats is specified, then the
entire file is the default range.

Before the change operation begins, you are asked if  you  wish  to
change  "all  or  some." If you select some, by typing the "S" key,
the editor stops whenever the first string is  found  and  displays
the  line  as it would appear with the change. If you hit "ESC" the
change will not be made in that case.  Hitting the space  bar  will
accept  the  change  as shown.  It should be noted that if the same
string appears N times in the same line, you  will  be  prompted  N
times for approval/disapproval.

Typing ^C or / at any time will abort the change process.

5.1.23  COPY

COPY line number/range TO line number

This command copies the line/range to just above the specified line
number.  It does not delete anything (that is why it is called COPY
not MOVE) Also, note that "TO"  is  part  of  the  command  and  is
required.

5.1.24  MOVE

MOVE line number/range TO line number.

This command copies the line/range to just above the specified line
number.   It  then  deletes  the original lines.  You always end up
with the same number of lines except they are in a different order.
Also, note that "TO" is part of the command and is required.

5.1.25  Edit

E [line number,range,range list],[d-string]

Edit presents the line, range, or range list, line by  line  to  be
edited.  If a d-string is appended, only those lines containing the
string are presented.  Some examples are:

  1.  E 14 causes line 14 to be presented for editing. When <R>  is
      typed, you exit the edit mode.

  2.  E 14,20 causes lines  14  through  20  to  be  presented  for
      editing.   When  <R>  is  typed,  you  advance  to  the  next
      sequential line until line 20 has been edited. At that point,
      you will exit the edit mode.

  3.  E 14,20/2,14  same  sequence  as  above  except  line  2   is
      presented  after  line  20. Notice that line 14 appears twice
      with no harm.

  4.  E "sought text" causes  every  line  in  the  data  set  that
      contains the string "sought text" to be presented in turn for
      editing.

  5.  E 14,20,"sought text" causes every line from  14  through  20
      that  contains  the  string  "sought text" to be presented in
      turn for editing.

5.1.25.1  Edit Commands

Once in the edit  mode  the  first  line  of  the  range  you  have
specified  is  displayed on the screen with the cursor on the first
character. The line is tabbed as it is when listed  with  the  List
command. The cursor will jump from character to character and field
to field under control of the two horizontal arrow keys.  When  you
are through editing (using the commands to be discussed below or by
completely retyping over the old text) Type:<R> and  you  the  line
will  be  accepted  as  typed. In addition, you will go to the next
line in the range or you will exit the Edit mode if  this  was  the
only/last  line  to  be  edited  in the range. Please note that the
cursor does not have to be at any particular point on the line when
<R> is typed for the entire line to be accepted.

The Edit commands and functions are very similar, but not identical
to  those  in  Neil Konzen's "Program Line Editor" and Southwestern
Data System's "A.C.E."

All the commands, except ^R are available in the Add/Insert modes.

   ^I   Insert command.  ^I  begins  the  insertion  of  characters
        before  the  cursor.  This  command  is  terminated  by any
        control character except ^L which is the  upper/lower  case
        toggle.  Normal usage is to move to the insertion point and
        Type:^I text, followed by either of  the  horizontal  arrow
        keys  (which  are  ^H  and ^U i.e. control keys) to move to
        some other point on the line for further editing or <R>  to
        accept the line as it stands and move on to the next.

   ^D   Delete command. ^D deletes  the  character  underneath  the
        cursor.

   ^F   Find  command.   ^F  finds  the  next  occurrence  of   the
        character  typed  after  the ^F (on the line being edited).
        After the character is found, another ^F character sequence
        may be typed in. The arrow keys are much faster.

   ^O   Insert Special command.  ^O functions as described  for  ^I
        and  in addition allows the insertion of control characters
        and the typing of characters not  found  on  the  Apple  ][
        keyboard.   For  normal and control characters, simply type
        them after typing ^O.  For the unavailable  characters  see
        the following chart:

               <    gives   Control _

               >      "     Control backslash

               K      "     [

               L      "     backslash

               M      "     ]

               N      "     ^

               O      "     _

               k      "     {

               l      "     |

               m      "     }

               n      "     tilde

               o      "     Whatever $FF gives on your machine


        Note: If you are using a shift key modification,  depending
        on  which  one you have, shift-M may give upper case ^M and
        you will have to use ^O^O to get the right bracket.

   ^P   Do **** command.  If entered as the first  character  of  a
        line it gives 32 *'s.

   ^@   Do boarder command.  If entered as the first character of a
        line it gives 30 spaces boardered by *'s.

   ^C or ^X Cancel command.  Aborts the Edit mode  and  returns  to
        the  EDITOR.  The current line being edited will retain its
        original form.

   ^B   Go to line beginning command.  Places  the  cursor  at  the
        beginning of the line.

   ^N   Go to line end command.  places the cursor to the right  of
        the last character on the line.

   ^R   Restore line command.  Returns the  line  to  its  original
        form. This command is not available in the Add/Insert mode.

   ^Q   Delete line right command.  Deletes the part  of  the  line
        following the cursor.

   <R>  Return key.  The Return key accepts the line as it  appears
        on  the  screen  and fetches the next line to be edited, or
        returns to the EDITOR mode if the specified range has  been
        completed.

5.1.26  Hex Dec Conversion

If, in the command mode, you type a  decimal  number  (positive  or
negative) the hexadecimal equivalent is returned.

If you type an hex number (number is prefixed by a "$") the decimal
equivalent is returned.

All MERLIN commands accept hex numbers, which are mainly convenient
for  HIMEM and SYM commands.  However, if you wish to show off, the
Edit command will also accept hex numbers.

5.1.27  TEXT

This converts all spaces in a source file to  inverse  spaces.  The
purpose  of  this  is  for  use  on  "text" files so that it is not
necessary to zero  the  tabs  before  printing  such  a  file.  The
conversion has no effect on anything except the editors tabulation.

5.1.28  FIX

This undoes the effect of the command TEXT. It also does  a  number
of  technical  housekeeping  chores.  It is recommended that FIX be
used on all files from  external  sources,  after  which  the  file
should be saved.

Both TEXT and FIX are written in sweet 16  code  and  are  somewhat
slow.  Several minutes may be needed to process large files. FIX or
an Edit command will truncate any lines longer than 255 characters.

5.1.29  SYM

MERLIN places the symbol table on the language card (in bank  1  of
$D000  through  $DFFF).  This  space  is quite adequate for all but
gigantic programs.  In case this space is used up, the SYM  command
gives  you  a  means to direct the assembler to continue the symbol
table in another area. For example, if you type  "SYM  $9000",  and
assemble  the  program,  when  and  if the symbol table uses up its
normal space, it will be continued at $9000 until it reaches  BASIC
HIMEM.

It should be noted that the SYM command  will  be  cancelled  by  a
HIMEM  command  or  by  an exit to the EXEC mode, followed by a re-
entry to the EDITOR.  The above should make it quite clear that  if
your  are  going to use both HIMEM and SYM, then you must set HIMEM
prior to SYM.

The SYM address must be above MERLIN HIMEM and below  BASIC  HIMEM.
If  the symbol table grows beyond its alloted space, you will get a
memory error during the first pass of the assembly.

The interactions between SYM, MERLIN HIMEM, BASIC  HIMEM,  and  OBJ
(see  assembler)  are difficult to describe in a succinct manner to
an inexperienced programmer. By the time you are capable of writing
programs  that  require manipulation of these commands, you will be
an experienced programmer and the documentation provided  (here and
in the suggested reading guide) will be more than sufficient.

Using SOURCEROR on large ($3500 bytes) programs will cause  you  to
run  into these situations much earlier. Keep in mind that you must
have enough memory for the symbol table and the source. The  object
can be saved using the DSK which frees $8000 to BASIC HIMEM for the
symbol table. Using the PUT pseudo op as described will handle  the
very large source situation.

Also, remember that there are interactions between the above  named
commands/pseudo  op's.  Understanding will come only after repeated
reading/study/bloody experiences of/with same.

5.1.30  Video

The command is will select or deselect  an  80  column  board.  The
default condition can be selected using the configuration program.

VIDeo is similar to the use of PR# in BASIC.  However, Do  Not  Use
PR#  to  select  an 80 column board while in MERLIN.  PRQ# is to be
used to select a printer ONLY.

If your 80 column board is in  slot  3,  for  example,  it  can  be
selected by typing "VID 3", while in the EDITOR.

It is deselected by VID 0 or VID $10 possibly  followed  by  RESET.
The  latter  two  forms  both  select  the  standard  Apple screen.
However, VID 0 will cause all lower case output to the screen to be
converted  to  upper case.  Note that lower case in the source file
will be converted to flashing upper case (output to the printer  is
never converted).

If you have a lower case adapter, you will want to use VID $10  (or
VId  16 if you are a decimal freak) instead of VID 0 when selecting
the 40 column mode.

If your 80 column  card  has  aa  software  switch  via  an  escape
sequence,  this  may be used to return to 40 column mode. This will
be equivalent to VID $10 and would have to be followed by a  VID  0
if you don't have a lower case adapter.

For example, use:

   W ESC ^Q<R> on the Smarterm.

   W ESC Q ^X on the Sup"R" term.

5.1.31  FW

This is an alternative to  the  find  command.  It  will  find  the
specified  word  only  if  it  is  surrounded,  in  source, by non-
alphanumeric characters.  Therefore, FW"CAT" will find:

   W CAT

   W CAT-1

   W (CAT,X)

It will not find CATALOG or SCAT.

5.1.32  CW

Where FW  was  an  alternative  to  the  Find  command,  CW  is  an
alternative to the Change command.  It too will find and change the
specified string, only if  it  is  surrounded  by  non-alphanumeric
characters. See FW for examples.

5.1.33  EW

Edit Word is to Edit as FW is to Find. See FW for examples.

5.1.34  VAL

VAL :expression" returns the value of "expression" as the assembler
would compute it.  Examples:

VAL "LABEL"    Gives the address (or value) of LABEL for  the  last
               assembly  done  or  "unknown label" if the label was
               not part of the previous assembly.

VAL "$1000/2"  Returns $0800

VAL "%1000"    Returns $0008

VAL !"A"       Returns $0011

5.1.35  Add/Insert Mode

If not already done, it will prove very helpful to read  and  under
stand the Edit command prior to attempting these two commands.

The Add/Insert mode acts as if you are in  the  Edit  mode,  except
that  ^R will do nothing (this is reasonable since the there really
is no "original" state for the line).  In addition, exit  from  the
Add/Insert  commands can only occur if a null line is input (a line
with no text and <R> is typed).

5.1.35.1  Add

Add can only add lines behind the last line in the source.  If  you
wish  to add lines to any other point, see the Insert command which
follows.

If you Type:Add you will be placed in the Add mode.  It  acts  much
like  entering  BASIC  lines with auto line numbering. However, you
may enter lower case text (useful for comments) by typing ^L or  if
you  have  a shift lock key, you can release it.  ^L acts as a case
toggle; typing another ^L will return you to the upper case.

In any case, text is entered as [LABEL] OP [OPERAND] [;COMMENTS] or
*COMMENT or ;COMMENT by itself.  When you type the space after each
of the fields, you will be tabbed to the first column of  the  next
field.  This continues until you exit by typing a null line (<R> by
itself) or by either ^X or ^C. The control characters will exit and
also cancel the current line (if typed after a <R> which accepted a
previous line, the effect is the same as typing <R>).

The Add command is also useful for determining the last line number
in  the  source.  Simply  type  A<R> and subtract one from the line
number just to the left of the cursor.

5.1.36  Insert

Insert is identical to Add except it adds text above the  specified
line.

5.1.37  ^L

Control-L toggles the current case. If you are in  upper  case,  ^L
will  place  you  in lower, and vice versa. Upper case is defaulted
when entering each new line.

To change the case of a word already in the source,  Type:^L,  then
copy over the word using the right arrow key.