This manual is organized into three kinds of units: chapters, sections, and entries. It has a modular structure intended to make it easy to find what you're looking for and to know when you are done reading about various topics.

Chapters frequently begin with some introductory text about what's in the chapter, followed by any necessary concept information, followed by the main entries and sometimes by some sample code using the ideas brought out in the chapter.

Sections are much the same, but are usually smaller groups.

Entries can best be described by an example:

Entry type	Meaning
Array	A pre-defined ARRAY.
Concept	Conceptual information you might find handy.
Formatop	A notation useful in with the FORMAT function.
Function	A pre-defined SUBR or LSUBR. See APPLY or FUNCALL.
Property	A property name with pre-defined significance.
Reader Macro	A pre-defined reader macro. See SETSYNTAX.
Sfamsg	An SFA message sent to implement a pre-defined behavior. See SFA-CALL.
Special Form	A pre-defined FSUBR. See APPLY.
SStatus Option	A name useful with the SSTATUS operator.
Status Option	A name useful with the STATUS operator.
Struct Option	A name useful with the DEFSTRUCT operator.
Style Note	Style information you might (or might not) find useful.
Value	A pre-defined variable. See SYMEVAL.

;; hi. i'm an example of code
(setq x '(hi there))
=> (HI THERE)

(car x)
=> HI

(+ 3 4)		=> 7

(zerop 17)	=> NIL

The documentation in this draft is most accurate for ITS since that's where Maclisp was designed and where it runs best. It is probably fairly good about noting operating-system dependencies. Most places that are ITS-specific are noted. Many differences between ITS and Tops-20 Maclisp are explicitly flagged, but there are probably some omissions. Where possible, differences between Multics Maclisp and PDP-10 Maclisp (the collective term for ITS and Tops-20 Maclisp) are flagged as well. Some work has been done in this draft to make the documentation for Multics Maclisp more accurate, but still some things may have been missed so beware.

This manual documents Maclisp both past and present. This is intended to help bring code out of the dark ages since most people have been a long time without a manual. Some things are marked as “obsolete” or “archaic”. These terms have well-defined meanings in this manual. “Obsolete” means “no longer existing” while “archaic” means “still existing, but something which is on the road to obsolescence.

(%include libname)

(%include library)

On ITS, LISP may be entered by the “:lisp” or “lisp^K” command. On Multics and Tops-20, just “lisp” is sufficient.

Note that case is not significant on ITS and Twenex either when invoking Lisp or when writing Lisp code. However, Multics is case sensitive in both situations and lowercase is required when invoking lisp and when using any of the terms in this manual. The convention in this manual is to use uppercase for code because it stands out better, but Multics users should remember to type all system names in lowercase.

The environment set up by this command is the standard initial environment. Lisp first checks for an init file. On ITS, the file is named "homedir;username LISP". On Tops-20, the file is named "<homedir>LISP.INI". On Multics, the file is named "[hd]>start_up.lisp".

Users should be aware that Lisp's default base is 8, so results in a bare Lisp such as (+ 5 5) evaluating to 12 is not a bug, it's just base 8 in effect. To change this behavior, the variables BASE, IBASE, and *NOPOINT may need to be assigned. For example, many users like to make init files which set these variables. The variables BASE, IBASE, *NOPOINT, PRINLEVEL and PRINLENGTH are the most commonly assigned in init files.

The following init file is recommended for novices:

Typically the user will want to wrap a PROGN around all the forms in his init file after the initial comment (as shown above) so that the results of each intermediate computation is not displayed on the console. The final return value in our example, the asterisk, will then be the only value typed out during the loading of that init file.

If an init file is found, it is read in, evaluating each form as it is read and printing the result on the terminal. This allows the user to customize his Lisp environment. Except on Multics, the init file must have a COMMENT statement at the beginning of it which can contain magic values pertaining to initial data storage layouts for Lisp. For novices, (COMMENT) will work just fine. The only reason this is mentioned here at all is that if an init file exists but the first s-expression in that file is not a COMMENT form, a fatal error will result.

For sophisticated users, the full format of the comment is:

For details of space allocation information, see documentation on ALLOC. Note however that a spacename must be a symbol and a size must be a fixnum in octal. On Multics, none of this is necessary; any initial comment in the init file is simply ignored.

If there is no init file, Lisp types out “ALLOC?” and awaits direction from the user. Novice users (and most experienced users) will want to just type “N” or a space to this, indicating that they don't wish to interactively set the space allocations. For those who do need to set space sizes, typing “?” offers some help and “Y” enters the interactive allocation routine. On Multics, initial allocation information isn't needed, so the “ALLOC?” question is not asked.

In most operating systems, lisp can be provided with jcl (job command line), the text which follows the word Lisp on the command line that starts an invocation of the lisp program. On ITS, JCL is supplied by an interaction like:

On Tops-20, it would look like:

If Lisp gets jcl, it expects that jcl to specify an init file which will be used instead of the default init. It is an error if jcl was supplied specifying an init and the init file does not exist. On Multics, the command line has a different meaning which is not relevant to this section; for more information see documentation for (STATUS JCL).

If no init was loaded, an asterisk will be typed out to indicate that Lisp is ready and awaiting input in its read-eval-print loop. If an init was loaded, each value returned by an expression in the init file (except that of the initial comment) will be printed on the terminal. When all return values for all forms in the init have been typed out, Lisp will await input from the terminal.

None of this behavior applies to suspended Lisp jobs which have been used for a while and had their state saved in order to make a more complex TS file (ITS) or .EXE file (Tops-20). See documentation on SUSPEND for information about such behavior.