





                              Notes on PSL at HP
                                 Cris Perdue
                                 Alan Snyder
                              28 September 1982

1.  Introduction

     This  memo  describes  PSL as it exists at HP, as opposed to the standard
PSL distribution described in the PSL Users Manual.  PSL at  HP  differs  from
standard  PSL  in  a  number  of  significant  ways.  This memo should be read
carefully before trying to run PSL at HP.

     This memo describes the version of PSL installed on Hulk on September 28,
1982.  This version does not yet exist on the Vaxen.

2.  Before Running PSL on HULK or THOR

     In order to run PSL on HULK or THOR, you  must  first  perform  the  EXEC
command:

        @take PSL:LOGICAL-NAMES.CMD

This  command defines a set of logical device names that are necessary for the
proper execution of PSL.  If you intend to use PSL more than once, you  should
include  the  above  command  in your LOGIN.CMD file.  These logical names are
also referred to below and in other PSL documentation; the above command  must
be performed before you can use any of these logical names.

3.  PSL Documentation

     A  printed  copy  of  the preliminary PSL manual can be obtained from Ira
Goldstein's secretary.  There is also a complete online version of this manual
on HULK, organized as a set of files, one per chapter.  These  are  stored  in
files  "PLPT:nnnn-chaptername.LPT".   Please  do  not print your own copies of
these files.  The manual is currently available  on  HEWEY  in  the  directory
~psl/dist/lpt.

     If  you have never used PSL at HP before, the memo "DEC-20 PSL New Users'
Guide" may be helpful.  Copies are available from Ira Goldstein's secretary.

     On HULK there is a set of short HELP files, on  directory  "PH:".   These
help files are generally not very helpful.

     There  is a log of PSL bugs, comments, and inquiries.  See the section on
"PSL Bugs" below.  There is also a file of more substantial  PSL  news  items,
(HULK:)  PSL:NEWS.TXT.    Be  sure  to  read  that file as a companion to this
document.  In addition, there is a file listing  most  changes  made  to  PSL,
(HULK:)  PSL:BUG-FIX.LOG.  This file is updated whenever a change is made to a
PSL system source file; the changes may not actually be installed  until  some
later time.

4.  PSL Bugs

     Send  bug  reports,  inquiries,  and comments via computer mail to "PSL".
This procedure should work on any DEC-20 or VAX in CRC.

     The file (HULK:) PSL:BUGS.TXT contains a log of inquiries, comments,  and
bug reports concerning PSL and its documentation.  The file is kept up to date
and  is  edited  somewhat.    Entries  are in chronological order, most recent
first, so it is easy to find the latest and most wonderful  bugs.    The  file
(HULK:) PSL:BUG-MAIL.TXT contains the unedited accumulation of mail to PSL.

5.  Local PSL -- What's in it

     PSL  at  HP has some modules preloaded on top of the "bare PSL", which is
the minimum set of features now available in a PSL.  Some of these modules are
described in the PSL manual and are part of  the  standard  PSL  distribution;
these   are   preloaded  as  a  convenience  for  users.    Others  are  local
contributions; these are described in greater detail below.

     The following modules described in the PSL manual are loaded as  part  of
"PSL"  at  HP.    We  have  chosen these modules as being most useful for most
people.

   useful         This module provides a variety of useful  features,  many
                  or  all  of  them documented in the PSL manual, including
                  the "extended" FOR loop.  These functions generally  have
                  an  obscure annotation in the manual saying that they are
                  available in the USEFUL library.

   strings        This module defines  all  of  the  string  and  character
                  functions  defined  in  section 8.7 of the manual, except
                  for Char and String,  whose  definitions  there  conflict
                  with definitions specified elsewhere in PSL.

   nstruct        This  module  provides  a "defstruct" facility said to be
                  the same as the one available on the LISP machines.  This
                  is a fancy package that allows the  user  to  define  and
                  make  use  of  record  or structure-like objects in LISP.
                  See the LISP machine documentation for details, but  note
                  that  in  PSL,  colons  should  not  be  used  to  prefix
                  keywords.

   debug          This  module  provides  various  debugging  features   as
                  described  in  the PSL manual.  Most of them are not very
                  high-powered.

   gsort          This module defines some functions for sorting lists  and
                  some predicates useful in sorting.

   common         This  module  defines  some  functions  of "Common LISP".
                  This module is incomplete in many ways: many Common  LISP
                  functions  are  either  not provided or are provided in a
                  limited form.  This module is intended as a compatibility
                  package rather than an extension to PSL.  Common LISP  is
                  a  relative  of  MacLISP, and is described in the "Common
                  LISP Reference Manual",  copies  of  which  are  floating
                  around the Application Technology Department.

     Many  other modules, although mentioned in the PSL manual, are not loaded
in "PSL" at HP.  Most notable of these are RLISP, the Pascal-like  syntax  for
Standard  Lisp,  COMPILER,  the PSL compiler, and EMODE, a screen editor.  See
below for information on compiling PSL programs.  EMODE has been  replaced  by
NMODE, a locally written editor that is described below.

     The following are locally-contributed modules that are preloaded in "PSL"
at   HP.     These  modules  are  not  described  in  the  PSL  Users  Manual.
Unfortunately, as a result, there is no easy way to prevent your programs from
clashing with symbols defined in these modules.  Only the most important  such
modules are listed here.

   nmode          NMODE  is  an  EMACS-like  screen  editor.  It provides a
                  different LISP interface than that described in  the  PSL
                  manual.  See below for more information.

   objects        OBJECTS   is   a   primitive   package   for   supporting
                  object-oriented programming.  It is used  extensively  in
                  NMODE  and  other  HP  contributions.  It supports a very
                  limited subset  of  the  Lisp  Machine  flavors  package.
                  Notably  missing is any support for inheritance.  See the
                  file <AS.PSL>OBJECTS.SL on Hulk for further information.

   input-stream   INPUT-STREAM is a class of objects implemented using  the
                  OBJECTS package that provide for buffered file input.  It
                  is    used    primarily   by   NMODE.    See   the   file
                  <AS.PSL>INPUT-STREAM.SL on Hulk for details.

   output-stream  OUTPUT-STREAM is a class of objects implemented using the
                  OBJECTS package that provide for  buffered  file  output.
                  It   is   used   primarily   by   NMODE.   See  the  file
                  <AS.PSL>OUTPUT-STREAM.SL on Hulk for details.

   pathnames      PATHNAMES is a  compatible  subset  of  the  Common  Lisp
                  pathname  package.    It  provides  a  system-independent
                  interface for manipulating file  names.    See  the  file
                  P20SUP:PATHNAMES.SL   for   information   on  the  DEC-20
                  version, and the "Common Lisp Reference Manual".


6.  NMODE

     NMODE is an EMACS-like screen editor.   It  currently  supports  only  HP
terminals,  and does not support HP262X terminals well.   It supports a useful
subset of the EMACS command interface, although many significant features  are
missing.   A  list  of  the  NMODE commands is attached as an appendix to this
document.  Available documentation on NMODE includes the following memos:  (1)
"NMODE  for  EMODE Users" - a brief description of NMODE written primarily for
those users  already  familiar  with  EMODE.   (2)  "Customizing  NMODE"  -  a
description  of  how to customize NMODE by defining new commands or redefining
existing commands.  These memos are available on the directory PSL: on Hulk.

     NMODE provides a display-oriented Lisp interface  that  is  significantly
different than the "standard" PSL interface described in the PSL Users Manual.
At  HP,  PSL  starts  up  in  NMODE.    However,  it is possible to get to the
"standard" PSL interface simply by executing the command C-] L.    (For  those
not  familiar  with  EMACS,  this  means  to type two characters: "CONTROL-]",
followed by "L".)  From the PSL interface, you can return to NMODE by invoking
the function NMODE (with no arguments), or by RESETing (invoking the  function
RESET  or aborting from a break loop), or reSTARTing (returning to EXEC via ^C
and using the "START" command).

     The proper way to leave NMODE and return to EXEC is to  use  the  command
C-X  C-Z.  While ^C will get you back to EXEC, it may leave your terminal in a
funny state.  Using C-X C-Z allows NMODE  to  restore  your  terminal  to  the
proper state before returning control to the EXEC.

     NMODE's  display-oriented  Lisp interface is based on the idea of reading
from and writing to NMODE text buffers.  The NMODE command "Lisp-E" (which  is
typed  as  C-]  E)  causes  PSL  to read and evaluate the form starting on the
current line of the current buffer.  The output resulting from that evaluation
is appended to the buffer named "OUTPUT" (which is the current buffer when PSL
starts up).

     If the evaluation of a Lisp form causes an error, a Break Handler will be
entered.  Terminal input will continue to be directed to NMODE, and NMODE  can
still  be used as an editor while the Break Handler is active.  NMODE provides
a number of special commands for interacting with an active Break handler: The
command "Lisp-Q" (typed as C-] Q) quits out of the  innermost  break  handler.
The command "Lisp-A" (typed as C-] A) aborts all the way back to the top level
and restarts NMODE.  The command "Lisp-R" attempts to retry the failing action
that  caused  the  error  (which  must be a "continuable" error).  The command
"Lisp-C" is similar, except that rather than reevaluating the "errorform",  it
uses  the result of the last expression evaluated using "Lisp-E".  The command
"Lisp-B" prints a backtrace.  The "Lisp-" commands are available only in  LISP
mode.  To enter Lisp mode, use the command "M-X Lisp Mode".

7.  Compiling PSL

     As  mentioned above, the PSL compiler is not normally loaded in PSL.  The
recommended way to compile  PSL  programs  is  to  use  the  program  PSLCOMP.
PSLCOMP  compiles  a  PSL  source  file  (e.g. "foo.sl") and produces a binary
object file (e.g. "foo.b").  PSLCOMP is invoked by the EXEC command

        @PSLCOMP foo
or      @PSLCOMP foo.sl

PSLCOMP may be given multiple source file names (separated by spaces) and will
produce a separate binary file for each source file; however, this practice is
dangerous because the "compilation context" created for one source  file  will
remain and may affect the compilation of a later source file.

     The  object  file "foo.b" created by PSLCOMP may be loaded into PSL using
either LOAD or FASLIN, as follows:

        (LOAD FOO)
        (FASLIN "FOO.B")

The difference between LOAD and FASLIN is that LOAD will  not  reload  a  file
that has already been loaded.

     If you use any non-standard macros, fexprs, or nexprs that are defined in
other  files,  you must cause definitions of those functions to be loaded into
PSLCOMP when it compiles your source file.  The way to do this is to include a
statement of the form

        (CompileTime (load Module1 Module2 ... ))

at the beginning of  your  source  file,  where  Module1,  Module2,  ...   are
LOADable  modules  that  define  the  macros,  etc.  that you use.  PSLCOMP is
preloaded with  the  following  modules:  COMMON,  USEFUL,  STRINGS,  OBJECTS,
PATHNAMES, NSTRUCT.

8.  PSL Directories and Subdirectories -- HULK

     HULK  has  a  complete  set of source files, command files, object files,
etc.  THOR currently does not, and  has  only  a  single  directory  for  PSL.
Status  of PSL directories and subdirectories on HEWEY is subject to change at
any time, so it isn't discussed here.

     Sources  on  Hulk  reside  in  SS:<PSL>  and  its  subdirectories.    The
subdirectories  of  SS:<PSL>  are  organized  in  a logical fashion.  The file
"PSL:-THIS-.DIRECTORY" contains short descriptions of the  files  in  SS:<PSL>
and the subdirectories of SS:<PSL>.  To see the complete set of subdirectories
of  SS:<PSL>,  type  "DSKUSE SS:<PSL*>" to EXEC.  Note that the source code is
kept separate from the object code, which is all on PL:.

8.1  TAGS -- Finding the Definitions of PSL System Functions

     The EMACS editor has a feature that is of great help  in  finding  source
code,  the TAGS package.  To use this package, first load a "tag table", which
is a database that records what source file definitions appear in.    One  tag
table  can  hold  definitions  that appear in many different source files.  We
have a very large tag table for all of PSL,  which  is  in  the  file  (HULK:)
PSL:PSL.TAGS.

     To  load a tag table file, do "M-X Visit Tag Table" in EMACS and give the
file name as an argument.  Once a file is  loaded,  search  for  a  definition
using  "M-.".    You  may  wish  to set the EMACS variable Tags Find File to 1
before searching for definitions.  Note also that tag table files  may  become
somewhat out of date.  Do not expect perfection.

     The  program  TAGS  is  used to create tag table files.  The version that
handles PSL (and RLISP) syntax, as well as understanding the  file  types  .SL
and  .RED  is  PSL:TAGS.EXE.    The  system  version  of  TAGS  may eventually
understand these things.

     Full information on the EMACS TAGS package is only available in the EMACS
manual and through the INFO facility.   Do  not  bother  the  PSL  group  with
questions   and   complaints   about   TAGS  until  you  have  read  the  full
documentation.  We will not improve the TAGS package itself in any case.