.c	Wednesday  Nov 30,1983  4:54  LQ+2D.23H.1M.45S.  -*- Bolio -*-

.chapter "Introduction"

lan{Nil}, which stands for New Implementation of Lisp, is a dialect
of lan{lisp} which runs on the lan{dec} lan{vax}.  lan{Nil}
currently runs under the lan{vms} operating system.  It will likely
be converted to run under lan{unix} (TM) at some point, but there is
no effort underway to do so right now.

lan{Nil} is a dialect of lan{common lisp}.  lan{Common lisp} is
essentially a formal specification of the lan{lisp} language such
that programs which conform to that specification may be transported
without modification from one lan{common lisp} implementation to
another, and be expected to run compatibly.  As of this writing, the
lan{common lisp} manual has just gone to press;  this manual has
therefore developed into documentation of a subset of lan{common
lisp} facilities which are currently supported by lan{nil}, and a
large number of lan{nil}-specific things.

This document schizophrenically attempts to cover
three areas.  One is "primer" documentation;  those things which must
be known for any programming to get done.  In this case, attempts are
made to point out what of these things are lan{common lisp}
compatible.  Another is the set of things which might be expected to
change incompatibly, 2due* to lan{common lisp} conversion.  The
third is those which are part of the lan{nil} core
term_i{Virtual Machine}, as it is being developed more formally.
These include, for example, functions like fun{%string-replace},
which are suitable low-level primitives for a lan{vax} (or other
byte-machine, like perhaps an lan{ibm-370}) to provide.
Lastly,
there are certain parts of lan{nil} which have undergone large
amounts of recent development, and are fairly stable, and which may
provide functionality for users in various domains;  the I/O system,
for example.  Much of the provided documentation will be of things
which are obscenely low-level;  sometimes, this is to point out places
where the implementation falls short of the design;  often too, to
document these for those who may find it useful debugging, or in
performing implementation-dependent activities;  and occasionally, to
explicitly note how the implementation differs from the general and
portable semantics (as in the case of numbers and fun{eq}).

Because the lan{common lisp} manual is finally available, this will
probably be the last lan{nil} manual in this format.  In the future,
complete documentation on lan{nil} will be provided by three
separate documents:  the lan{common lisp} manual, a document
describing the extensions beyond lan{common lisp} which lan{nil}
provides, and a document on lan{nil} internals and data structures
(somewhat similar in spirit to the 2VAX/VMS Internals and Data
Structures* document published by DEC).


.section "Conventions"

All otherwise unqualified rational numbers in this manual are in
2decimal*, not 2octal* (as has been the practice in certain
other manuals, notably ref{Moonual} and ref{LMMan}).  Special
qualifying syntax for forcing the interpretation of rational numbers
in other radices is described in (number-types-section-page).

There are a couple conventions for the forming names of functions and
variables coming into use from within the lan{common lisp}
community.

Generally, variables whose values are 3special* and which may be
modified during the course of program operation have names which begin
and end with an asterisk;  for instance, 3*package**.  Lexical
variables, and constants defined with 3defconstant*
((defconstant-fun)), are normally named without these asterisks.
For instance, lan{nil} defines the constants 3pi* and
3most-positive-double-float*.  This is a convention only and does
not affect the operation of the lan{nil} interpreter or compiler,
the sole exception being that the compiler uses the presence of a
leading asterisk to choose a course of action when it encounters a free
reference to an undeclared variable.
(Special and lexical variable reference is discussed in
(scope-extent-and-binding-section-page).)

The names of predicate functions in lan{nil} and lan{common lisp}
are typically formed by suffixing the character "p" to the end of a
descriptive name.  For instance, 3consp* is a predicate which is
true if its argument is a cons, and 3lessp* (which actually is a
lan{maclisp}, not lan{common lisp}, function) compares numbers and
(when given two arguments) returns 3t* if the first is less than
the second.  If the name itself is hyphenated, then "-p" is suffixed:
3upper-case-p* is a predicate which tells if a character is
upper-case.  If, however, the predicate name is formed by prefixing a
specializing name to an existing predicate name, then the final "p"
would not have hyphenation added to it:  3string-lessp* is a
predicate can be used to compare strings using a standard collating
sequence, the name being formed by prefixing "string-" to "lessp".
There are, of course, many exceptions to this, and this convention
does not eliminate all ambiguity, but it helps.  A good number of
lan{nil} functions did not follow this convention in earlier
versions of lan{nil};  many of these have been fixed, and the old
names made synonymous with the new names for the time being.
