home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / cli / okami15.lzh / OKAMI15 / DOC / ENGLISH.DOC < prev    next >
Encoding:
Text File  |  1992-09-20  |  9.0 KB  |  275 lines
  1.  
  2.  
  3.  
  4.         ==================================================
  5.  
  6.  
  7. @(#)      OKAMI SHELL VERSION 1.5 - ENGLISH INSTRUCTIONS
  8.  
  9.  
  10.         ==================================================
  11.                         Sep 19th, 1992
  12.  
  13.  
  14.  
  15.  
  16. The  Okami  Shell is a Unix-like CLI for the Atari ST.  It should run on
  17. any ST. 1 MB and harddisk are recommended, modem and mouse are optional.
  18. It  will  run on all screen resolutions,  although some commands require
  19. lines to be at least 80 characters wide. MiNT is supported. 
  20.  
  21. The  Okami  Shell  resembles  the  Unix  Bourne  Shell (/bin/sh)  and in
  22. particular  the  AIX  Shell  found  on  the IBM RT 6150 computer system.
  23. Although  not  completely compatible to the original,  it gives the user
  24. much of the comfort of the Unix interface. 
  25.  
  26. The Okami Shell has some 100 built-in (internal)  commands. They are all
  27. listed  in the file `help'  which can be viewed with the command "help".
  28. Pressing  the  HELP  key  after  entering  a  command  will  display the
  29. appropriate  chapter from the file named by the shell variable HELPFILE.
  30. (No english version yet, sorry) 
  31.  
  32.  
  33. SUPPORT
  34.  
  35. The  Okami  Shell  is  public domain.  Everybody may possess,  use,  and
  36. distribute  it  without  profit.  There are no shareware fees,  although
  37. donations are greately appreciated. 
  38. Hints and suggestions are always welcome. So are all errors you found in
  39. the  program and the documentation (including language errors :)).  Send
  40. them to 
  41.  
  42.         Wolfram Roesler
  43.         Augustastr. 44-46
  44.         W-5100 Aachen
  45.         Germany
  46.  
  47.  
  48. or via EMail:
  49.         wr@bara.oche.de
  50.         or via Mausnet gateway to: Wolfram_Roesler@ac2.maus.de
  51.  
  52.  
  53.  
  54. INSTALLATION
  55.  
  56. The  shell  doesn't  require  any  installation except copying the okami
  57. folder onto the hard disk or a diskette. 
  58. After  starting,   the shell executes the file `profile'  in the current
  59. directory  as  a shell script.  So,  you should tailor this file to suit
  60. your needs. 
  61.  
  62.  
  63.  
  64. STARTING
  65.  
  66. The shell can be started from the desktop by double-clicking on sh.ttp .
  67. Any  commands entered on the command line will be executed by the shell.
  68. They may be introduced by `-c'  which is ignored.  Having executed these
  69. commands, the shell will exit. 
  70. When a single `-'  is passed as a parameter,  the shell will execute the
  71. file  `profile'   in the current directory.  If the environment variable
  72. OKSH_PROFILE  is  set  to  the  name  of a file,  then that file will be
  73. executed as a profile. 
  74. It  is  recommended  to  start the shell with a `-'  parameter using the
  75. supplied  msh.prg  since there will be trouble running GEM programs from
  76. the shell if it has been started as a ttp from desktop. 
  77.  
  78. The  shell  installs  itself in the _shell_p vector from where it can be
  79. called by successive programs using the C library's system() function. 
  80.  
  81.  
  82.  
  83. ENDING
  84.  
  85. The shell can be terminated by entering `exit' or pressing Ctrl-D. 
  86.  
  87.  
  88.  
  89. RUNNING PROGRAMS
  90.  
  91. All  executable  programs  can  be started by the shell.  However,  some
  92. shell variables have to be set: 
  93.  
  94.         XEXT    must contain the extenders of all files that are to
  95.                 be considered binaries. The default is
  96.                 ".prg,.tos,.ttp,.app".
  97.         GEXT    must contain the extenders of all files that are to
  98.                 be started as GEM programs. The default is ".prg".
  99.         PATH    must contain all directories (including drive id) that
  100.                 are to be searched for executable files.
  101.  
  102. So,  if XEXT is ".prg,.ttp" and PATH is "c:/bin,$HOME/bin", after typing
  103. "cmd",   the  shell will seek the files c:/bin/cmd.prg,  c:/bin/cmd.ttp,
  104. $HOME/bin/cmd.prg  and $HOME/bin/cmd.ttp and execute the first file thus
  105. found. 
  106. Arguments  will  be  passed  to started programs in the ordinary fashion
  107. (basepage  via  Pexec)  and using the xArg protocol.  If xArg passing is
  108. not desired, it can be switched off by typing "set -a". 
  109.  
  110. Any file can be run as a (binary) program with the shell command `exec'.
  111. So,  typing `exec file.xyz'  will run file.xyz regardless wether .xyz is
  112. in  $XEXT  or  not.  If .xyz is in $XEXT,  file.xyz can be run by simply
  113. typing `file'. 
  114.  
  115. When using MiNT, background processes may be started with `&', e.g. 
  116.  
  117.  
  118.         getty u:/dev/tty &
  119.  
  120.  
  121. will start the "getty" program in the background. 
  122.  
  123.  
  124.  
  125. SHELL SCRIPTS
  126.  
  127. A  shell  script  is  an  ascii  file  containing shell commands.  Lines
  128. beginning with a # are interpreted as comments. 
  129. Shell  scripts  can be started just like binary programs.  However,  the
  130. extenders  of  all  files to be considered scripts must be stored in the
  131. shell variable SEXT. The default is ".sh" which should do in most cases.
  132. Any file can be run as a shell script by using the `.' command. I.e., 
  133.  
  134.       . shscript.txt
  135.  
  136. will run the file shscript.txt as a shell script.  Note: you must supply
  137. the full filename and extender here, PATH and SEXT are not evaluated. 
  138.  
  139.  
  140.  
  141. SHELL FUNCTIONS
  142.  
  143. A  shell function simply is a shell script held in memory.  Any file can
  144. be loaded to make a shell function by typing: 
  145.  
  146.         cmd(filename)
  147.  
  148. this  will  load the named file and store it so that it can be called by
  149. typing `cmd'.  If cmd is ommited (i.e. by typing `(filename)'), the base
  150. name of filename (without extender) will be used. Example: 
  151.  
  152.         (showpic.sh)
  153.  
  154. will  load  the supplied file `showpic.sh'  into memory,  making a shell
  155. function named "showpic". 
  156.  
  157. Shell  functions  can  be created by shell scripts or by typing from the
  158. keyboard in the following manner: 
  159.  
  160.         name()
  161.         {
  162.          ....................  any commands
  163.         }
  164.  
  165.  
  166. Removing:
  167.  
  168.  
  169.         name()
  170.         {
  171.         }
  172.  
  173.  
  174.         or `unset name'.
  175.  
  176. The  shell command `alias'  can be used to create brief shell funktions.
  177. So,   `alias  ll  ls -l'  will create a shell function named `ll'  which
  178. executes `ls -l'  when called.  When using `alias'  to rename a built-in
  179. command, use it prefixed with a `!', e.g. 
  180.  
  181.         alias ls ls -C
  182.  
  183.  
  184. will recurse forever, whereas
  185.  
  186.  
  187.         alias ls !ls -C
  188.  
  189.  
  190. is correct.
  191.  
  192. A  list  of all shell functions can be created with the internal command
  193. 'fcts'. 
  194.  
  195.  
  196.  
  197. SHELL VARIABLES
  198.  
  199.  
  200. ...setting:
  201. VAR=this is the value of VAR
  202.  
  203.  
  204. ...using:
  205. echo The value of VAR is $VAR.
  206. cat $HOME/profile
  207.  
  208.  
  209. ...protecting against value changes and deletion:
  210. readonly VAR
  211.  
  212.  
  213. ...exporting into environment for successive programs:
  214. export VAR
  215.  
  216.  
  217. ...listing:
  218. vars
  219.  
  220.  
  221. ...removing:
  222. VAR=""                  (removes value)
  223. VAR=                    (removes variable)
  224. unset VAR               (removes variable)
  225.  
  226.  
  227. Type `ver -l' to find out the maximum number of shell variables.
  228.  
  229.  
  230. Predefined shell variables:
  231.  
  232.  
  233. PS1             The primary shell prompt.
  234. PS2             The secondary shell prompt, used if additional input is
  235.                 required (e.g. when entering shell funktions).
  236. OKAMISHELL      The shell's version number.
  237. TERM            Initially set to "Atari ST" and not yet used any further.
  238. CWD             The current directory, set by the cd command.
  239. HOME            The current directory at the time the shell was started.
  240. ETC             The name of a directory for additional files. Initially
  241.                 set to $HOME.
  242. SHELL           Initially set to $HOME/sh.ttp . Should be changed if the
  243.                 name of the shell program file is changed.
  244. PAGELEN         The number of lines on the screen to be used by the more
  245.                 command. Initially set to 23.
  246. PIPDIR          The name of a writable drive to be used for pipelining
  247.                 etc. Initially set to the same as HOME. Should be set
  248.                 in profile to be on a ramdisk to speed things up.
  249. NULL            The name of a file or device to which output is to be sent
  250.                 which has been redirected to the NULL: device. Initially
  251.                 set to PRN: but can be set to a ramdisk file.
  252.                 NULL is set to u:/dev/null when MiNT is active so it
  253.                 shouldn't be reset then.
  254. PATHSEP         The seperator characters to be used in PATH, XEXT etc.
  255.                 Initially set to ",;", i.e. list entries may be seperated
  256.                 by commas and semicolons. You may include a colon in
  257.                 PATHSEP if you work on the MiNT unified file system (drive U:)
  258.                 only, and seperate list entries with colons (in Unix fashion).
  259. XEXT
  260. SEXT
  261. GEXT
  262. PATH
  263.                 explained above.
  264. CDPATH          A list of directories to be searched by the cd command.
  265. MANPATH         A list of directories to be searched by the man command.
  266. MANEXT          A list of file extenders to be recognized as online-help
  267.                 text files for external commands, used by the man command.
  268. HELPFILE        The name of the online help file for internal commands.
  269.                 Should be set to $HOME/doc/english.doc in profile since
  270.                 the default is $HOME/doc/commands.doc (the german instructions
  271.                 file).
  272. CLIPDIR         Contains the directory and file of the AES scrap directory.
  273.                 Should only be set by the `clipb' command.
  274.  
  275.