X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/b9d79c4c07134738b826dd84c80e2431e2a0d3c8..7d69686f71d01de4f8df65b2d417b6b4faaac5ec:/doc/misc.tex

diff --git a/doc/misc.tex b/doc/misc.tex
index 05cda1f..353c948 100644
--- a/doc/misc.tex
+++ b/doc/misc.tex
@@ -84,7 +84,7 @@ of these are standard.
   If a @<value-form> is omitted, then the value of the corresponding @<var>
   is used.  It is conventional usage for a macro to wrap @|once-only| around
   its body so as to convert the arguments which it should evaluate into safe
-  gensyms capturing their runtime values.  (Not that the simple expansion
+  gensyms capturing their runtime values.  (Note that the simple expansion
   given above can't do this correctly.)  A bare symbol may be written in
   place of a singleton list.
 \end{describe}
@@ -138,11 +138,11 @@ These locatives can't usefully be compared.  It should be possible to compare
 true locatives, such that two locatives compare equal if and only if they
 refer to the same place; but that doesn't work for these locatives.
 
-\begin{describe}{cls}{loc}
+\begin{describe}{cls}{locative}
   The type of locative objects.
 \end{describe}
 
-\begin{describe}{fun}{locp @<object> @> @<generalized-boolean>}
+\begin{describe}{fun}{locativep @<object> @> @<generalized-boolean>}
   Return non-nil if and only if @<object> is a locative.
 \end{describe}
 
@@ -184,7 +184,7 @@ refer to the same place; but that doesn't work for these locatives.
 
 An anaphoric macro implicitly binds a well-known name to a value of interest,
 in the course of doing something else.  The concept was popularized by Paul
-Graham \cite{FIXME:OnLisp}.
+Graham \cite{graham-1993:on-lisp}.
 
 The macros described here all bind the variable @|it|.
 
@@ -192,10 +192,11 @@ The macros described here all bind the variable @|it|.
   The symbol @|it| is exported by the @|sod-utilities| package.
 \end{describe}
 
-\begin{describe}{mac}{aif @<condition> @<consequent> @[@<alt>@] @> @<value>^*}
+\begin{describe}{mac}
+    {aif @<condition> @<consequent> @[@<alternative>@] @> @<value>^*}
   Evaluate the @<condition>.  If @<condition> is non-nil, then bind @|it| to
   the resulting value and evaluate the @<consequent>, returning all of its
-  values.  Otherwise, evaluate @<alt>, returning all of its values.
+  values.  Otherwise, evaluate @<alternative>, returning all of its values.
 \end{describe}
 
 \begin{describe}{mac}{aand @<form>^* @> @<value>^*}
@@ -256,9 +257,16 @@ metaobject protocol.
 \begin{describe}{gf}{instance-initargs @<instance> @> @<initargs-list>}
   Return a fresh list of plausible initargs for the given @<instance>.
 
-  This is done by digging through the instance's class's slot definitions and
-  enquiring about their initargs.  Initargs which are handled by methods on
-  @|shared-initialize| or similar generic functions won't be discovered.
+  The default method should work for most classes, but may be overridden to
+  cope with special effects.
+
+  \begin{describe}{meth}{standard-object}
+      {instance-initargs (@<instance> standard-object) @> @<initargs-list>}
+    The default method works by digging through the instance's class's slot
+    definitions and enquiring about their initargs.  Initargs which are
+    handled by methods on @|shared-initialize| or similar generic functions
+    won't be discovered.
+  \end{describe}
 \end{describe}
 
 \begin{describe*}
@@ -275,18 +283,24 @@ metaobject protocol.
   that generic function.
 
   The default method on @|copy-instance-using-class| should work for most
-  classes, but may be overridden to cope with special effects.  It works as
-  follows.
-  \begin{enumerate}
-  \item Allocate a fresh instance of @<class>, using @|allocate-instance|.
-  \item For each slot defined by @<class>, if that slot is bound in the
-    original instance, then set the corresponding slot in the new instance to
-    the same value.
-  \item Call @|shared-initialize| on the new instance, providing it the given
-    list of @<initargs>, but inhibiting the usual initialization of slots
-    from their initforms.
-  \item Return the new instance.
-  \end{enumerate}
+  classes, but may be overridden to cope with special effects.
+
+  \begin{describe}{meth}{standard-class}
+    {copy-instance-using-class \=(@<class> standard-class) @<instance> \\
+                               \>\&rest initargs
+        \nlret @<new-instance>}
+    The default method works as follows.
+    \begin{enumerate}
+    \item Allocate a fresh instance of @<class>, using @|allocate-instance|.
+    \item For each slot defined by @<class>, if that slot is bound in the
+      original instance, then set the corresponding slot in the new instance
+      to the same value.
+    \item Call @|shared-initialize| on the new instance, providing it the
+      given list of @<initargs>, but inhibiting the usual initialization of
+      slots from their initforms.
+    \item Return the new instance.
+    \end{enumerate}
+  \end{describe}
 \end{describe*}
 
 \begin{describe*}
@@ -505,6 +519,15 @@ be implemented fairly easily using @|merge-lists| below.
   the partial order.
 \end{describe}
 
+\begin{describe}{fun}{cross-product \&rest @<pieces>}
+  Return the cross product of the @<pieces>.
+
+  Each arguments may be a list, or a (non-nil) atom, which is equivalent to a
+  singleton list containing just that atom.  Return a list of all possible
+  lists which can be constructed by taking one item from each argument list
+  in turn, in an arbitrary order.
+\end{describe}
+
 \begin{describe}{fun}
     {find-duplicates @<report> @<sequence> \&key :key :test}
   Call @<report> on each pair of duplicate items in a @<sequence>.
@@ -513,9 +536,14 @@ be implemented fairly easily using @|merge-lists| below.
   and $y$ are considered equal if and only if @|(funcall @<test> (funcall
   @<key> $x$) (funcall @<key> $y$))| returns non-nil.
 
+  The @<report> function is called as @|(funcall @<report> @<duplicate>
+  @<previous>)|.  Duplicates are reported in order; the @<previous> item is
+  always the first matching item in the sequence.
+
   This function will work for arbitrary @<test> functions, but it will run
-  much more efficiently if @<test> is @|eq|, @|eql|, @|equal|, or @|equalp|
-  (because it can use hash-tables).
+  much more efficiently if @<test> is @|eq|, @|eql|, @|equal|, or @|equalp|,
+  because it can use hash-tables.  (The generic implementation for lists is
+  especially inefficient.)
 \end{describe}
 
 
@@ -867,6 +895,19 @@ The following definitions are useful when working with conditions.
   Dijkstra.
 \end{describe}
 
+
+\subsection{Other exported symbols}
+
+\begin{describe}{sym}{int}
+  The symbol @|int| is exported by the @|sod-utilities| package, without
+  giving it any particular meaning.  This is done because it's given
+  non-conflicting meanings by two different packages, and it's more
+  convenient for user code not to have to deal with an unnecessary symbol
+  conflict.  Specifically, the @|sod| package wants to define it as a C type
+  specifier, see \descref{cls}{simple-c-type}; and @|optparse| wants to
+  define it as an option handler, see \descref{opt}{int}.
+\end{describe}
+
 %%%--------------------------------------------------------------------------
 \section{Option parser} \label{sec:misc.optparse}
 
@@ -918,8 +959,8 @@ Most of these symbols are defined in the @|optparse| package.
      \dhead{fun}{setf (opt-negated-tag @<option>) @<tag>}
      \dhead{fun}{opt-arg-name @<option> @> @<string-or-null>}
      \dhead{fun}{setf (opt-arg-name @<option>) @<string-or-null>}
-     \dhead{fun}{opt-optional-p @<option> @> @<generalized-boolean>}
-     \dhead{fun}{setf (opt-optional-p @<option>) @<generalized-boolean>}
+     \dhead{fun}{opt-arg-optional-p @<option> @> @<generalized-boolean>}
+     \dhead{fun}{setf (opt-arg-optional-p @<option>) @<generalized-boolean>}
      \dhead{fun}{opt-documentation @<option> @> @<string-or-null>}
      \dhead{fun}{setf (opt-documentation @<option>) @<string-or-null>}}
 \end{describe*}
@@ -956,6 +997,9 @@ Most of these symbols are defined in the @|optparse| package.
       \&key :format-control :format-arguments}
 \end{describe}
 
+\begin{describe}{fun}{option-parse-error @<msg> \&optional @<args>}
+\end{describe}
+
 \begin{describe}{fun}{option-parse-remainder @<option-parser>}
 \end{describe}
 
@@ -1074,7 +1118,7 @@ Most of these symbols are defined in the @|optparse| package.
           @<form>^*) @}^*}
 \end{describe}
 
-\begin{describe}{fun}{augment-options @<options-list>}
+\begin{describe}{fun}{sod-frontend:augment-options @<options-list>}
 \end{describe}
 
 %%%--------------------------------------------------------------------------
@@ -1098,6 +1142,7 @@ Most of these symbols are defined in the @|optparse| package.
 
 \begin{describe*}
     {\dhead{fun}{p-name @<property> @> @<name>}
+     \dhead{meth}{property}{file-location (@<property> property) @> @<floc>}
      \dhead{fun}{p-value @<property> @> @<value>}
      \dhead{fun}{p-type @<property> @> @<type>}
      \dhead{fun}{p-key @<property> @> @<symbol>}