X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/1818107e8198734df843841a51bca3713bd37596..d5fdd49e70b734b791eb907706f92da5775e2a8b:/doc/lispintro.tex

diff --git a/doc/lispintro.tex b/doc/lispintro.tex
index 5f1043f..9497164 100644
--- a/doc/lispintro.tex
+++ b/doc/lispintro.tex
@@ -69,6 +69,9 @@ particular circumstance is erroneous and results in unspecified and possibly
 incorrect behaviour.  In particular, the situation need not be immediately
 diagnosed, and the consequences may be far-reaching.
 
+A \emph{specified} function, variable, symbol, class, type, macro, or other
+item is one documented in this specification.
+
 The following conventions apply throughout this specification.
 
 \begin{itemize}
@@ -77,11 +80,35 @@ The following conventions apply throughout this specification.
   syntax, then it is an error to provide an argument not having that
   particular type or syntax.
 
-\item If a specification describes a function then that function might be
-  implemented as a generic function; it is an error to attempt to (re)define
+\item A specified function may, e.g., in a later version, accept additional
+  optional and/or keyword arguments.  A specified macro may be extended to
+  accept syntax other than that documented in this specification, e.g., to
+  add additional optional arguments.
+
+\item If a specified function or macro is described as returning the values
+  returned by some user-supplied function or form, then it will do precisely
+  that, and there are no restrictions on which or how many values such a
+  user-supplied function or form may return.  Other specified functions or
+  macros may return additional values beyond those described (so it is likely
+  an error to invoke them in forms such as @|multiple-value-list| or
+  @|multiple-value-call|).  It is an error for a user-supplied function or
+  form not to return the documented number and types of values.
+
+\item The \emph{specified packages} are the @|SOD| package, and all packages
+  whose names begin @|SOD-|.  The specified packages are reserved for the Sod
+  translator.  It is an error to define or alter specified packages (e.g., to
+  export additional symbols from them, import symbols into them, shadow
+  symbols in them, or modify their `use' lists), to refer to internal symbols
+  in specified packages, or to define functions or macros, or proclaim
+  @|special| variables, whose names are exported by specified packages.  If a
+  symbol exported from a specified package has a name beginning and ending
+  with @|*| or @|+|, then it is an error to use it as a lexical variable.
+
+\item A specified function might be implemented as a generic function even if
+  it is not documented as being one; it is an error to attempt to (re)define
   it as a generic function, or to attempt to add methods to it.  A function
   specified as being a generic function will certainly be so; if user methods
-  are permitted on the generic function then this will be specified.
+  are permitted on the generic function then this will be documented.
 
 \item Where a class precedence list is specified, either explicitly or
   implicitly by a class hierarchy, the implementation may include additional
@@ -99,27 +126,24 @@ The following conventions apply throughout this specification.
 
 \item An object $o$ is a \emph{direct instance} of a class $c$ if @|(eq
   (class-of $o$) $c$)|; $o$ is an \emph{instance} of $c$ if it is a direct
-  instance of any subclass of $c$.
-
-\item If a class is specified as being \emph{abstract} then it is an error to
-  construct direct instances of it, e.g., using @|make-instance|.
+  instance of any subclass of $c$.  If a class is specified as being
+  \emph{abstract} then it is an error to construct direct instances of it,
+  e.g., using @|make-instance|.
 
 \item If an object is specified as being \emph{immutable} then it is an error
-  to mutate it, e.g., using @|(setf (slot-value \ldots) \ldots)|.  Programs
-  may rely on immutable objects retaining their state.
+  to mutate it, e.g., using @|(setf (slot-value \ldots) \ldots)|.  User
+  programs may rely on immutable objects retaining their state.
 
 \item A value is \emph{fresh} if it is guaranteed to be not @|eql| to any
   previously existing value.  A list is \emph{fresh} if it is guaranteed that
   none of the cons cells in its main cdr chain (i.e., the list head, its cdr,
-  and so on) are @|eql| to any previously existing value.
-
-\item Unless otherwise specified, it is an error to mutate any part of value
-  passed as an argument to, or a non-fresh part of a value returned by, a
-  function specified in this document.
+  and so on) are @|eql| to any previously existing value.  Unless otherwise
+  specified, it is an error to mutate any part of value passed as an argument
+  to, or a non-fresh part of a value returned by, a specified function.
 
 \item Unless otherwise specified, it is an error to change the class of an
-  instance of any class described here; and it is an error to change the
-  class of an object to a class described here.
+  instance of any specified class; and it is an error to change the class of
+  an object to a specified class.
 
 \end{itemize}
 
@@ -129,7 +153,7 @@ Most symbols defined by the protocol have their own entries.  An entry begins
 with a header line, showing a synopsis of the symbol on the left, and the
 category (function, class, macro, etc.) on the right.
 
-\begin{describe}{fun}{example-function @<required>
+\begin{describe*}{\dhead*{fun}{example-function @<required>}
     \&optional @<optional>
     \&rest @<rest>
     \&key :keyword
@@ -155,13 +179,15 @@ category (function, class, macro, etc.) on the right.
     some-generic-function ((@<specialized> list) @<unspecialized>)
       @> @<result>
   \end{quote}
-\end{describe}
-
-\begin{describe}{mac}{example-macro
-  ( @{ @<symbol> @! (@<symbol> @<form>) @}^* ) \\ \ind
-    @[[ @<declaration>^* @! @<documentation-string> @]] \\
-    @<body-form>^*
-      \nlret @<value>^*}
+\end{describe*}
+
+\begin{describe*}
+    {\dhead*{mac}
+      {example-macro
+          (@{ @<symbol> @! (@<symbol> @<form>) @}^*)            \\ \ind
+        @[[ @<declaration>^* @! @<doc-string> @]]               \\
+        @<form>^*
+       \nlret @<value>^*}}
   The synopsis for a macro describes the acceptable syntax using the
   following notation.
   \begin{itemize}
@@ -184,10 +210,11 @@ category (function, class, macro, etc.) on the right.
   \end{itemize}
   For example, the notation at the head of this example describes syntax
   for @|let|.
-\end{describe}
+\end{describe*}
 
-\begin{describe}{cls}{example-class (direct-super other-direct-super) \&key
-    :initarg}
+\begin{describe*}
+    {\dhead*{cls}{example-class (direct-super other-direct-super)
+                   \&key :initarg}}
   The synopsis for a class lists the class's direct superclasses, and the
   acceptable initargs in the form of a lambda-list.  The initargs may be
   passed to @|make-instance| when constructing an instance of the class or a
@@ -196,7 +223,7 @@ category (function, class, macro, etc.) on the right.
   may also be passed to @|reinitialize-instance| and/or @|change-class| as
   applicable; the class description will state explicitly when these
   operations are allowed.
-\end{describe}
+\end{describe*}
 
 %%%----- That's all, folks --------------------------------------------------