From cac85e0be5833902081c903f75e348b949294fb9 Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Sun, 30 Aug 2015 10:58:38 +0100
Subject: [PATCH] doc/: Document where declarations are permitted in macros.

---
 doc/clang.tex     | 27 +++++++++++++++++++--------
 doc/lispintro.tex | 11 ++++++-----
 doc/misc.tex      | 49 ++++++++++++++++++++++++++++++++-----------------
 doc/parsing.tex   | 32 ++++++++++++++++++++------------
 4 files changed, 77 insertions(+), 42 deletions(-)

diff --git a/doc/clang.tex b/doc/clang.tex
index 52e330d..9462942 100644
--- a/doc/clang.tex
+++ b/doc/clang.tex
@@ -138,7 +138,10 @@ type specifier.  Type specifiers fit into two syntactic categories.
 \end{describe}
 
 \begin{describe}{mac}
-    {define-c-type-syntax @<name> @<lambda-list> @<form>^* @> @<name>}
+    {define-c-type-syntax @<name> @<lambda-list> \\ \ind
+      @[[ @<declaration>^* @! @<doc-string> @]] \\
+      @<form>^* \-
+     \nlret @<name>}
   Defines the symbol @<name> as a new type operator.  When a list of the form
   @|(@<name> @<argument>^*)| is used as a type specifier, the @<argument>s
   are bound to fresh variables according to @<lambda-list> (a destructuring
@@ -265,7 +268,9 @@ argument lists for methods.  This is done by @|c-type-equal-p|.
 \end{describe}
 
 \begin{describe}{mac}
-    {maybe-in-parens (@<stream-var> @<guard-form>) @<form>^*}
+    {maybe-in-parens (@<stream-var> @<guard-form>)
+      @<declaration>^*
+      @<form>^*}
   The @<guard-form> is evaluated, and then the @<form>s are evaluated in
   sequence within a pretty-printer logical block writing to the stream named
   by the symbol @<stream-var>.  If the @<guard-form> evaluates to nil, then
@@ -800,13 +805,17 @@ Temporary names are represented by objects which implement a simple protocol.
 \end{describe}
 
 \begin{describe}{mac}
-    {definst @<code> (@<streamvar> \&key @<export>) (@<arg>^*)
-      @<body-form>^*}
+    {definst @<code> (@<streamvar> \&key @<export>) (@<arg>^*) \\ \ind
+      @[[ @<declaration>^* @! @<doc-string> @]] \\
+      @<form>^* \-
+     \nlret @<code>}
 \end{describe}
 
 \begin{describe}{mac}
-    {format-compound-statement (@<stream> @<child> \&optional @<morep>)
-      @<body-form>^*}
+    {format-compound-statement
+        (@<stream> @<child> \&optional @<morep>) \\ \ind
+      @<declaration>^* \\
+      @<form>^*}
 \end{describe}
 
 \begin{table}
@@ -895,8 +904,10 @@ Temporary names are represented by objects which implement a simple protocol.
 \end{describe}
 
 \begin{describe}{mac}
-    {with-temporary-var (@<codegen> @<var> @<type>) @<body-form>^*
-      @> @<value>^*}
+    {with-temporary-var (@<codegen> @<var> @<type>) \\ \ind
+      @<declaration>^* \\
+      @<form>^* \-
+     \nlret @<value>^*}
 \end{describe}
 
 \begin{describe}{fun}{deliver-expr @<codegen> @<target> @<expr>}
diff --git a/doc/lispintro.tex b/doc/lispintro.tex
index 5f1043f..dc1cab1 100644
--- a/doc/lispintro.tex
+++ b/doc/lispintro.tex
@@ -157,11 +157,12 @@ category (function, class, macro, etc.) on the right.
   \end{quote}
 \end{describe}
 
-\begin{describe}{mac}{example-macro
-  ( @{ @<symbol> @! (@<symbol> @<form>) @}^* ) \\ \ind
-    @[[ @<declaration>^* @! @<documentation-string> @]] \\
-    @<body-form>^*
-      \nlret @<value>^*}
+\begin{describe}{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}
diff --git a/doc/misc.tex b/doc/misc.tex
index de62c8e..92223d1 100644
--- a/doc/misc.tex
+++ b/doc/misc.tex
@@ -32,17 +32,20 @@ These symbols are defined in the @|sod-utilities| package.
 
 \begin{describe}{mac}
     {with-gensyms (@{ @<var> @! (@<var> @[@<name>@]) @}^*) \\ \ind
-      @<body-form>^*}
+      @<declaration>^* \\
+      @<form>^*}
 \end{describe}
 
 \begin{describe}{mac}
     {once-only (@[[ :environment @<env> @]]
                 @{ @<var> @! (@<var> @[@<value-form>@]) @}^*) \\ \ind
-      @<body-form>^*}
+      @<declaration>^* \\
+      @<form>^*}
 \end{describe}
 
 \begin{describe}{mac}
-    {parse-body @<body> @> @<doc-string> @<declarations> @<body-forms>}
+    {parse-body @<body> \&key :docp :declp
+      @> @<doc-string> @<declarations> @<body-forms>}
 \end{describe}
 
 \begin{describe}{cls}{loc}
@@ -51,7 +54,7 @@ These symbols are defined in the @|sod-utilities| package.
 \begin{describe}{fun}{locp @<object> @> @<generalized-boolean>}
 \end{describe}
 
-\begin{describe}{macro}{locf @<place> @> @<locative>}
+\begin{describe}{mac}{locf @<place> @> @<locative>}
 \end{describe}
 
 \begin{describe*}
@@ -63,7 +66,8 @@ These symbols are defined in the @|sod-utilities| package.
     {with-locatives
         @{ @<var> @! (@{ @<var> @!
                          (@<var> @[@<locative>@]) @}^*) @} \\ \ind
-      @<body-form>^*}
+      @<declaration>^* \\
+      @<form>^*}
 \end{describe}
 
 \begin{describe}{sym}{it}
@@ -72,7 +76,7 @@ These symbols are defined in the @|sod-utilities| package.
 \begin{describe}{mac}{aif @<condition> @<consequent> @[@<alt>@]}
 \end{describe}
 
-\begin{describe}{mac}{awhen @<condition> @<body-form>^*}
+\begin{describe}{mac}{awhen @<condition> @<form>^*}
 \end{describe}
 
 \begin{describe}{mac}{acond @{ (@<condition> @<form>^*) @}^*}
@@ -136,7 +140,8 @@ These symbols are defined in the @|sod-utilities| package.
     {categorize (\=@<item-var> @<items>
                    @[[ :bind (@{ @<var> @! (@<var> @[@<value>@]) @}^*) @]])
                                                                  \\ \ind\ind
-        (@{ @<cat-var> @<cat-predicate> @}^*) \- \\
+        (@{ (@<cat-var> @<cat-predicate>) @}^*) \- \\
+      @<declaration>^* \\
       @<body-form>^* \-
      \nlret @<value>^*}
 \end{describe}
@@ -170,14 +175,16 @@ These symbols are defined in the @|sod-utilities| package.
     {maybe-print-unreadable-object (@<object> @<stream>
                                     @[[ :type @<type> @!
                                         :identity @<identity> @]]) \\ \ind
-       @<body-form>^*}
+      @<declaration>^* \\
+      @<form>^*}
 \end{describe}
 
 \begin{describe}{mac}
     {dosequence (@<var> @<sequence>
                  @[[ :start @<start> @! :end @<end> @!
                      :indexvar @<var> @]]) \\ \ind
-      @{ @<tag> @! @<body-form> @}^*}
+      @<declaration>^* \\
+      @{ @<tag> @! @<statement> @}^*}
 \end{describe}
 
 \begin{describe}{mac}
@@ -187,12 +194,13 @@ These symbols are defined in the @|sod-utilities| package.
 
 \begin{describe}{mac}
     {default-slot (@<instance> @<slot> @[@<slot-names>@]) \\ \ind
-      @<body-form>^*}
+      @<form>^*}
 \end{describe}
 
 \begin{describe}{mac}
     {define-on-demand-slot @<class> @<slot> (@<instance>) \\ \ind
-      @<body-form>^*}
+      @[[ @<declaration>^* @! @<doc-string> @]] \\
+      @<form>^*}
 \end{describe}
 
 %%%--------------------------------------------------------------------------
@@ -307,15 +315,16 @@ These symbols are defined in the @!optparse| package.
 \begin{describe}{fun}{option-parse-next @<option-parser>}
 \end{describe}
 
-\begin{describe}{mac}{option-parse-try @<body-form>^*}
+\begin{describe}{mac}{option-parse-try @<form>^*}
 \end{describe}
 
-\begin{describe}{mac}{with-unix-error-reporting () @<body-form>^*}
+\begin{describe}{mac}{with-unix-error-reporting () @<form>^*}
 \end{describe}
 
 \begin{describe}{mac}
     {defopthandler @<name> (@<var> @[@<arg>@]) @<lambda-list> \\ \ind
-      @<body-form>^*}
+      @[[ @<declaration>^* @! @<doc-string> @]] \\
+      @<form>^*}
 \end{describe}
 
 \begin{describe}{fun}
@@ -349,7 +358,10 @@ These symbols are defined in the @!optparse| package.
 \begin{describe}{opt}{list \&optional @<handler> \&rest @<handler-args>}
 \end{describe}
 
-\begin{describe}{mac}{defoptmacro @<name> @<lambda-list> @<body-form>^*}
+\begin{describe}{mac}
+    {defoptmacro @<name> @<lambda-list> \\ \ind
+      @[[ @<declaration>^* @! @<doc-string> @]] \\
+      @<form>^*}
 \end{describe}
 
 \begin{describe}{fun}{parse-option-form @<form>}
@@ -366,7 +378,8 @@ These symbols are defined in the @!optparse| package.
                          (:opt-arg @<arg-name>) @! \\
                          @<keyword> @! (:tag @<tag>) @!
                                        (:negated-tag @<tag>) @! \\
-                         @{ (@<handler> @<var> @<handler-arg>^*) @}^* @]]) @}^*}
+                         @{ (@<handler> @<var> @<handler-arg>^*) @}^*
+                   @]]) @}^*}
 \end{describe}
 
 \begin{describe}{fun}
@@ -468,7 +481,8 @@ These symbols are defined in the @!optparse| package.
 \begin{describe}{fun}{pset-map @<func> @<pset>}
 \end{describe}
 
-\begin{describe}{mac}{with-pset-iterator (@<iter> @<pset>) @<body-form>^*}
+\begin{describe}{mac}
+    {with-pset-iterator (@<iter> @<pset>) @<declaration>^* @<form>^*}
 \end{describe}
 
 \begin{describe}{fun}
@@ -499,6 +513,7 @@ These symbols are defined in the @!optparse| package.
     {default-slot-from-property
         (@<instance> @<slot> @[@<slot-names>@]) \\ \ind\ind
         (@<pset> @<property> @<type> @[@<prop-var> @<convert-form>^*@]) \- \\
+      @<declaration>^* \\
       @<default-form>^*}
 \end{describe}
 
diff --git a/doc/parsing.tex b/doc/parsing.tex
index 58959c0..2bf9105 100644
--- a/doc/parsing.tex
+++ b/doc/parsing.tex
@@ -124,11 +124,12 @@ consumed any input items.
 \end{describe*}
 
 \begin{describe}{mac}
-    {with-default-error-location (@<floc>) @<body-form>^* @> @<value>^*}
+    {with-default-error-location (@<floc>) @<declaration>^* @<form>^*
+      @> @<value>^*}
 \end{describe}
 
 \begin{describe}{mac}
-    {count-and-report-errors () @<body-form>^*
+    {count-and-report-errors () @<declaration>^* @<form>^*
       @> @<value> @<n-errors> @<n-warnings>}
 \end{describe}
 
@@ -209,7 +210,8 @@ the scanner and read that data again.  Therefore it's possible to
 \end{describe}
 
 \begin{describe}{mac}
-    {with-scanner-place (@<place> @<scanner>) @<body-form>^* @> @<value>^*}
+    {with-scanner-place (@<place> @<scanner>) @<declarations>^* @<form>^*
+      @> @<value>^*}
   Capture the @<scanner>'s current position as a place, evaluate the
   @<body-form>s as an implicit progn with the variable @<place> bound to the captured
   place.  When control leaves the @<body-form>s, the place is released.  The return
@@ -446,14 +448,16 @@ file-location protocols.
 \begin{describe}{mac}
     {defparse @<name> (@[[ :context (@<var> @<context-class>) @]]
                        @<destructuring-lambda-list-item>^*) \\ \ind
-      @<body-form>^* \-
+      @[[ @<declaration>^* @! @<doc-string> @]] \\
+      @<form>^* \-
      \nlret @<name>}
 \end{describe}
 
 \begin{describe}{mac}
     {with-parser-context
         (@<context-class> @{ @<init-keyword> @<value> @}^*) \\ \ind
-      @<body-form>^* \-
+      @<declaration>^* \\
+      @<form>^* \-
      \nlret @<value>^*}
 \end{describe}
 
@@ -482,7 +486,7 @@ file-location protocols.
 
 \begin{describe}{mac}
     {when-parse (@[@<result-var>@]) @<parser> \\ \ind
-      @<body-form>^* \-
+      @<form>^* \-
      \nlret @<value>^*}
 \end{describe}
 
@@ -563,7 +567,9 @@ file-location protocols.
 \end{describe}
 
 \begin{describe}{mac}
-    {define-pluggable-parser @<symbol> @<tag> @<lambda-list> @<body-form>^*}
+    {define-pluggable-parser @<symbol> @<tag> @<lambda-list>
+      @[[ @<declaration>^* @! @<doc-string> @]]
+      @<form>^*}
 \end{describe}
 
 \begin{describe}{gf}{parser-capture-place @<context> @> @<form>}
@@ -580,7 +586,9 @@ file-location protocols.
 \end{describe}
 
 \begin{describe}{mac}
-    {with-parser-place (@<place-var> @<context>) @<body-form>^*}
+    {with-parser-place (@<place-var> @<context>)
+      @[[ @<declaration>^* @! @<doc-string> @]]
+      @<form>^*}
 \end{describe}
 
 \begin{describe}{parseform}{peek @<parser>}
@@ -704,14 +712,14 @@ file-location protocols.
 
 \begin{describe*}
     {\dhead{mac}{preop @<name> (@<operand-var> @<lprec>)
-                  @<body-form>^*
+                  @<declaration>^* @<form>^*
                   @> @<prefix-operator>}
      \dhead{mac}{postop @<name>
                      (@<operand-var> @<lprec> @[[ :rprec @<rprec> @]])
-                  @<body-form>^*
-                  @> @<postfix-operator>}
+                  @<declaration>^* @<form>^*
+                  \nlret @<postfix-operator>}
      \dhead{mac}{binop @<name> (@<operand-var> @<lprec> @<rprec> @<assoc>)
-                  @<body-form>^*
+                  @<declaration>^*@<form>^*
                   @> @<binary-operator>}}
 \end{describe*}
 
-- 
2.11.0