doc/misc.tex: Describe a couple of default methods explicitly.

[sod] / doc / misc.tex

diff --git a/doc/misc.tex b/doc/misc.tex
index 890dd14..4d80a5d 100644 (file)
--- a/doc/misc.tex
+++ b/doc/misc.tex
@@ -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|.
 
@@ -256,9 +256,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 +282,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 +518,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 +535,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}
 
 
@@ -1114,6 +1141,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>}