home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / os / psh_1 / psh / manpage < prev    next >
Text File  |  1995-05-08  |  10KB  |  236 lines
  1.  
  2.  
  3.  
  4. PSH(1)                      PSH(1)
  5.  
  6.  
  7. NNAAMMEE
  8.        psh - the Penguin shell ;-)
  9.  
  10. SSYYNNOOPPSSIISS
  11.        ppsshh  [-c command | file]
  12.  
  13. DDEESSCCRRIIPPTTIIOONN
  14.        This manual page  documents psh,  a very simple bash-like 
  15.        shell written to run under RISC OS. 
  16.  
  17.        The main  purpose of psh was to add GNU  readline editing
  18.        facilities to  the  RISC OS CLI and  to  provide  a shell 
  19.        which  could be  executed  usefully from vim. (Originally
  20.        :sh from inside vim  would call GOS.  But GOS exits after
  21.        an application is run, so things like e.g. ls would cause
  22.        it to exit). 
  23.  
  24. BBUUIILLTTIINNSS
  25.  
  26.        psh supplies a number of builtin  commands and facilities
  27.        to make  things look  more like Unix.  These  will now be 
  28.        described:
  29.  
  30.             .          Execute commands from a file.
  31.                        This is the analogue of "source" under
  32.                        csh if that's your preferred shell.
  33.  
  34.             autoconv   Add a command name for uname conversion.
  35.                        psh was compiled under UnixLib. This
  36.                        means that it prefers to use Unix style
  37.                        filenames (e.g. $.bin = /bin). Such names
  38.                        are not translated by the shell by
  39.                        default. This is because many other
  40.                        UnixLib programs exist out there and
  41.                        these also prefer Unix filenames.
  42.  
  43.                        However there are a lot of programs which
  44.                        *don't* understand Unix filenames.
  45.                        autoconv supplies a method to allow
  46.                        automatic conversion for these programs.
  47.                        It specifies a command name which should
  48.                        have automatic Unix name argument
  49.                        conversion whenever it is run.
  50.  
  51.                        For example:
  52.                          autoconv rename
  53.  
  54.                        From now on, an operation of the form
  55.                          rename /bin/ls /bin/ls-old
  56.  
  57.                        will automatically get translated to 
  58.                          rename $.bin.ls $.bin.ls-old
  59.  
  60.                        (Read the UnixLib manual for full details
  61.                        of filename translation).
  62.  
  63.                        autoconv uses exact text matching, so
  64.                        "Rename" will be unaffected, as would
  65.                        *rename. This allows the autoconv
  66.                        operation to be avoided when necessary.
  67.  
  68.             bye        Same as exit.
  69.  
  70.             cd         Change directory, using CDPATH.
  71.  
  72.                        CDPATH is an environment variable
  73.                        containing a list of directories which
  74.                        can be searched by the cd command. If a
  75.                        command of the form "cd fred" is issued,
  76.                        cd first looks in the current directory
  77.                        for one called fred. If this is not found
  78.                        then the directories listed in CDPATH are
  79.                        searched. A match in any of these
  80.                        directories will cause a directory change
  81.                        to the appropriate place.
  82.  
  83.             dirs       Show the directory stack.
  84.                        (see pushd).
  85.  
  86.             exec       Replace this shell with a command.
  87.                        The specified command is run and the
  88.                        current copy of the shell exits.
  89.                        e.g. exec "ls -l"
  90.  
  91.             exit       Same as bye.
  92.  
  93.             help       Show help on a command.
  94.                        This gives a one-line help message for
  95.                        each builtin command. Note that this
  96.                        overloads the RISC OS help command - to
  97.                        get to this, use *help.
  98.                        
  99.             history    Show the history list.
  100.                        Each command executed gets placed in the
  101.                        shell's history list. The history command
  102.                        can be used to examine the list. The list
  103.                        can be navigated using csh style !
  104.                        expansions or using the arrow keys (see
  105.                        the manuals for GNU readline and history
  106.                        libraries for full details).
  107.                        
  108.             popd       Pop a directory from the stack.
  109.                        (see pushd).
  110.  
  111.             pushd      Push a directory onto the stack
  112.                        pushd, popd and dirs are used to maintain
  113.                        a stack of directories. The action of
  114.                        pushd is similar to cd in that it changes
  115.                        directory. However, before doing so it
  116.                        records the current directory in a stack.
  117.                        A subsequent popd command can then be
  118.                        used to change back to the most recently
  119.                        pushed directory. The dirs command will
  120.                        list which directories are currently on
  121.                        the stack.
  122.  
  123.                        psh has an additional facility over that
  124.                        of Unix shells. It uses the RISC OS
  125.                        "previously selected directory", "\". If
  126.                        the directory stack is empty and popd is
  127.                        issued then the PSD is selected. I find
  128.                        this useful for swapping between two
  129.                        directories without having to remember to
  130.                        do pushd.
  131.  
  132.                        e.g.
  133.                        penguin: /home $ cd /bin
  134.                        penguin: /bin $ dirs
  135.                        \
  136.                        penguin: /bin $ popd
  137.                        penguin: /home $ 
  138.  
  139.             pwd        Show the current directory.
  140.  
  141.             read       Read a line into a variable.
  142.                        This stores a line read from the keyboard
  143.                        into a RISC OS system variable. 
  144.  
  145.             source     Execute commands from a file
  146.                        (See ".")
  147.  
  148.        As mentioned above,  psh supplies a  command line history
  149.        and GNU  readline editing.  Both the history and readline
  150.        functions are best introduced by the relevant GNU manuals
  151.        (available  from all  good  ftp sites!). The  default psh
  152.        configuration is exactly the same as the default readline
  153.        except for the following changes:
  154.  
  155.        1) Customisation  filename: Under  Unix  readline this is
  156.           .inputrc RISC OS filename limitations require  this to
  157.           be /inputrc instead.
  158.  
  159.        2) The  standard readline  functions have been  augmented
  160.           with an extra one for Unix to RISC OS name conversion.
  161.           This function,  mapped to Meta-k by default, takes the
  162.           Unix filename  under the cursor and  maps it to a RISC 
  163.           OS name.  This is useful when  a command is not in the
  164.           autoconv list and completion has been used to generate
  165.           its arguments.
  166.  
  167.           The function name is "riscos-name" and its mapping can
  168.           be changed in the /inputrc file if necessary.
  169.  
  170.        3) Meta-K is mapped to "cursor-edit-on". This enables the
  171.           standard  RISC OS cursor  editing  operations  for the
  172.           duration  of   the  current  line.   A   corresponding
  173.           "cursor-edit-off" command is mapped by Meta-Meta.
  174.  
  175. FFIILLEESS
  176.  
  177.        psh uses several  files for startup (note that  filenames
  178.        listed in this section are RISC OS filenames).
  179.  
  180.        &./inputrc
  181.        As mentioned above,  this is actually a  readline startup
  182.        file. Its contents are documented in the readline manual.
  183.        (This facility has not been tested!)
  184.  
  185.        &./history
  186.        This  contains  a  saved  command  history  file  from  a
  187.        previous shell session.  It is read when the shell starts
  188.        and written when it finishes.
  189.  
  190.        &./shrc
  191.        This contains a list of commands which are to be run when
  192.        the  shell  starts.  This is  useful to  store a  list of
  193.        autoconv  commands  and set the prompt and CDPATH values,
  194.        for instance.
  195.  
  196.        $.etc.shrc
  197.        (Actually whatever /etc/shrc maps to under UnixLib)
  198.        This is a global shrc which is sources by every user when
  199.        the shell starts.
  200.  
  201. BBUUGGSS
  202.  
  203.        There are no bugs. This program is perfect.
  204.  
  205.        Hmmm, believe that and you'll believe anything.  Here are
  206.        the ones that I've found so far:
  207.  
  208.        Command  completion  on files like  fred/tar fails (press
  209.        tab twice to get a list  of  matches and  it will display
  210.        "tar"  rather  than  "fred/tar".  The  reason for this is
  211.        simple - readline does not expect to find / in filenames.
  212.        I suspect this would take a lot of hacking of readline to
  213.        fix.
  214.  
  215.        Command  completion *is* case sensitive,  even though the 
  216.        filesystem isn't! So m<tab> will not match Makefile.
  217.  
  218.        Autoconv  sometimes allows two copies of the same command
  219.        to  enter  the  list.  I don't  know  why  this is but it
  220.        doesn't seem to cause any problems! Also it would be nice
  221.        to have a "noautoconv" command. It would  also be nice to
  222.        have  some  way of  specifying which  arguments should be
  223.        subject  to conversion  so that  e.g. regular expressions
  224.        don't get splatted!
  225.  
  226.        No scripting language is supplied. No way!
  227.  
  228.        All  but  the  builtin  commands  are  merely  chucked at
  229.        system()  and  RISC OS takes  over  from there.  This may
  230.        cause  problems  with some  things. Redirection does  not
  231.        work for builtins.
  232.  
  233.        Please  report any more to Alun Jones, auj@aber.ac.uk and 
  234.        I will try to fix them - no promises though!
  235.  
  236.