HELP CLISP                                      John Williams, July 1985
                                                       Revised June 1995

Poplog contains compilers for four AI programming languages: Pop-11,
Prolog, Common Lisp, and Standard ML. A full specification of Common
Lisp can be found in Guy Steele's book: Common Lisp: The Language, 2nd
Edition (Digital Press, 1990). This file provides a basic introduction
to using the Poplog Common Lisp subsystem.


         CONTENTS - (Use <ENTER> g to access required sections)

  1   Invoking Poplog Common Lisp
  2   The Top-Level Loop
  3   Interrupts & Errors
  4   The Ved Editor
  5   Online documentation
  6   Internet Resources
  7   See Also


-----------------------------------------------------------------------
1  Invoking Poplog Common Lisp
-----------------------------------------------------------------------

On Unix Poplog systems, first get to the shell, and then type:

    % clisp

On VMS systems, go to DCL, and type:

    $ clisp

The "c" in "clisp" stands for "Common"! After a short pause, Lisp will
announce its presence by printing a message. It is then ready to accept
commands:

    Sussex Poplog (Version 14.53 Tue May 30 16:17:17 BST 1995)
    Common Lisp (Version 1.6)

    Setlisp
    ==

"Setlisp" is printed whenever the Lisp system is "reset" - on start-up
or after aborting from an error. The double-equal sign, "==", is the
Lisp prompt. It indicates that Lisp is waiting for input from the
terminal.

When Lisp is invoked in this way, it looks for two initialisation files:
init.p and init.lsp. If present, they are compiled. The former should
contain Pop-11 code, and the latter Lisp code. This facility allows you
to define utilities that extend your private Poplog Lisp environment.
See HELP * INITIAL for full details.


-----------------------------------------------------------------------
2  The Top-Level Loop
-----------------------------------------------------------------------

Once Lisp is invoked, it goes into a top-level loop. This is a process
which repeatedly waits for a Lisp expression to be typed in, evaluates
it, and then prints the result. For example:

    Setlisp
    == (+ 2 3 4)
    9
    == (cons 'lisp '(is a nice language))
    (LISP IS A NICE LANGUAGE)
    == (position-if #'numberp '(my cat is 5 years old))
    3
    == (map 'string #'char-downcase "THIS IS A STRING")
    this is a string

Notice that words (or symbols to be precise) typed in lowercase are
printed in capital letters. This is because the Lisp reader (the program
responsible for parsing input) converts lowercase letters into uppercase
when reading a symbol. If you prefer lowercase output, assign the
keyword :downcase to the variable *print-case*. Thus:

    == (setq *print-case* :downcase)
    :downcase
    == (append '(lowercase is much) '(easier on the eyes))
    (lowercase is much easier on the eyes)


To leave the top-level loop, type:

    == (bye)

Typing end-of-file (<CTRL> d on Unix machines; <CTRL> z on VMS) has the
same effect.


-----------------------------------------------------------------------
3  Interrupts & Errors
-----------------------------------------------------------------------

If you interrupt execution of a Lisp program, by typing <CTRL> c, Lisp
enters a break. This is essentially a new top-level loop: it evaluates
and prints the values of Lisp expressions as they are typed in. However,
certain top-level forms are recognised specially and interpreted as
debugging commands. A break is also entered after an error. The file
HELP * BREAK provides full details of the break facility. HELP * MISHAP
explains the format of Lisp error messages.


-----------------------------------------------------------------------
4  The Ved Editor
-----------------------------------------------------------------------

To get into Ved from the Lisp top-level loop, type ved followed by the
name of the file you wish to edit. For example:

    == ved myfile.lsp

For more details on using the Ved editor for writing and testing Lisp
programs, see HELP * LISPVED.


-----------------------------------------------------------------------
5  Online documentation
-----------------------------------------------------------------------

The Poplog Common Lisp online documentation comprises two sets of files:
the HELP files, and the REF files. The HELP files constitute a Common
Lisp user guide: they describe Poplog specific features such as the
format of error messages, or how to use the Lisp debugger. The REF files
form an online reference manual; they contain brief descriptions of all
the core Common Lisp language constructs (i.e. those described in
Steele). Each REF file corresponds to a chapter of Steele's book.

HELP and REF files are accessed in a similar manner to Ved files. For
example

    == help news
    == ref lists

If the argument to the REF command is a function or variable described
by Steele, then the appropriate REF file entry is located and displayed
automatically. Try typing the following to Ved:

    <ENTER> ref dolist <RETURN>

The file REF CONTROL should appear, with the cursor at the description
of the macro DOLIST.

HELP * HELPFILES and REF * REFFILES provide general overviews of the
HELP and REF files respectively. HELP * LISPINDEX and REF * LISPINDEX
provide alphabetically sorted indexes of the HELP and REF files.


-----------------------------------------------------------------------
6  Internet Resources
-----------------------------------------------------------------------

There are many interesting and useful Lisp resources available on the
Internet. Good starting points are:

 # The Association of Lisp Users
    http://www.cs.rochester.edu/u/miller/ALU/home.html

 # Common Lisp the Language, Second Edition
    http://www.math.uio.no/cltl/clm/node1.html

 # CMU Lisp Repository
    http://www.cs.cmu.edu/afs/cs.cmu.edu/project/ai-repository/ai/lang/lisp/0.html

 # Lisp `News' Group
    news:comp.lang.lisp

 # Poplog `News' Group
    news:comp.lang.pop

 # Draft ANSI standard for Common Lisp
    ftp://parcftp.xerox.com/pub/cl/dpANS2/


-----------------------------------------------------------------------
7  See Also
-----------------------------------------------------------------------

    HELP * BREAK                    - The Lisp Debugger
    HELP * BUGS                     - Known Bugs and Omissions
    HELP * LISPVED                  - Using the Ved editor with Lisp
    HELP * MISHAP                   - Error Message format

    HELP * HELPFILES                - Overview of Lisp HELP files
    HELP * LISPINDEX                - Index

    REF * LISPINDEX                 - Overview of Lisp REF files
    REF * REFFILES                  - Index


--- C.all/lisp/help/clisp
--- Copyright University of Sussex 1996. All rights reserved.
