debian/changelog: Prepare for next version.

[sod] / doc / lispintro.tex

diff --git a/doc/lispintro.tex b/doc/lispintro.tex
index dc1cab1..9497164 100644 (file)
--- 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.
 
 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}
 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.
 
   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
   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
 
 \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
 
 \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
 
 \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,
 
 \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
 
 \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}
 
 
 \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.
 
 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
     \&optional @<optional>
     \&rest @<rest>
     \&key :keyword


@@ -155,14 +179,15 @@ category (function, class, macro, etc.) on the right.
     some-generic-function ((@<specialized> list) @<unspecialized>)
       @> @<result>
   \end{quote}
     some-generic-function ((@<specialized> list) @<unspecialized>)
       @> @<result>
   \end{quote}

-\end{describe}
-
-\begin{describe}{mac}
-    {example-macro
-        (@{ @<symbol> @! (@<symbol> @<form>) @}^*) \\ \ind
-      @[[ @<declaration>^* @! @<doc-string> @]] \\
-      @<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}
   The synopsis for a macro describes the acceptable syntax using the
   following notation.
   \begin{itemize}


@@ -185,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{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
   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


@@ -197,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.
   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 --------------------------------------------------
 
 
 %%%----- That's all, folks --------------------------------------------------