-@item
-A list of @dfn{value forms} corresponding to the temporary variables
-above. The temporary variables will be bound to these value forms
-as the first step of any operation on the generalized variable.
-
-@item
-A list of exactly one @dfn{store variable} (generally obtained
-from a call to @code{gensym}).
-
-@item
-A Lisp form which stores the contents of the store variable into
-the generalized variable, assuming the temporaries have been
-bound as described above.
-
-@item
-A Lisp form which accesses the contents of the generalized variable,
-assuming the temporaries have been bound.
-@end enumerate
-
-This is exactly like the Common Lisp macro of the same name,
-except that the method returns a list of five values rather
-than the five values themselves, since Emacs Lisp does not
-support Common Lisp's notion of multiple return values.
-
-Once again, the @var{forms} may begin with a documentation string.
-
-A setf-method should be maximally conservative with regard to
-temporary variables. In the setf-methods generated by
-@code{defsetf}, the second return value is simply the list of
-arguments in the place form, and the first return value is a
-list of a corresponding number of temporary variables generated
-by @code{gensym}. Macros like @code{setf} and @code{incf} which
-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.
-@end defspec
-
-@defun get-setf-method place &optional env
-This function returns the setf-method for @var{place}, by
-invoking the definition previously recorded by @code{defsetf}
-or @code{define-setf-method}. The result is a list of five
-values as described above. You can use this function to build
-your own @code{incf}-like modify macros. (Actually, it is
-better to use the internal functions @code{cl-setf-do-modify}
-and @code{cl-setf-do-store}, which are a bit easier to use and
-which also do a number of optimizations; consult the source
-code for the @code{incf} function for a simple example.)
-
-The argument @var{env} specifies the ``environment'' to be
-passed on to @code{macroexpand} if @code{get-setf-method} should
-need to expand a macro in @var{place}. It should come from
-an @code{&environment} argument to the macro or setf-method
-that called @code{get-setf-method}.
-
-See also the source code for the setf-methods for @code{apply}
-and @code{substring}, each of which works by calling
-@code{get-setf-method} on a simpler case, then massaging
-the result in various ways.
-@end defun
-
-Modern Common Lisp defines a second, independent way to specify
-the @code{setf} behavior of a function, namely ``@code{setf}
-functions'' whose names are lists @code{(setf @var{name})}
-rather than symbols. For example, @code{(defun (setf foo) @dots{})}
-defines the function that is used when @code{setf} is applied to
-@code{foo}. This package does not currently support @code{setf}
-functions. In particular, it is a compile-time error to use
-@code{setf} on a form which has not already been @code{defsetf}'d
-or otherwise declared; in newer Common Lisps, this would not be
-an error since the function @code{(setf @var{func})} might be
-defined later.
-
-@iftex
-@secno=4
-@end iftex
-
-@node Variable Bindings, Conditionals, Generalized Variables, Control Structure
-@section Variable Bindings
-
-@noindent
-These Lisp forms make bindings to variables and function names,
-analogous to Lisp's built-in @code{let} form.
-
-@xref{Modify Macros}, for the @code{letf} and @code{letf*} forms which
-are also related to variable bindings.
-
-@menu
-* Dynamic Bindings:: The `progv' form
-* Lexical Bindings:: `lexical-let' and lexical closures
-* Function Bindings:: `flet' and `labels'
-* Macro Bindings:: `macrolet' and `symbol-macrolet'
-@end menu
-
-@node Dynamic Bindings, Lexical Bindings, Variable Bindings, Variable Bindings
-@subsection Dynamic Bindings
-
-@noindent
-The standard @code{let} form binds variables whose names are known
-at compile-time. The @code{progv} form provides an easy way to
-bind variables whose names are computed at run-time.
-
-@defspec progv symbols values forms@dots{}
-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
-of symbols and values, respectively. The symbols are bound to the
-corresponding values for the duration of the body @var{form}s.
-If @var{values} is shorter than @var{symbols}, the last few symbols
-are made unbound (as if by @code{makunbound}) inside the body.
-If @var{symbols} is shorter than @var{values}, the excess values
-are ignored.
-@end defspec
-
-@node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings
-@subsection Lexical Bindings
-
-@noindent
-The @dfn{CL} package defines the following macro which
-more closely follows the Common Lisp @code{let} form:
-
-@defspec lexical-let (bindings@dots{}) forms@dots{}
-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
-within the body of the @code{lexical-let} (after macro expansion)
-may refer to the bound variables.
-
-@example
-(setq a 5)
-(defun foo (b) (+ a b))
-(let ((a 2)) (foo a))
- @result{} 4
-(lexical-let ((a 2)) (foo a))
- @result{} 7
-@end example
-
-@noindent
-In this example, a regular @code{let} binding of @code{a} actually
-makes a temporary change to the global variable @code{a}, so @code{foo}
-is able to see the binding of @code{a} to 2. But @code{lexical-let}
-actually creates a distinct local variable @code{a} for use within its
-body, without any effect on the global variable of the same name.
-
-The most important use of lexical bindings is to create @dfn{closures}.
-A closure is a function object that refers to an outside lexical
-variable. For example:
-
-@example
-(defun make-adder (n)
- (lexical-let ((n n))
- (function (lambda (m) (+ n m)))))
-(setq add17 (make-adder 17))
-(funcall add17 4)
- @result{} 21
-@end example
-
-@noindent
-The call @code{(make-adder 17)} returns a function object which adds
-17 to its argument. If @code{let} had been used instead of
-@code{lexical-let}, the function object would have referred to the
-global @code{n}, which would have been bound to 17 only during the
-call to @code{make-adder} itself.
-
-@example
-(defun make-counter ()
- (lexical-let ((n 0))
- (function* (lambda (&optional (m 1)) (incf n m)))))
-(setq count-1 (make-counter))
-(funcall count-1 3)
- @result{} 3
-(funcall count-1 14)
- @result{} 17
-(setq count-2 (make-counter))
-(funcall count-2 5)
- @result{} 5
-(funcall count-1 2)
- @result{} 19
-(funcall count-2)
- @result{} 6
-@end example
-
-@noindent
-Here we see that each call to @code{make-counter} creates a distinct
-local variable @code{n}, which serves as a private counter for the
-function object that is returned.
-
-Closed-over lexical variables persist until the last reference to
-them goes away, just like all other Lisp objects. For example,
-@code{count-2} refers to a function object which refers to an
-instance of the variable @code{n}; this is the only reference
-to that variable, so after @code{(setq count-2 nil)} the garbage
-collector would be able to delete this instance of @code{n}.
-Of course, if a @code{lexical-let} does not actually create any
-closures, then the lexical variables are free as soon as the
-@code{lexical-let} returns.
-
-Many closures are used only during the extent of the bindings they
-refer to; these are known as ``downward funargs'' in Lisp parlance.
-When a closure is used in this way, regular Emacs Lisp dynamic
-bindings suffice and will be more efficient than @code{lexical-let}
-closures:
-
-@example
-(defun add-to-list (x list)
- (mapcar (lambda (y) (+ x y))) list)
-(add-to-list 7 '(1 2 5))
- @result{} (8 9 12)
-@end example
-
-@noindent
-Since this lambda is only used while @code{x} is still bound,
-it is not necessary to make a true closure out of it.
-
-You can use @code{defun} or @code{flet} inside a @code{lexical-let}
-to create a named closure. If several closures are created in the
-body of a single @code{lexical-let}, they all close over the same
-instance of the lexical variable.
-
-The @code{lexical-let} form is an extension to Common Lisp. In
-true Common Lisp, all bindings are lexical unless declared otherwise.
-@end defspec
-
-@defspec lexical-let* (bindings@dots{}) forms@dots{}
-This form is just like @code{lexical-let}, except that the bindings
-are made sequentially in the manner of @code{let*}.
-@end defspec
-
-@node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings
-@subsection Function Bindings
-
-@noindent
-These forms make @code{let}-like bindings to functions instead
-of variables.
-
-@defspec flet (bindings@dots{}) forms@dots{}
-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}
-@var{forms}@dots{})}, which defines a function exactly as if
-it were a @code{defun*} form. The function @var{name} is defined
-accordingly for the duration of the body of the @code{flet}; then
-the old function definition, or lack thereof, is restored.
-
-While @code{flet} in Common Lisp establishes a lexical binding of
-@var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The
-result is that @code{flet} affects indirect calls to a function as
-well as calls directly inside the @code{flet} form itself.
-
-You can use @code{flet} to disable or modify the behavior of a
-function in a temporary fashion. This will even work on Emacs
-primitives, although note that some calls to primitive functions
-internal to Emacs are made without going through the symbol's
-function cell, and so will not be affected by @code{flet}. For
-example,
-
-@example
-(flet ((message (&rest args) (push args saved-msgs)))
- (do-something))
-@end example
-
-This code attempts to replace the built-in function @code{message}
-with a function that simply saves the messages in a list rather
-than displaying them. The original definition of @code{message}
-will be restored after @code{do-something} exits. This code will
-work fine on messages generated by other Lisp code, but messages
-generated directly inside Emacs will not be caught since they make
-direct C-language calls to the message routines rather than going
-through the Lisp @code{message} function.
-
-@c Bug#411.
-Also note that many primitives (e.g. @code{+}) have special byte-compile
-handling. Attempts to redefine such functions using @code{flet} will
-fail if byte-compiled. In such cases, use @code{labels} instead.
-
-Functions defined by @code{flet} may use the full Common Lisp
-argument notation supported by @code{defun*}; also, the function
-body is enclosed in an implicit block as if by @code{defun*}.
-@xref{Program Structure}.
-@end defspec
-
-@defspec labels (bindings@dots{}) forms@dots{}
-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
-@code{labels} make lexical bindings of slightly different sorts;
-since Emacs Lisp is dynamically bound by default, it seemed
-more appropriate for @code{flet} also to use dynamic binding.
-The @code{labels} form, with its lexical binding, is fully
-compatible with Common Lisp.)
-
-Lexical scoping means that all references to the named
-functions must appear physically within the body of the
-@code{labels} form. References may appear both in the body
-@var{forms} of @code{labels} itself, and in the bodies of
-the functions themselves. Thus, @code{labels} can define
-local recursive functions, or mutually-recursive sets of
-functions.
-
-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}.
-@end defspec
-
-@node Macro Bindings, , Function Bindings, Variable Bindings
-@subsection Macro Bindings
-
-@noindent
-These forms create local macros and ``symbol macros.''
-
-@defspec macrolet (bindings@dots{}) forms@dots{}
-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{defmacro*} (i.e., a macro name, argument list,
-and macro-expander forms). The macro is defined accordingly for
-use within the body of the @code{macrolet}.
-
-Because of the nature of macros, @code{macrolet} is lexically
-scoped even in Emacs Lisp: The @code{macrolet} binding will
-affect only calls that appear physically within the body
-@var{forms}, possibly after expansion of other macros in the
-body.
-@end defspec
-
-@defspec symbol-macrolet (bindings@dots{}) forms@dots{}
-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})};
-any reference to @var{var} within the body @var{forms} is
-replaced by @var{expansion}.
-
-@example
-(setq bar '(5 . 9))
-(symbol-macrolet ((foo (car bar)))
- (incf foo))
-bar
- @result{} (6 . 9)
-@end example
-
-A @code{setq} of a symbol macro is treated the same as a @code{setf}.
-I.e., @code{(setq foo 4)} in the above would be equivalent to
-@code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}.
-
-Likewise, a @code{let} or @code{let*} binding a symbol macro is
-treated like a @code{letf} or @code{letf*}. This differs from true
-Common Lisp, where the rules of lexical scoping cause a @code{let}
-binding to shadow a @code{symbol-macrolet} binding. In this package,
-only @code{lexical-let} and @code{lexical-let*} will shadow a symbol
-macro.
-
-There is no analogue of @code{defmacro} for symbol macros; all symbol
-macros are local. A typical use of @code{symbol-macrolet} is in the
-expansion of another macro:
-
-@example
-(defmacro* my-dolist ((x list) &rest body)
- (let ((var (gensym)))
- (list 'loop 'for var 'on list 'do
- (list* 'symbol-macrolet (list (list x (list 'car var)))
- body))))
-
-(setq mylist '(1 2 3 4))
-(my-dolist (x mylist) (incf x))
-mylist
- @result{} (2 3 4 5)
-@end example
-
-@noindent
-In this example, the @code{my-dolist} macro is similar to @code{dolist}
-(@pxref{Iteration}) except that the variable @code{x} becomes a true
-reference onto the elements of the list. The @code{my-dolist} call
-shown here expands to
-
-@example
-(loop for G1234 on mylist do
- (symbol-macrolet ((x (car G1234)))
- (incf x)))
-@end example
-
-@noindent
-which in turn expands to
-
-@example
-(loop for G1234 on mylist do (incf (car G1234)))
-@end example
-
-@xref{Loop Facility}, for a description of the @code{loop} macro.
-This package defines a nonstandard @code{in-ref} loop clause that
-works much like @code{my-dolist}.
-@end defspec
-
-@node Conditionals, Blocks and Exits, Variable Bindings, Control Structure
-@section Conditionals
-
-@noindent
-These conditional forms augment Emacs Lisp's simple @code{if},
-@code{and}, @code{or}, and @code{cond} forms.
-
-@defspec case keyform clause@dots{}
-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
-matches, the @code{case} form returns @code{nil}. The clauses are
-of the form
-
-@example
-(@var{keylist} @var{body-forms}@dots{})
-@end example
-
-@noindent
-where @var{keylist} is a list of key values. If there is exactly
-one value, and it is not a cons cell or the symbol @code{nil} or
-@code{t}, then it can be used by itself as a @var{keylist} without
-being enclosed in a list. All key values in the @code{case} form
-must be distinct. The final clauses may use @code{t} in place of
-a @var{keylist} to indicate a default clause that should be taken
-if none of the other clauses match. (The symbol @code{otherwise}
-is also recognized in place of @code{t}. To make a clause that
-matches the actual symbol @code{t}, @code{nil}, or @code{otherwise},
-enclose the symbol in a list.)
-
-For example, this expression reads a keystroke, then does one of
-four things depending on whether it is an @samp{a}, a @samp{b},
-a @key{RET} or @kbd{C-j}, or anything else.
-
-@example
-(case (read-char)
- (?a (do-a-thing))
- (?b (do-b-thing))
- ((?\r ?\n) (do-ret-thing))
- (t (do-other-thing)))
-@end example
-@end defspec
-
-@defspec ecase keyform clause@dots{}
-This macro is just like @code{case}, except that if the key does
-not match any of the clauses, an error is signaled rather than
-simply returning @code{nil}.
-@end defspec
-
-@defspec typecase keyform clause@dots{}
-This macro is a version of @code{case} that checks for types
-rather than values. Each @var{clause} is of the form
-@samp{(@var{type} @var{body}...)}. @xref{Type Predicates},
-for a description of type specifiers. For example,
-
-@example
-(typecase x
- (integer (munch-integer x))
- (float (munch-float x))
- (string (munch-integer (string-to-int x)))
- (t (munch-anything x)))
-@end example
-
-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.
-@end defspec
-
-@defspec etypecase keyform clause@dots{}
-This macro is just like @code{typecase}, except that if the key does
-not match any of the clauses, an error is signaled rather than
-simply returning @code{nil}.
-@end defspec
-
-@node Blocks and Exits, Iteration, Conditionals, Control Structure
-@section Blocks and Exits