X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/d9bd7c90250b7563be98f105d0a53ce66d559ea0..9b9ad6b931736323a34123c11edfdff97a22623e:/doc/misc.tex

diff --git a/doc/misc.tex b/doc/misc.tex
index ec0fe59..1e58cdf 100644
--- a/doc/misc.tex
+++ b/doc/misc.tex
@@ -39,7 +39,8 @@ of these are standard.
 \begin{describe}{mac}
     {with-gensyms (@{ @<var> @! (@<var> @[@<name>@]) @}^*)      \\ \ind
       @<declaration>^*                                          \\
-      @<form>^*}
+      @<form>^*
+     \-\nlret @<value>^*}
   Bind each @<var> (a symbol, not evaluated) to a freshly made gensym whose
   name is based on the corresponding @<name> (a string, evaluated), and
   evaluate the @<form>s as an implicit @|progn| in the resulting environment.
@@ -52,7 +53,7 @@ of these are standard.
                 @{ @<var> @! (@<var> @[@<value-form>@]) @}^*)   \\ \ind
       @<declaration>^*                                          \\
       @<form>^*
-      \nlret @<result-form>}
+     \-\nlret @<result-form>}
   This is a helper to ensure that macro expansions evaluate their arguments
   exactly once each, in the correct order.
 
@@ -163,7 +164,8 @@ refer to the same place; but that doesn't work for these locatives.
         @{ @<var> @! (@{ @<var> @!
                          (@<var> @[@<locative>@]) @}^*) @}      \\ \ind
       @<declaration>^*                                          \\
-      @<form>^*}
+      @<form>^*
+     \-\nlret @<values>^*}
   This is a macro which hides the use of locatives from its caller using
   symbol-macros.
 
@@ -190,13 +192,13 @@ 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>@]}
+\begin{describe}{mac}{aif @<condition> @<consequent> @[@<alt>@] @> @<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.
 \end{describe}
 
-\begin{describe}{mac}{aand @<form>^*}
+\begin{describe}{mac}{aand @<form>^* @> @<value>^*}
   Evaluate each @<form> in turn.  If any @<form> evaluates to nil, then stop
   and return nil.  Each form except the first is evaluated with @|it| bound
   to the (necessarily non-nil) value of the previous form.  If all but the
@@ -205,12 +207,12 @@ The macros described here all bind the variable @|it|.
 
 (No @|aor| is provided, since @|it| would necessarily be bound to nil.)
 
-\begin{describe}{mac}{awhen @<condition> @<form>^*}
+\begin{describe}{mac}{awhen @<condition> @<form>^* @> nil}
   If @<condition> evaluates to a non-nil value, bind @|it| to that value, and
   evaluate the @<form>s as an implicit @|progn|.  Otherwise, return nil.
 \end{describe}
 
-\begin{describe}{mac}{acond @{ (@<condition> @<form>^*) @}^*}
+\begin{describe}{mac}{acond @{ (@<condition> @<form>^*) @}^* @> @<value>^*}
   Evaluate each @<condition> in turn, until one of them produces a non-nil
   value.  If the @<condition> is followed by one or more @<form>s, then bind
   @|it| to the non-nil value of the @<condition> and evaluate the @<form>s as
@@ -219,21 +221,27 @@ The macros described here all bind the variable @|it|.
 \end{describe}
 
 \begin{describe*}
-    {\dhead{mac}
-      {acase @<scrutinee> @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*}
-     \dhead{mac}
-      {aecase @<scrutinee> @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*}
-     \dhead{mac}{atypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*}
-     \dhead{mac}{aetypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*}}
+    {\dhead{mac}{acase @<scrutinee>
+                  @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*
+                  @> @<value>^*}
+     \dhead{mac}{aecase @<scrutinee>
+                  @{ (@{ @<case> @! (@<case>^*) @} @<form>^*) @}^*
+                  @> @<value>^*}
+     \dhead{mac}{atypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*
+                  @> @<value>^*}
+     \dhead{mac}{aetypecase @<scrutinee> @{ (@<type> @<form>^*) @}^*
+                  @> @<value>^*}}
   These are like the Common Lisp macros @|case|, @|ecase|, @|typecase|, and
   @|etypecase|, except that @|it| is bound to the value of the @<scrutinee>
   while evaluating the matching @<form>s.
 \end{describe*}
 
-\begin{describe}{mac}{asetf @{ @<place> @<value> @}^*}
+\begin{describe}{mac}{asetf @{ @<place> @<value> @}^* @> @<value>^*}
   For each @<place> and @<value> in turn: bind @|it| to the current value of
   the @<place>, evaluate the @<value> expression, and store the resulting
-  value back in the @<place>.
+  value back in the @<place>.  Return the @<value>(s) stored by the final
+  pair: there may be more than one value, e.g., if @<place> is a @|values|
+  form.
 
   For example, @|(asetf @<place> (1+ it))| is almost equivalent to @|(incf
   @<place>)|, even if evaluating @<place> has side-effects.
@@ -245,7 +253,7 @@ The macros described here all bind the variable @|it|.
 The following utilities make use of the introspection features of the CLOS
 metaobject protocol.
 
-\begin{describe}{gf}{instance-initargs @<instance>}
+\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
@@ -859,6 +867,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}
 
@@ -1066,7 +1087,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}
 
 %%%--------------------------------------------------------------------------
