                 Hilfstexte zum GULAM-Hilfesystem
		 
         Dirk Donath, Vogelpothsweg 20, 4600 Dortmund 1
------------------------------------------------------------------	 

#ALIAS
>> alias         << 

The  'alias'  built-in command works almost like a shell file but
one  that is stored in the internal data structures of Gulam.  It
often just specifies a shorter or different name for a command.  

alias cc c:\megamax\mmcc.ttp                                    #1
unalias cc                                                      #2
alias cl 'mmcc e:\gulam\$1.c; cp e:\gulam\$1.o .; linkmm l.lnk' #3
alias r  'echo $1.c $1.o; r'                                    #4
alias                                                           #5
alias g 'echo $3 $1'                                            #6
alias cg 'f:\cc.ttp -c -V -Ie:\gulam -DMWC e:\gulam\$1.c'       #7

Alias  without  args  (see  #5)  lists  all  the aliases that are
currently  defined.    The   command  unalias (see 2) removes the
def  of an  alias.  Line 4 shows a recursive def; try it out!  If
we  invoke  g as in 'g a b c d e f' this is equivalent to 'echo c
a  d e f'; i.e., all arguments above the highest that was used in
a  $-substitution  are  appended  to the resulting command string
before executing it.  
#
#BATCH
>> Batch Files        << 

A  batch  file,  also  called  a  shell  file,  is  a  text  file
containing  Gulam  commands,  both  internal  and external.  Such
files  must  have the extension `.g' for them to be recognized as
commands.   See  the  section  on  gulam.g  for  an example shell
file.  

In  processing  these  files  Gulam  uses uE buffers.  So, if you
have  `ue'  as  a  command in a batch file, and then exit uE with
either  UNDO or ^X-^C, all the buffers (including the one holding
the  batch  file)  will be released, and Gulam will surely crash.
So, do NOT include ue as a command in a shell file.  
#
#COMMANDS
Usage: h <command>

Built-in commands:

alias    dirc     exit     history  msoff    pwd      source   unalias 
cd       dirs     fg       if       mv       rehash   sx       unset 
chmod    echo     fgrep    lpr      peekw    ren      te       unsetenv 
copy     egrep    foreach  ls       pokew    rm       teexit   which 
cp       ef       format   mem      popd     rmdir    time     while 
date     endfor   gem      mkdir    print    rx       touch    
df       endif    grep     more     printenv set      ue       
dm       endwhile help     mson     pushd    setenv   uekb     

Additional help:  batch
                  commands
		  variables
#
#CD
>> cd         << 

The   cd  command  changes   the    current working directory; it
also  sets the shell variable named cwd, the environment variable
named  CWD.  If cd was given noarguments,  it is equivalent to cd
$home.  
#
#CHMOD
>> chmod [+-w] filenames       << 

The  chmod  changes  the  read/write  attributes of the files: +w
makes them read-write, and -w makes them read-only.  
#
#CP
>> cp filenames target-dir       << 
>> cp filename1 filename2       << 

Copies  files.   In  the  first  form, any number of files may be
copied  into  the destination directory;  files in the target dir
will  have  their  original  names.  In the second form, only one
file is copied, and the new one will be named filename2.  

cp fnm fnm    # will exit with status -1 
cp d1 dir2    # if  d1  is  a  directory,  this command will create a dir 
              # named  d1  in dir2, and copies all the files in d1 to 
              # dir2\d1 

There  is  a `+t' option that gives the created target files  the
time  and  date of the source files.  If you care about this, you
may want to set up an alias as in: 

  alias cp 'cp +t' 
#
#DATE
>> date         << 

The  date command, without arguments, prints the current date and
time.  With arguments, it sets the date and time.  

        date 01-22-87-22:08:34 

will set the date to Jan 22, 87 and time to 10:08:34 pm.  
#
#DF
>> df drivenames        << 

Df  shows the free space on the asked for drive(s); e.g., 'df a c f' 
#
#DM
>> dm         << 

-- drive map 

Gives a string of letters that stand for the installed drives.  
#
#DIRC
>> dir_cache dirc        << 

To  help  do the Tenex file name completion efficiently, there is
a  cache  of  contents  of  directories.  Dirc shows the names of
these  dirs,  and  how  many  bytes  are  used by their contents.
Unless  you did a 'set dir_cache 1', the dirc has nothing to show
since  the  cache  is  flushed  at  the end of each command.  Try
Gulam  with  dir_cache set to 1.  Note however that this cache is
updated  only  by  the  'ls'  command; so even after  you deleted
some files, file name completion may still find those names.  
#
#DIRS
>> dirs         << 

Gulam  has  an  internal  stack  of  directories whose content is
printed  by  the  dirs command.  The built-in commands pushd, and
popd are the only others that operate on this stack.  
#
#ECHO
>> echo         << 

The echo command prints its arguments.  
#
#EF
>> ef         <<
-- see if               (stands for elseif)
#
#EGREP
>> egrep         <<
-- see grep
#
#FGREP
>> fgrep         <<
-- see grep
#
#ENDIF
>> endif         <<
-- see if
#
#ENDFOR
>> endfor         <<
-- see foreach
#
#EXIT
>> exit [number]        << 

The   exit  built-in  command  is  used to force termination of a
shell script.  
#
#FG
>> fg         << 

Fg  is  part  of  the simulation of what we were used to doing on
Unix  with  GNU-Emacs:  get  out  of  it  by  stopping GNU (^Z in
ue/Gulam),  do a few shell commands and get back in  by fg (works
the same in ue/Gulam).  
#
#FOREACH
>> foreach         << 

The   foreach  command  is  used in shell scripts (but not at the
terminal)  to   specify   repetition  of  a  sequence of commands
while  the value of  a  certain  shell  variable  ranges  through
a  specified  list.  The foreach command ends with an "enfdor" on
a separate line all by itself.  

        foreach i { a b c *.o [a-k]*[ch] } 
                echo $i 
        endfor 
#
#FORMAT
>> format         << 

This  command  formats  diskettes, in the standard form (360K, or
720K)  in  either  the  A  or  B floppy drive.  It does not touch
hard-/ram-disks,  no  matter  what arguments (illegal or not) you
give  it.  Its valid arguments are either `a', `b', or both.  The
optional  flag  `-2'  implies  double-sided formatting; otherwise
the diskette is formatted single-sided.  

  format        # does nothing 
  format b      # format the floppy in drive B, single-sided 
  format -1 b   # same as format b 
  format -2 a   # format the floppy in drive A, double-sided 

If  you  issue  the  wrong  command  (e.g.,  `format  -2  a' on a
single-sided  drive),  you  will hear a lot of grinding noises; a
control-C will kill this, but not right away.  
#
#GEM
>> gem         << 

The  word  "gem"  is a prefix, like "time" is, to commands.  This
enables  proper  running  via Gulam of most programs that use the
desktop  metaphor.   It  clears screen, turns cursor off, enables
mouse  and  then  executes  the command, and after the command is
finished  it  again  clears  screen,  turns  cursor  on, disables
mouse.
The  "time"  and  "gem"  prefixes  mix  in  either order, and the
command name will be searched for in the usual way.  
We  do  not  know, for sure, if all desktop/window/mouse oriented
programs  can  be  run  properly  with  this  command prefix.  So
experiment,  and  be  ready  to hit the reset button before using
the prefix.  
Dvi  is  an  example of a command that needs to be run with `gem'
prefix.  And you may be tempted to do the following.  

  alias dvi 'gem dvi'                   # recurses infinitely 
  alias dzz dvi                         # dzz or whatever 
  alias dvi 'gem dzz'                   # will work 
  alias dvi 'gem c:\bin\dvi.prg'        # also will work 
#
#GREP
>> grep/egrep/fgrep re-pattern filenames       << 

The   grep  command searches through a list of argument files for
a specified string.  Thus  

        grep lex[aw] e:\gulam\*.c 

will  print  each  line  in  the  files that contains a substring
matching  lex[aw].   Grep   stands   for   `globally find regular
expression  matches  and  print'.  Grep and egrep are one and the
same.   The  first argument to egrep is a regular expression, and
the  rest  are expected to be file names.  Fgrep's first argument
is  the as-is string to be searched for in the files.  Because of
the  preprocessing  done  by Gulam, the as-is string for fgrep or
the   regular   exp   for   egrep   is   generally   enclosed  in
single-quotes.  
#
#VARIABLES
>> Gulam Variables and Environment      << 

The  following shell variables cause/control useful effects.  The
format  of  the  explanation  is  `variable_name:  default-value;
meaning'.  

batch_max_nesting: 20;  if  you need to nest batch file execution
    at levels deeper than this, change this variable.  
batch_echo: 0;  if  1  echoes each cmd of the batch file as it is
    executed.  
baud_rate:none; for  use  in  the  terminal  emulator, rx/sx file
    transfers.  
cwd:CWD: full  pathname  of  current directory; gets re-set every
    time a cd, pushd or popd is executed.  
dir_cache: 0; (if non-0, turns on the dir list cache) 
home,HOME: full   pathname   of   home  directory;  home  is  the
    directory you were in before invoking Gulam.  
ginprompt: $<;  the  prompt  shown  when  asking you for input in
    dollar-substituting a $<.  
histfile: none; reads and saves history in file named $histfile 
ncmd:   number  of  the  current  command;  gets  set  after each
    executing each command.  

The following  pr_XXX  vars are relevant with  `print', and `lpr'
    commands.  When set, these strings are sent to the printer : 
pr_bof:unset; send before printing each new file 
pr_eol:`^Qr^Qn'; send after each line 
pr_eop:`^Q214'; send after each page (214 == ASCII ^L + 0200).  
pr_eof:`^Q214'; send after the end of file.  
    Thus,  to  have  a  left  margin of eight-spaces, just define
    pr_eol  as  '^Qr^Qn^Qt'.    To turn condensed mode etc., just
    set  pr_bof  to the appropriate string after looking it up in
    the  printer's  manual.   See  the  section on strings for an
    explanation of ^Q.  
    
prompt          >>; see gulam.g for an example 
rgb,RGB         '000-700-007-070-';  sets  the  palette:  3 octal
    digits (followed 
            by a  dummy  '-')  per  color;  2  in  hi-rez,  4  in
    med-rez, 16 in low-rez 
rx_remote_command:unset; command  to  send  to  remote to receive
    file  with  Xmdm.  For our Unix, this string is `xm st'.  The
    rx  command  appends  a  space  followed by the file name and
    sends  the  resulting  string  to  the remote as if you typed
    it.  
sx_remote_command: unset;  command to send to remote to send file
    with Xmdm.  Similar to the above.  
semicolon_max: 20;   (Number  of  `;'  per line; to stop infinite
    recursions in alias expanded commands.) 
status: status  of  the  most  recent external command; set after
    each external cmd.  
sz_rs232_buffer: unset;  The  built-in  terminal  emulator,  when
    invoked,  will  reallocate  a  buffer  of  this size (if this
    value  is  >  256) for the associated IOREC.  If unset, or if
    set  but  to  a  value  lower  than  4096, you may experience
    XON/XOFF occuring at 9600.  I recommend 4096.  
time: unset; if set to non-0, times every command.  
#
#HELP
>> HELP         << 

The  all-upper  case  name HELP in this manual stands for the key
marked  HELP on the Atari ST.  Pressing this key, outside the ue,
will  show  all  the Gulam built-in commands, and a brief version
of  the  hash  table.   Within  ue, it can show the binding of an
individual key, or produce a wall-chart of all bindings.  

The  shift-HELP  key  resets  the  special key table mapping that
Gulam/uE  use;  after  pressing shift-HELP the function keys, and
arrow  keys  become equivalent to ^@, and the keypad will work as
a  typcial  numerical  keypad.   To  get back to the Gulam/uE key
table,  press  ^L,  which not only refreshes the display but also
sets the key table.

Typing  the letters 'help' while outside ue, or in buffer >gulam<
is equivalent to pressing HELP.  
#
#HISTORY
>> history [-h]        << 

The   history command lists the last N commands.  Each command is
preceded  by  its  number;  to suppress these numbers, supply the
"-h"  flag.  The value N is obtained by $history.  To change this
N to, say, 30, do "set history 30".  

>> History Substitutions        << 

        Occurrences of  the  form  !!,  !number, !string refer to
the  text  of  previously  issued  commands.    The text of these
older  commands  itself does not contain ! unless it is part of a
string  argument.   Each   !!  is  replaced  by  the  text of the
immediately  preceding  command.  Gulam consecutively numbers the
commands  that  you  have issued.  (The current count can be seen
in  the  shell variable named ncmd.) Each   !n is replaced by the
n-th  old  command.   Each  !str is a replaced by the most recent
old command that begins with str.  
The  name  completion  feature  works  with history substitutions
also.   Pressing INSERT or ESC-ESC will bring the history-matched
command  and  replace  the  current line in the buffer, which you
can further edit.  
#
#IF
>> if         << 

The  if  stmt  is similar to those in many programming languages.
The  Boolean  expression  of  shell  if  stmts typically involves
tests  on  file  names and types.  (See Expressions.) There is no
'then'.    Any  remaining  lexemes  after  the  Boolean  exp  are
ignored.  

        if {-d e:\gulam\lex} + 2 == 3 
                echo e:\gulam\lex is a dir 
        ef -e e:\gulam\lex      # read ef as `else if' 
                echo e:\gulam\lex does exist 
        ef 
                echo e:\gulam\lex does NOT exist 
        endif 
#
#LPR
>> lpr filenames        << 

The   command   lpr prints its files as-is, with no processing at
the end of lines.  
#
#LS
>> ls [-lRLF] filenames       << 

The   ls  (list  files)  command, with  no  arguments, prints the
sorted  list of names  of the files in the current directory.  It
has  a  number  of  useful   flag  arguments,  and  can  also  be
given   the  names of directories  as  arguments,  in  which case
it lists the names of the files in these directories.  

        If no  flags  are  given,  ls  prints only the filenames.
The  -L  causes  a  full-length  line  for  each  file giving its
attributes,  size, creation date, and name.  The -l (small el) is
the  same as -L except that the output is sorted by name.  The -R
will  cause  the  subtrees of directories in the argument list of
files  to  be  traversed.   The  -F  will  append  to each listed
filename  one  char  that indicates the type of that file: '*' if
it  is executable (i.e., has an extension of .prg, .tos, .ttp, or
.g), a '\' if its is a directory, a ' ' otherwise.  
#
#MEM
>> mem         << 

Mem  shows  the  largest free chunk of memory available.  It just
does a  Malloc(-1L) and reports the result.  
#
#MD
>> md         <<
-- see mkdir
#
#MKDIR
>> mkdir names        << 

The  mkdir  command creates new directories with the arguments as
their names.  
#
#MORE
>> more         << 

This is a built-in alias, if you will, to ue -r.  
#
#MV
>> mv filenames target-dir       << 
>> mv filename1 filename2       << 

Moves  files.   In  the  first  form,  any number of files may be
moved  into  the destination directory;  files in the target dir
will  have  their  original  names.  In the second form, only one
file  is  moved, and the new one will be named filename2.  On the
Atari  ST,  moving  files  is  accomplished  by  copying and then
deleting  the  source  file unless it is the second form and both
are in the same directory.  
#
#MSON
>> mson/msoff         << 

These  enable/disable  the  mouse.   Gulam/ue does not use mouse;
we  intend  to  in  a good way.  Most GEM-based .prg programs use
mouse,  but do not set it up themselves.  Some of these will hang
if  invoked   from  Gulam,  which  is no big deal;  do 'mson' and
then try.  
#
#PATH
>> PATH         << 

A   comma-separated  list  (with  no white chars)  of directiries
should  be the value of this environment variable.  This value is
use  by  'rehash'  command.   Rehash  scans  the  files  in  each
directory  looking  for  executable  files  (by  def,  files with
extensions  of .prg, .tos. .ttp, or .g).  The leaf names and full
pathnames  are  entered  into  a  hash  table.  Typing the 'help'
command  (not  the  HELP  key) will list the hash table in brief;
'which'  command  lists  it  in full.  Gulam does NOT auto rehash
whenever  PATH  is  changed  (which I will change if a lot of you
think it should).  

        setenv PATH c:,c:\bin,d:\mwc\bin 
#
#PEEKW
>> peekw and pokew       << 

Peekw  and pokew are similar to their namesakes in BASIC.  We use
privileged  mode  to  alter/access any arbitrary location.  These
commands  expect  their  arguments  to be hex numbers.  The pokew
command should be used with care.  

 peekw 420         # shows you what is at word at 0x420 
 pokew 420 123E    # sets word at 0x420 to 0x123E 
#
#POPD
>> popd         << 

The   popd  command  changes the shell's working directory to the
one on top of the directory stack.  Also, sets cwd, and CWD.  
#
#PRINT
>> print filenames        << 

The   print   command   is   used  to  prepare  listings  of  the
contents  of files  with  headers giving the name of the file and
the date and time at which the file was last modified.   
#
#PRINTENV
>> printenv         << 

The  printenv  command  is equiv to setenv with no args.  
#
#PUSHD
>> pushd [dir]        << 

The   pushd   (push  directory)  command  pushes  the name of the
current  directory  on  to  the  internal  stack, and cd's to the
directory  given  by  the  argument.   You can later do a popd to
return  to  the  present  current  directory.  The command pushd,
without  arguments,  exchanges the working directory with the one
on top of the stack.  
#
#PWD
>> pwd         << 

This   built-in  command   prints   the  full   pathname  of  the
current working directory.  
#
#REHASH
>> rehash         << 

-- see PATH 
#
#REN
>> ren fnm1 fnm2       << 

Rename  file  fnm1  as  fnm2;  they  both  must  be  in  the same
directory.  
#
#RD
>> rd         <<
-- see rmdir
#
#RMDIR
>> rmdir dnm      <<

Removes the directory dnm. The directory must be empty.
#
#RM
>> rm filenames        << 

Rm  removes  the  named  files.   Most  of  us have the following
aliases in our gulam.g files: 

        alias rm rm -i 
        alias Rm rm 

which  queries you, for each file, before deleting it.  We use Rm
when  we are really sure we want to delete the file(s).  There is
no  special check to see if you typed 'rm *.*' or 'rm *'; both of
these will clear your current directory.  
#
#SET
>> set [name value]       << 

The   built-in   set   command   is  used to assign new values to
shell   variables    and  to  show  the  values  of  the  current
variables.   The  command  without  any  arguments  lists all the
shell  vars and their values.  When arguments are present, second
and  subsequent  words  are processed as an expression yielding a
value  which  is  then assigned to the first argument.  The unset
command deletes a variable.  

  set i  {  $j > 10 }    # sets i to 1 if $j is > 10; to 0 otherwise 
  set x "hi there" 
  set y $i + 4 @ 2       # @ stands for multiplication 
#
#SETENV
>> setenv         << 

Variables   in   the   environment  can  be changed by using  the
setenv   built-in   command.   The  setenv  command  without args
prints    the    values    of    all   the   variables   in   the
environment.   
#
#SOURCE
>> source file-name        << 

The  contents of file file-name are excuted by Gulam.  Unless the
file-name  has  an  extension  other  than  .g,  use  the simpler
command 'file.g' instead.  
#
#SX
>> sx        <<
-- see variables
#
#RX
>> rx        <<
-- see variables
#
#TE
>> te/teexit         << 

Te  (also  bound to Keypad-0) gets you into the built-in terminal
emulator.   If  you have baud_rate set up properly (see gulam.g),
the  rs232  port  is set to that speed, and you are switched to a
fresh  screen.   Set  sz_rs232_buffer  to  a  large  value if you
encounter  XON/XOFF  problems  too frequently.  We have  used the
following   TERMCAP  and  used  vi,  GNU-Emacs  etc  without  any
problems.  

To  return  to the local mode after having done 'te', press UNDO.
Then  a  Keypad-0  will  take you back to remote with your remote
screen  in  tact.   After  you  are finally done with your remote
system,  press UNDO, and then issue a 'teexit' to reclaim the 32k
used for the extra screen.  
#
#TIME
>> time [command]        << 

The   word time when prefixed to a regular command, it prints the
elapsed  time  after  the  command finishes.  If you set variable
named  `time'  to  a non-zero value, each and every command, even
if  they  are  not  prefixed  with  the  word 'time',  will be so
timed.  

   time  ls -lF c:\     # See how long it takes 
   set   time  1        # After this, all command will be timed until 
        set   time 0    # you do this, or 
        unset time      # this 

If  you  set  up aliases with `time' prefixes in them, watch out!
The  discussion  under the section on Gem is applicable to `time'
also.  
#
#TOUCH
>> touch fnms        << 

Touch  updates  the  time  stamp on the files to current time and
date.  
#
#UE
>> ue [-r] [fnms]       << 

This  command  takes you into the built-in microEmacs editor.  If
no  args  are  given,  you  will  land  in  the  >gulam<  buffer,
otherwise  in  the buffer of the  last named file.  The output of
Gulam  commands  executed while you are within >gulam< is entered
into  that  buffer;   this,  of  course,  consumes  malloc-space.
Meta-g brings you into >gulam< if you are in another buffer.  
To  examine  the key bindings, press HELP-key first, and then a B
while  inside  ue.  To rebind them to suit your tastes, see uekb.
On  the  Atari  ST, all the keys are bound (thoughtfully, I hope)
to  useful  commands.  F1 through F5 delete things; F6-F10 update
files  and  buffers;  Keypad  keys cause harmless cursor motions;
Keypad  0  (zero)  switches you to the (remote computer hooked to
the)  rs232  port;  to  return  to  your local Atari, press UNDO.
HELP  is  for (not much) help; UNDO will exit after saving files;
the rest of the keys in that group move the cursor around.  
The  -r  flag causes the buffers of the files following the -r to
be  marked  as  read-Only.  You can still edit these buffers; but
the  read-Only  mark  causes  ue  to  ask before writing to these
files.  
Do try ^Z, ^X-! and Meta-X-! commands.  
#
#UEKB
>> uekb redefine microEmacs keybindings      << 

To bind key with code 144 to function with hex-number 1d, do 

        uekb 144 1d      

You  can  find  the key codes and hex-numbers of functions in the
wall-chart  (shown  below), which can be produced by pressing the
HELP key, and then a B.  
#
#UNALIAS
>> unalias [aliassed-name]        << 

The unalias command removes aliases.   
#
#UNSET
>> unset [var-name]        << 
>> unsetenv [env-var]        << 

The unset command removes the definitions of shell variables.  
#
#WHICH
>> which         << 

The  which  cmd  displays the internal table of names of external
cmds,  and the full pathnames of the files that contain them.  If
nothing  gets  displayed,  either  you did not do a `rehash', did
not  setenv  the PATH, or none of the directories in PATH had any
executables.  
#
#WHILE
>> while         << 

The   while   built-in   control   construct   is  used  in shell
command  scripts.   Instead  of  echo  and set in the body of the
loop shown below, you can use other commands.  

        set i 10 
        while $i > 0 
                echo $i 
                set i $i - 1 
        endwhile 
#
