X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/cac85e0be5833902081c903f75e348b949294fb9..db6c3279edc260e3e301df1c9b082b374cd002c7:/doc/lispintro.tex

diff --git a/doc/lispintro.tex b/doc/lispintro.tex
index dc1cab1..c628a2c 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}
 
@@ -159,8 +183,8 @@ category (function, class, macro, etc.) on the right.
 
 \begin{describe}{mac}
     {example-macro
-        (@{ @<symbol> @! (@<symbol> @<form>) @}^*) \\ \ind
-      @[[ @<declaration>^* @! @<doc-string> @]] \\
+        (@{ @<symbol> @! (@<symbol> @<form>) @}^*)              \\ \ind
+      @[[ @<declaration>^* @! @<doc-string> @]]                 \\
       @<form>^*
      \nlret @<value>^*}
   The synopsis for a macro describes the acceptable syntax using the
