Brief user documentation for Rug.

The order of things  in this document  is pretty random.   Someday
someone should fix it.

Basically Rug expects a symbolic expression followed by a  command
which operates on the expression, e.g.  "FOO+5=" where "FOO+5"  is
the symbolic expression and "="  is the command.  Commands may  be
one letter (e.g.  "="), one letter following an escape (e.g.  "$L"
where escape will echo as a  dollar sign), or a colon followed  by
up to six letters (such as ":HELP").

Symbolic expressions may contain any defined symbol, octal number,
or decimal  number (digit-string  terminated with  a period,  e.g.
"143."  whereas "143" without the  "."  would be octal)  connected
with the  arithmetic  operators  "+",  "-",  or  space  (which  is
equivalent to "+" for  convenience).  $Q (Escape  Q) is a  special
symbol whose  value  is the  last  quantity that  rug  typed  out.
Further, the user can generate ascii or rad50 codes for characters
and  use  these  numbers   in  any  symbolic  expression:   Typing
single-quote followed by one  letter produces the 16-bit  quantity
containing the letter in the low  byte and zero in the high  byte.
Typing double-quote followed by two ascii letters will produce the
16-bit quantity containing the  first letter in  the low byte  and
the second in the high byte.  Typing "&" followed by three letters
produces the 16-bit rad50 equivalent of the letters.

If the user types an undefined  symbol in an expression, Rug  will
beep, generally  allowing  the  user to  rubout  and  correct  the
symbol.  When the expression is done an error will usually  result
(unless the  command  doesn't care)  if  there was  any  undefined
symbol within  the  expression.  There  is  one exception  to  the
beep-rule: if the  first symbol  in the  expression is  undefined,
then the expression will  be terminated immediately, not  allowing
the user to correct it.

Many commands will produce different results depending on  certain
modes that  the user  can set.   Most modes  have "temporary"  and
"permanent" settings: temporary modes act until Rug prompts with a
"*".  The "*" prompt indicates that  all modes have been reset  to
their permanent settings.

There are  several  symbols  with predefined  values.   These  are
listed below (note that  "user" refers to  the user program  being
run, e.g.  "user R0" means the programs R0):

.		Contains the last address opened.
%0  -  %7	Standard register definitions (user regs).
.M		Mask for searches:
		.M has the 16-bit mask.
		.M+1 has the 16-bit low address.
		.M+2 has the 16-bit hi address.
.STBEG		Location containing pointer to bottom (low
		address) of symbol table.
.STEND		Address of bottom of predefined RUG symbol table.
.START		Address of RUG's starting address.
.MXOFF		Initially 200.  A value must be within this distance
		symbol to be printed as that symbol+offset.

ESCAPE COMMANDS (<arg> is symbolic expression):

$Q		Value of last quantity typed out

$G		Start execution at default start address.
<arg>$G		Start execution of user program at <arg>.
<arg>$$G	Set default start addr to <arg> and start execution.

<arg>$W		Search from low-address (.M+1 contents) to high-address
		(.M+2 contents) for <arg> masked by contents of .M.
		Each match found will be shown by printing location and
		contents.  Any type-in by user will stop the search.

<arg>$E		Same as W but effective address search.  I.e. BR FOO
		will match an arg of FOO.

<arg>$B		Set a breakpoint at <arg>.  (There are 8 breakpoints
		available.  Use :LISTB to see where breakpoints are
		currently set.)

<arg>$P		Proceed user program after hitting breakpoint. If no
		<arg>, proceed until hitting any breakpoint.  If <arg>
		then set this breakpoint's count to <arg> and proceed.
		If a breakpoint has a count, then it will only break
		after being hit count many times.

<arg>$U		Remove breakpoint at <arg>.  If no <arg> then remove
		all breakpoints.

$C		Set temporary type-out mode "contants", i.e. type
		contents of open locations as octal numbers.

$S		Set temp type-out mode "symbols", i.e. type open
		location contents as symbols.

$I		Set temp type-out mode "instructions", i.e. type
		open location contents as instructions.

$R		Set temp type-out mode "relative addresses", i.e.
		type addresses as symbolic references, INC FOO.

$A		Set temp type-out mode "absolute addresses", i.e.
		type addresses as octal numbers, INC 14345.

$"		Set temp word type-out mode to "ascii", i.e. when
		opening words, type out ascii characters.  

$'		Set byte word type-out mode to "ascii", ie. when
		opening words, type out ascii characters.
				
		Note that examining a location in Ascii mode that
		contains control characters will cause them to be
		shown as the usual ^<char> representation, (or $ for
		escape) except that Space, CR, LF and Bell will
		actually be sent to the terminal, Tab will cause the
		correct number of spaces to be sent,and FF will
		clear the screens on displays and CRLF on theirs.

$&		Set temp type out mode to radix 50.
		ASCII		    A - Z    $    .    %   0  - 9
		Radix 50 (in octal) 1 - 32   33	  34   35  36 - 47

$$C $$S $$I $$R $$A $$" $$' $$&
		Like $C $S $I $R $A $" $' and $& but set permanent
		type-out modes.

$L		Load program.  Source loaded from depends on how
		this RUG was assembled and environment its running in.
		For stand alone disk system, takes block number after
		the L.

$Y		Dump program.  Only meaningful in standalone disk
		system thus far.  Takes arg of lblock number after
		the Y.

$Z		Zero all of core.  I will change this to $$Z to be less
		dangerous soon.


SINGLE-LETTER COMMANDS:

<symbol>:	Define <symbol> to be . (i.e. current location).

<arg>=		Print value of <arg>.

<arg>><symbol>	Define <symbol> to be <arg>, e.g. 1234>FOO defines
		FOO to be 1234.

<arg>/		Open location <arg> as word.

<arg>\		Open location <arg> as byte.

<arg><CR>	(Carriage-return) Deposit <arg> into current location
		if it is open and then close the location and prompt.
		No <arg> means no change to current location.

<arg><LF>	(Line-feed) Deposit <arg> into current location if
		open, then open next location.  No <arg> means no
		change to current location.

<arg>^		Deposit <arg> and open previous location.  No change
		if no <arg>.

<arg>]		Open location <arg> as symbol.

<arg>[		Open location <arg> as number.

<symbol>$K	Half-kill <symbol> so that it won't be used for
		printing symbolic addresses.

$$K		Kill all symbols in program.

^L		Clear screen.

<arg>^N		Proceed program in single-step mode: no <arg> means
		execute one instruction;q  <arg> means execute <arg>
		instructions then return to RUG.

_		Type out <arg> in symbolic mode, but don't set
		either the temporary or permanent modes.

;		Type out <arg> in the last specified temporary
		or permanent mode (see $A, $C, $I, $R, $S).

$;		Like ; but also set the temporary mode to the
		last specified temporary or permanent mode.

$$;		Like $; but set permanent mode instead of
		temporary mode.

@		Open location addressed by PC in instruction mode

COLON COMMANDS:

:HELP		List the colon commands.

:LISTB		List all breakpoints set, and their counts.

:EXIT		Exists Rug