[Emacs-diffs] /srv/bzr/emacs/trunk r110695: * doc/misc/cl.texi: Use defmac for macros rather than defspec.

[Glenn Morris]

------------------------------------------------------------
revno: 110695
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sat 2012-10-27 15:54:53 -0700
message:
  * doc/misc/cl.texi: Use defmac for macros rather than defspec.
  (Efficiency Concerns): Related copyedit.
modified:
  doc/misc/ChangeLog
  doc/misc/cl.texi

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-10-27 22:42:07 +0000
+++ b/doc/misc/ChangeLog        2012-10-27 22:54:53 +0000
@@ -1,5 +1,8 @@
 2012-10-27  Glenn Morris  <address@hidden>
 
+       * cl.texi: Use defmac for macros rather than defspec.
+       (Efficiency Concerns): Related copyedit.
+
        * cl.texi (Control Structure): Update for setf now being in core.
        (Setf Extensions): Rename from Basic Setf.  Move much of the
        former content to lispref/variables.texi.

=== modified file 'doc/misc/cl.texi'
--- a/doc/misc/cl.texi  2012-10-27 22:42:07 +0000
+++ b/doc/misc/cl.texi  2012-10-27 22:54:53 +0000
@@ -268,14 +268,14 @@
 Instead, this package defines alternates for several Lisp forms
 which you must use if you need Common Lisp argument lists.
 
address@hidden cl-defun name arglist body...
address@hidden cl-defun name arglist body...
 This form is identical to the regular @code{defun} form, except
 that @var{arglist} is allowed to be a full Common Lisp argument
 list.  Also, the function body is enclosed in an implicit block
 called @var{name}; @pxref{Blocks and Exits}.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-defsubst name arglist body...
address@hidden cl-defsubst name arglist body...
 This is just like @code{cl-defun}, except that the function that
 is defined is automatically proclaimed @code{inline}, i.e.,
 calls to it may be expanded into in-line code by the byte compiler.
@@ -285,9 +285,9 @@
 efficient inline expansions.  In particular, @code{cl-defsubst}
 arranges for the processing of keyword arguments, default values,
 etc., to be done at compile-time whenever possible.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-defmacro name arglist body...
address@hidden cl-defmacro name arglist body...
 This is identical to the regular @code{defmacro} form,
 except that @var{arglist} is allowed to be a full Common Lisp
 argument list.  The @code{&environment} keyword is supported as
@@ -296,13 +296,13 @@
 cannot be implemented with the current Emacs Lisp interpreter.
 The macro expander body is enclosed in an implicit block called
 @var{name}.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-function symbol-or-lambda
address@hidden cl-function symbol-or-lambda
 This is identical to the regular @code{function} form,
 except that if the argument is a @code{lambda} form then that
 form may use a full Common Lisp argument list.
address@hidden defspec
address@hidden defmac
 
 Also, all forms (such as @code{cl-flet} and @code{cl-labels}) defined
 in this package that include @var{arglist}s in their syntax allow
@@ -491,7 +491,7 @@
 at compile-time so that later parts of the file can refer to the
 macros that are defined.
 
address@hidden cl-eval-when (situations...) forms...
address@hidden cl-eval-when (situations...) forms...
 This form controls when the body @var{forms} are evaluated.
 The @var{situations} list may contain any set of the symbols
 @code{compile}, @code{load}, and @code{eval} (or their long-winded
@@ -563,7 +563,7 @@
 certain top-level forms, like @code{defmacro} (sort-of) and
 @code{require}, as if they were wrapped in @code{(cl-eval-when
 (compile load eval) @dots{})}.
address@hidden defspec
address@hidden defmac
 
 Emacs includes two special forms related to @code{cl-eval-when}.
 One of these, @code{eval-when-compile}, is not quite equivalent to
@@ -573,7 +573,7 @@
 equivalent to @samp{(cl-eval-when (compile load eval) @dots{})} and
 so is not itself defined by this package.
 
address@hidden eval-when-compile forms...
address@hidden eval-when-compile forms...
 The @var{forms} are evaluated at compile-time; at execution time,
 this form acts like a quoted constant of the resulting value.  Used
 at top-level, @code{eval-when-compile} is just like @samp{eval-when
@@ -582,9 +582,9 @@
 or other reasons.
 
 This form is similar to the @samp{#.} syntax of true Common Lisp.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-load-time-value form
address@hidden cl-load-time-value form
 The @var{form} is evaluated at load-time; at execution time,
 this form acts like a quoted constant of the resulting value.
 
@@ -625,7 +625,7 @@
           ", and loaded on: "
           --temp--))
 @end example
address@hidden defspec
address@hidden defmac
 
 @node Predicates
 @chapter Predicates
@@ -733,7 +733,7 @@
 error.
 @end defun
 
address@hidden cl-deftype name arglist forms...
address@hidden cl-deftype name arglist forms...
 This macro defines a new type called @var{name}.  It is similar
 to @code{defmacro} in many ways; when @var{name} is encountered
 as a type name, the body @var{forms} are evaluated and should
@@ -761,7 +761,7 @@
 The last example shows how the Common Lisp @code{unsigned-byte}
 type specifier could be implemented if desired; this package does
 not implement @code{unsigned-byte} by default.
address@hidden defspec
address@hidden defmac
 
 The @code{cl-typecase} and @code{cl-check-type} macros also use type
 names.  @xref{Conditionals}.  @xref{Assertions}.  The @code{cl-map},
@@ -826,7 +826,7 @@
 The @code{cl-psetq} form is just like @code{setq}, except that multiple
 assignments are done in parallel rather than sequentially.
 
address@hidden cl-psetq [symbol address@hidden
address@hidden cl-psetq [symbol address@hidden
 This special form (actually a macro) is used to assign to several
 variables simultaneously.  Given only one @var{symbol} and @var{form},
 it has the same effect as @code{setq}.  Given several @var{symbol}
@@ -854,7 +854,7 @@
 @pxref{Modify Macros}.)
 
 @code{cl-psetq} always returns @code{nil}.
address@hidden defspec
address@hidden defmac
 
 @node Generalized Variables
 @section Generalized Variables
@@ -1010,15 +1010,15 @@
 variables.  Many are interesting and useful even when the @var{place}
 is just a variable name.
 
address@hidden cl-psetf [place address@hidden
address@hidden cl-psetf [place address@hidden
 This macro is to @code{setf} what @code{cl-psetq} is to @code{setq}:
 When several @var{place}s and @var{form}s are involved, the
 assignments take place in parallel rather than sequentially.
 Specifically, all subforms are evaluated from left to right, then
 all the assignments are done (in an undefined order).
address@hidden defspec
address@hidden defmac
 
address@hidden cl-incf place &optional x
address@hidden cl-incf place &optional x
 This macro increments the number stored in @var{place} by one, or
 by @var{x} if specified.  The incremented value is returned.  For
 example, @code{(cl-incf i)} is equivalent to @code{(setq i (1+ i))}, and
@@ -1057,22 +1057,22 @@
 As a more Emacs-specific example of @code{cl-incf}, the expression
 @code{(cl-incf (point) @var{n})} is essentially equivalent to
 @code{(forward-char @var{n})}.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-decf place &optional x
address@hidden cl-decf place &optional x
 This macro decrements the number stored in @var{place} by one, or
 by @var{x} if specified.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-pushnew x place @t{&key :test :test-not :key}
address@hidden cl-pushnew x place @t{&key :test :test-not :key}
 This macro inserts @var{x} at the front of the list stored in
 @var{place}, but only if @var{x} was not @code{eql} to any
 existing element of the list.  The optional keyword arguments
 are interpreted in the same way as for @code{cl-adjoin}.
 @xref{Lists as Sets}.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-shiftf address@hidden newvalue
address@hidden cl-shiftf address@hidden newvalue
 This macro shifts the @var{place}s left by one, shifting in the
 value of @var{newvalue} (which may be any Lisp expression, not just
 a generalized variable), and returning the value shifted out of
@@ -1090,9 +1090,9 @@
 @noindent
 except that the subforms of @var{a}, @var{b}, and @var{c} are actually
 evaluated only once each and in the apparent order.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-rotatef address@hidden
address@hidden cl-rotatef address@hidden
 This macro rotates the @var{place}s left by one in circular fashion.
 Thus, @code{(cl-rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to
 
@@ -1107,12 +1107,12 @@
 except for the evaluation of subforms.  @code{cl-rotatef} always
 returns @code{nil}.  Note that @code{(cl-rotatef @var{a} @var{b})}
 conveniently exchanges @var{a} and @var{b}.
address@hidden defspec
address@hidden defmac
 
 The following macros were invented for this package; they have no
 analogues in Common Lisp.
 
address@hidden letf (address@hidden) address@hidden
address@hidden letf (address@hidden) address@hidden
 This macro is analogous to @code{let}, but for generalized variables
 rather than just symbols.  Each @var{binding} should be of the form
 @code{(@var{place} @var{value})}; the original contents of the
@@ -1162,14 +1162,14 @@
 variables and calls to @code{symbol-value} and @code{symbol-function}.
 If the symbol is not bound on entry, it is simply made unbound by
 @code{makunbound} or @code{fmakunbound} on exit.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-letf* (address@hidden) address@hidden
address@hidden cl-letf* (address@hidden) address@hidden
 This macro is to @code{letf} what @code{let*} is to @code{let}:
 It does the bindings in sequential rather than parallel order.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-callf @var{function} @var{place} @address@hidden
address@hidden cl-callf @var{function} @var{place} @address@hidden
 This is the ``generic'' modify macro.  It calls @var{function},
 which should be an unquoted function name, macro name, or lambda.
 It passes @var{place} and @var{args} as arguments, and assigns the
@@ -1186,14 +1186,14 @@
 @xref{Customizing Setf}, for @code{define-modify-macro}, a way
 to create even more concise notations for modify macros.  Note
 again that @code{cl-callf} is an extension to standard Common Lisp.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-callf2 @var{function} @var{arg1} @var{place} @address@hidden
address@hidden cl-callf2 @var{function} @var{arg1} @var{place} @address@hidden
 This macro is like @code{cl-callf}, except that @var{place} is
 the @emph{second} argument of @var{function} rather than the
 first.  For example, @code{(push @var{x} @var{place})} is
 equivalent to @code{(cl-callf2 cons @var{x} @var{place})}.
address@hidden defspec
address@hidden defmac
 
 The @code{cl-callf} and @code{cl-callf2} macros serve as building
 blocks for other macros like @code{cl-incf}, @code{cl-pushnew}, and
@@ -1209,7 +1209,7 @@
 @code{defsetf}, and @code{define-setf-method}, that allow the
 user to extend generalized variables in various ways.
 
address@hidden define-modify-macro name arglist function [doc-string]
address@hidden define-modify-macro name arglist function [doc-string]
 This macro defines a ``read-modify-write'' macro similar to
 @code{cl-incf} and @code{cl-decf}.  The macro @var{name} is defined
 to take a @var{place} argument followed by additional arguments
@@ -1249,9 +1249,9 @@
 is completely irregular.  You can define these macros ``by hand''
 using @code{get-setf-method}, or consult the source
 to see how to use the internal @code{setf} building blocks.
address@hidden defspec
address@hidden defmac
 
address@hidden defsetf access-fn update-fn
address@hidden defsetf access-fn update-fn
 This is the simpler of two @code{defsetf} forms.  Where
 @var{access-fn} is the name of a function which accesses a place,
 this declares @var{update-fn} to be the corresponding store
@@ -1294,9 +1294,9 @@
 (defsetf symbol-value set)
 (defsetf buffer-name rename-buffer t)
 @end example
address@hidden defspec
address@hidden defmac
 
address@hidden defsetf access-fn arglist (store-var) address@hidden
address@hidden defsetf access-fn arglist (store-var) address@hidden
 This is the second, more complex, form of @code{defsetf}.  It is
 rather like @code{defmacro} except for the additional @var{store-var}
 argument.  The @var{forms} should return a Lisp form which stores
@@ -1325,9 +1325,9 @@
 (defsetf nth (n x) (store)
   (list 'setcar (list 'nthcdr n x) store))
 @end example
address@hidden defspec
address@hidden defmac
 
address@hidden define-setf-method access-fn arglist address@hidden
address@hidden define-setf-method access-fn arglist address@hidden
 This is the most general way to create new place forms.  When
 a @code{setf} to @var{access-fn} with arguments described by
 @var{arglist} is expanded, the @var{forms} are evaluated and
@@ -1372,7 +1372,7 @@
 use this setf-method will optimize away most temporaries that
 turn out to be unnecessary, so there is little reason for the
 setf-method itself to optimize.
address@hidden defspec
address@hidden defmac
 
 @defun get-setf-method place &optional env
 This function returns the setf-method for @var{place}, by
@@ -1435,7 +1435,7 @@
 at compile-time.  The @code{cl-progv} form provides an easy way to
 bind variables whose names are computed at run-time.
 
address@hidden cl-progv symbols values address@hidden
address@hidden cl-progv symbols values address@hidden
 This form establishes @code{let}-style variable bindings on a
 set of variables computed at run-time.  The expressions
 @var{symbols} and @var{values} are evaluated, and must return lists
@@ -1445,7 +1445,7 @@
 are bound to @code{nil}.
 If @var{symbols} is shorter than @var{values}, the excess values
 are ignored.
address@hidden defspec
address@hidden defmac
 
 @node Lexical Bindings
 @subsection Lexical Bindings
@@ -1454,7 +1454,7 @@
 The @code{CL} package defines the following macro which
 more closely follows the Common Lisp @code{let} form:
 
address@hidden lexical-let (address@hidden) address@hidden
address@hidden lexical-let (address@hidden) address@hidden
 This form is exactly like @code{let} except that the bindings it
 establishes are purely lexical.  Lexical bindings are similar to
 local variables in a language like C:  Only the code physically
@@ -1554,12 +1554,12 @@
 
 The @code{lexical-let} form is an extension to Common Lisp.  In
 true Common Lisp, all bindings are lexical unless declared otherwise.
address@hidden defspec
address@hidden defmac
 
address@hidden lexical-let* (address@hidden) address@hidden
address@hidden lexical-let* (address@hidden) address@hidden
 This form is just like @code{lexical-let}, except that the bindings
 are made sequentially in the manner of @code{let*}.
address@hidden defspec
address@hidden defmac
 
 @node Function Bindings
 @subsection Function Bindings
@@ -1568,7 +1568,7 @@
 These forms make @code{let}-like bindings to functions instead
 of variables.
 
address@hidden flet (address@hidden) address@hidden
address@hidden flet (address@hidden) address@hidden
 This form establishes @code{let}-style bindings on the function
 cells of symbols rather than on the value cells.  Each @var{binding}
 must be a list of the form @samp{(@var{name} @var{arglist}
@@ -1612,9 +1612,9 @@
 argument notation supported by @code{cl-defun}; also, the function
 body is enclosed in an implicit block as if by @code{cl-defun}.
 @xref{Program Structure}.
address@hidden defspec
address@hidden defmac
 
address@hidden labels (address@hidden) address@hidden
address@hidden labels (address@hidden) address@hidden
 The @code{labels} form is like @code{flet}, except that it
 makes lexical bindings of the function names rather than
 dynamic bindings.  (In true Common Lisp, both @code{flet} and
@@ -1635,7 +1635,7 @@
 A ``reference'' to a function name is either a call to that
 function, or a use of its name quoted by @code{quote} or
 @code{function} to be passed on to, say, @code{mapcar}.
address@hidden defspec
address@hidden defmac
 
 @node Macro Bindings
 @subsection Macro Bindings
@@ -1643,7 +1643,7 @@
 @noindent
 These forms create local macros and ``symbol macros''.
 
address@hidden cl-macrolet (address@hidden) address@hidden
address@hidden cl-macrolet (address@hidden) address@hidden
 This form is analogous to @code{flet}, but for macros instead of
 functions.  Each @var{binding} is a list of the same form as the
 arguments to @code{cl-defmacro} (i.e., a macro name, argument list,
@@ -1655,9 +1655,9 @@
 affect only calls that appear physically within the body
 @var{forms}, possibly after expansion of other macros in the
 body.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-symbol-macrolet (address@hidden) address@hidden
address@hidden cl-symbol-macrolet (address@hidden) address@hidden
 This form creates @dfn{symbol macros}, which are macros that look
 like variable references rather than function calls.  Each
 @var{binding} is a list @samp{(@var{var} @var{expansion})};
@@ -1723,7 +1723,7 @@
 @xref{Loop Facility}, for a description of the @code{cl-loop} macro.
 This package defines a nonstandard @code{in-ref} loop clause that
 works much like @code{my-dolist}.
address@hidden defspec
address@hidden defmac
 
 @node Conditionals
 @section Conditionals
@@ -1732,7 +1732,7 @@
 These conditional forms augment Emacs Lisp's simple @code{if},
 @code{and}, @code{or}, and @code{cond} forms.
 
address@hidden cl-case keyform address@hidden
address@hidden cl-case keyform address@hidden
 This macro evaluates @var{keyform}, then compares it with the key
 values listed in the various @var{clause}s.  Whichever clause matches
 the key is executed; comparison is done by @code{eql}.  If no clause
@@ -1766,15 +1766,15 @@
   ((?\r ?\n) (do-ret-thing))
   (t (do-other-thing)))
 @end example
address@hidden defspec
address@hidden defmac
 
address@hidden cl-ecase keyform address@hidden
address@hidden cl-ecase keyform address@hidden
 This macro is just like @code{cl-case}, except that if the key does
 not match any of the clauses, an error is signaled rather than
 simply returning @code{nil}.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-typecase keyform address@hidden
address@hidden cl-typecase keyform address@hidden
 This macro is a version of @code{cl-case} that checks for types
 rather than values.  Each @var{clause} is of the form
 @samp{(@var{type} @var{body}...)}.  @xref{Type Predicates},
@@ -1791,13 +1791,13 @@
 The type specifier @code{t} matches any type of object; the word
 @code{otherwise} is also allowed.  To make one clause match any of
 several types, use an @code{(or ...)} type specifier.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-etypecase keyform address@hidden
address@hidden cl-etypecase keyform address@hidden
 This macro is just like @code{cl-typecase}, except that if the key does
 not match any of the clauses, an error is signaled rather than
 simply returning @code{nil}.
address@hidden defspec
address@hidden defmac
 
 @node Blocks and Exits
 @section Blocks and Exits
@@ -1810,7 +1810,7 @@
 optimizing byte-compiler to omit the costly @code{catch} step if the
 body of the block does not actually @code{cl-return-from} the block.
 
address@hidden cl-block name address@hidden
address@hidden cl-block name address@hidden
 The @var{forms} are evaluated as if by a @code{progn}.  However,
 if any of the @var{forms} execute @code{(cl-return-from @var{name})},
 they will jump out and return directly from the @code{cl-block} form.
@@ -1849,20 +1849,20 @@
 that jump to it.  This means that @code{cl-do} loops and @code{cl-defun}
 functions which don't use @code{cl-return} don't pay the overhead to
 support it.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-return-from name [result]
address@hidden cl-return-from name [result]
 This macro returns from the block named @var{name}, which must be
 an (unevaluated) symbol.  If a @var{result} form is specified, it
 is evaluated to produce the result returned from the @code{block}.
 Otherwise, @code{nil} is returned.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-return [result]
address@hidden cl-return [result]
 This macro is exactly like @code{(cl-return-from nil @var{result})}.
 Common Lisp loops like @code{cl-do} and @code{cl-dolist} implicitly enclose
 themselves in @code{nil} blocks.
address@hidden defspec
address@hidden defmac
 
 @node Iteration
 @section Iteration
@@ -1872,7 +1872,7 @@
 looping constructs to complement Emacs Lisp's basic @code{while}
 loop.
 
address@hidden cl-loop address@hidden
address@hidden cl-loop address@hidden
 The @code{CL} package supports both the simple, old-style meaning of
 @code{loop} and the extremely powerful and flexible feature known as
 the @dfn{Loop Facility} or @dfn{Loop Macro}.  This more advanced
@@ -1900,9 +1900,9 @@
 (This is not a restriction in practice, since a plain symbol
 in the above notation would simply access and throw away the
 value of a variable.)
address@hidden defspec
address@hidden defmac
 
address@hidden cl-do (address@hidden) (end-test address@hidden) address@hidden
address@hidden cl-do (address@hidden) (end-test address@hidden) address@hidden
 This macro creates a general iterative loop.  Each @var{spec} is
 of the form
 
@@ -1948,9 +1948,9 @@
      ((or (null x) (null y))
       (nreverse z)))
 @end example
address@hidden defspec
address@hidden defmac
 
address@hidden cl-do* (address@hidden) (end-test address@hidden) address@hidden
address@hidden cl-do* (address@hidden) (end-test address@hidden) address@hidden
 This is to @code{cl-do} what @code{let*} is to @code{let}.  In
 particular, the initial values are bound as if by @code{let*}
 rather than @code{let}, and the steps are assigned as if by
@@ -1968,9 +1968,9 @@
    (nreverse z))
   (push (f x y) z))
 @end example
address@hidden defspec
address@hidden defmac
 
address@hidden cl-dolist (var list [result]) address@hidden
address@hidden cl-dolist (var list [result]) address@hidden
 This is a more specialized loop which iterates across the elements
 of a list.  @var{list} should evaluate to a list; the body @var{forms}
 are executed with @var{var} bound to each element of the list in
@@ -1978,9 +1978,9 @@
 with @var{var} bound to @code{nil} to produce the result returned by
 the loop.  Unlike with Emacs's built in @code{dolist}, the loop is
 surrounded by an implicit @code{nil} block.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-dotimes (var count [result]) address@hidden
address@hidden cl-dotimes (var count [result]) address@hidden
 This is a more specialized loop which iterates a specified number
 of times.  The body is executed with @var{var} bound to the integers
 from zero (inclusive) to @var{count} (exclusive), in turn.  Then
@@ -1988,9 +1988,9 @@
 number of iterations that were done (i.e., @code{(max 0 @var{count})})
 to get the return value for the loop form.  Unlike with Emacs's built in
 @code{dolist}, the loop is surrounded by an implicit @code{nil} block.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-do-symbols (var [obarray [result]]) address@hidden
address@hidden cl-do-symbols (var [obarray [result]]) address@hidden
 This loop iterates over all interned symbols.  If @var{obarray}
 is specified and is not @code{nil}, it loops over all symbols in
 that obarray.  For each symbol, the body @var{forms} are evaluated
@@ -1998,12 +1998,12 @@
 an unspecified order.  Afterward the @var{result} form, if any,
 is evaluated (with @var{var} bound to @code{nil}) to get the return
 value.  The loop is surrounded by an implicit @code{nil} block.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-do-all-symbols (var [result]) address@hidden
address@hidden cl-do-all-symbols (var [result]) address@hidden
 This is identical to @code{cl-do-symbols} except that the @var{obarray}
 argument is omitted; it always iterates over the default obarray.
address@hidden defspec
address@hidden defmac
 
 @xref{Mapping over Sequences}, for some more functions for
 iterating over vectors or lists.
@@ -2043,7 +2043,7 @@
 takes place at byte-compile time; compiled @code{cl-loop}s are just
 as efficient as the equivalent @code{while} loops written longhand.
 
address@hidden cl-loop address@hidden
address@hidden cl-loop address@hidden
 A loop construct consists of a series of @var{clause}s, each
 introduced by a symbol like @code{for} or @code{do}.  Clauses
 are simply strung together in the argument list of @code{cl-loop},
@@ -2082,7 +2082,7 @@
 (Because the loop body is enclosed in an implicit block, you can
 also use regular Lisp @code{cl-return} or @code{cl-return-from} to
 break out of the loop.)
address@hidden defspec
address@hidden defmac
 
 The following sections give some examples of the Loop Macro in
 action, and describe the particular loop clauses in great detail.
@@ -2773,21 +2773,21 @@
 The @code{values} form, for example, is a synonym for @code{list}
 in Emacs.
 
address@hidden cl-multiple-value-bind (address@hidden) values-form 
address@hidden
address@hidden cl-multiple-value-bind (address@hidden) values-form 
address@hidden
 This form evaluates @var{values-form}, which must return a list of
 values.  It then binds the @var{var}s to these respective values,
 as if by @code{let}, and then executes the body @var{forms}.
 If there are more @var{var}s than values, the extra @var{var}s
 are bound to @code{nil}.  If there are fewer @var{var}s than
 values, the excess values are ignored.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-multiple-value-setq (address@hidden) form
address@hidden cl-multiple-value-setq (address@hidden) form
 This form evaluates @var{form}, which must return a list of values.
 It then sets the @var{var}s to these respective values, as if by
 @code{setq}.  Extra @var{var}s or values are treated the same as
 in @code{cl-multiple-value-bind}.
address@hidden defspec
address@hidden defmac
 
 Since a perfect emulation is not feasible in Emacs Lisp, this
 package opts to keep it as simple and predictable as possible.
@@ -2805,7 +2805,7 @@
 Destructuring is made available to the user by way of the
 following macro:
 
address@hidden cl-destructuring-bind arglist expr address@hidden
address@hidden cl-destructuring-bind arglist expr address@hidden
 This macro expands to code which executes @var{forms}, with
 the variables in @var{arglist} bound to the list of values
 returned by @var{expr}.  The @var{arglist} can include all
@@ -2814,13 +2814,13 @@
 is not allowed.)  The macro expansion will signal an error
 if @var{expr} returns a list of the wrong number of arguments
 or with incorrect keyword arguments.
address@hidden defspec
address@hidden defmac
 
 This package also includes the Common Lisp @code{cl-define-compiler-macro}
 facility, which allows you to define compile-time expansions and
 optimizations for your functions.
 
address@hidden cl-define-compiler-macro name arglist address@hidden
address@hidden cl-define-compiler-macro name arglist address@hidden
 This form is similar to @code{defmacro}, except that it only expands
 calls to @var{name} at compile-time; calls processed by the Lisp
 interpreter are not expanded, nor are they expanded by the
@@ -2854,7 +2854,7 @@
 @code{cl-member} call is left intact.  (The actual compiler macro
 for @code{cl-member} optimizes a number of other cases, including
 common @code{:test} predicates.)
address@hidden defspec
address@hidden defmac
 
 @defun cl-compiler-macroexpand form
 This function is analogous to @code{macroexpand}, except that it
@@ -2896,7 +2896,7 @@
 is evaluated and thus should normally be quoted.
 @end defun
 
address@hidden cl-declaim address@hidden
address@hidden cl-declaim address@hidden
 This macro is like @code{cl-proclaim}, except that it takes any number
 of @var{decl-spec} arguments, and the arguments are unevaluated and
 unquoted.  The @code{cl-declaim} macro also puts an @code{(cl-eval-when
@@ -2905,22 +2905,22 @@
 since normally the declarations are meant to influence the way the
 compiler treats the rest of the file that contains the @code{cl-declaim}
 form.)
address@hidden defspec
address@hidden defmac
 
address@hidden cl-declare address@hidden
address@hidden cl-declare address@hidden
 This macro is used to make declarations within functions and other
 code.  Common Lisp allows declarations in various locations, generally
 at the beginning of any of the many ``implicit @code{progn}s''
 throughout Lisp syntax, such as function bodies, @code{let} bodies,
 etc.  Currently the only declaration understood by @code{cl-declare}
 is @code{special}.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-locally address@hidden address@hidden
address@hidden cl-locally address@hidden address@hidden
 In this package, @code{cl-locally} is no different from @code{progn}.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-the type form
address@hidden cl-the type form
 Type information provided by @code{cl-the} is ignored in this package;
 in other words, @code{(cl-the @var{type} @var{form})} is equivalent
 to @var{form}.  Future versions of the optimizing byte-compiler may
@@ -2933,7 +2933,7 @@
 compiler would have enough information to expand the loop in-line.
 For now, Emacs Lisp will treat the above code as exactly equivalent
 to @code{(mapcar 'car foo)}.
address@hidden defspec
address@hidden defmac
 
 Each @var{decl-spec} in a @code{cl-proclaim}, @code{cl-declaim}, or
 @code{cl-declare} should be a list beginning with a symbol that says
@@ -3137,7 +3137,7 @@
 expression.
 @end defun
 
address@hidden cl-remf place property
address@hidden cl-remf place property
 This macro removes the property-value pair for @var{property} from
 the property list stored at @var{place}, which is any @code{setf}-able
 place expression.  It returns true if the property was found.  Note
@@ -3145,7 +3145,7 @@
 effectively do a @code{(setf @var{place} (cddr @var{place}))},
 whereas if it occurs later, this simply uses @code{setcdr} to splice
 out the property and value cells.
address@hidden defspec
address@hidden defmac
 
 @node Creating Symbols
 @section Creating Symbols
@@ -4259,7 +4259,7 @@
 implements structures as vectors (or lists upon request) with a
 special ``tag'' symbol to identify them.
 
address@hidden cl-defstruct name address@hidden
address@hidden cl-defstruct name address@hidden
 The @code{cl-defstruct} form defines a new structure type called
 @var{name}, with the specified @var{slots}.  (The @var{slots}
 may begin with a string which documents the structure type.)
@@ -4563,7 +4563,7 @@
 specifies a number of slots to be skipped between the last slot
 of the included type and the first new slot.
 @end table
address@hidden defspec
address@hidden defmac
 
 Except as noted, the @code{cl-defstruct} facility of this package is
 entirely compatible with that of Common Lisp.
@@ -4582,7 +4582,7 @@
 away the following assertions.  Because assertions might be optimized
 away, it is a bad idea for them to include side-effects.
 
address@hidden cl-assert test-form [show-args string address@hidden
address@hidden cl-assert test-form [show-args string address@hidden
 This form verifies that @var{test-form} is true (i.e., evaluates to
 a address@hidden value).  If so, it returns @code{nil}.  If the test
 is not satisfied, @code{cl-assert} signals an error.
@@ -4606,9 +4606,9 @@
 which can be @code{setf}'d by the user before continuing from the
 error.  Since Emacs Lisp does not support continuable errors, it
 makes no sense to specify @var{places}.
address@hidden defspec
address@hidden defmac
 
address@hidden cl-check-type form type [string]
address@hidden cl-check-type form type [string]
 This form verifies that @var{form} evaluates to a value of type
 @var{type}.  If so, it returns @code{nil}.  If not, @code{cl-check-type}
 signals a @code{wrong-type-argument} error.  The default error message
@@ -4627,7 +4627,7 @@
 must be a @var{place} suitable for use by @code{setf}, because
 @code{check-type} signals a continuable error that allows the
 user to modify @var{place}.
address@hidden defspec
address@hidden defmac
 
 @node Efficiency Concerns
 @appendix Efficiency Concerns
@@ -4660,12 +4660,10 @@
 @emph{Interpreted} code, on the other hand, must expand these macros
 every time they are executed.  For this reason it is strongly
 recommended that code making heavy use of macros be compiled.
address@hidden FIXME why are they not labelled as macros?
-(The features labeled ``Special Form'' instead of ``Function'' in
-this manual are macros.)  A loop using @code{cl-incf} a hundred times
-will execute considerably faster if compiled, and will also
-garbage-collect less because the macro expansion will not have
-to be generated, used, and thrown away a hundred times.
+A loop using @code{cl-incf} a hundred times will execute considerably
+faster if compiled, and will also garbage-collect less because the
+macro expansion will not have to be generated, used, and thrown away a
+hundred times.
 
 You can find out how a macro expands by using the
 @code{cl-prettyexpand} function.