From 9f2881afe2d7b12ddf30c5e5c33073f647c763f9 Mon Sep 17 00:00:00 2001
From: Glenn Morris <rgm@gnu.org>
Date: Thu, 1 Nov 2012 00:16:32 -0700
Subject: [PATCH] More edits for cl.texi
* doc/misc/cl.texi: More copyedits, plus:
(Time of Evaluation, Iteration): Add xref to Emacs Lisp manual.
(Macro Bindings, Blocks and Exits): Acknowledge existence of lexical-binding.
(Iteration): Mainly defer to doc of standard dolist, dotimes.
---
doc/misc/ChangeLog | 4 +++
doc/misc/cl.texi | 89 +++++++++++++++++++++++-----------------------
2 files changed, 48 insertions(+), 45 deletions(-)
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 38dcdf507c4..d719a02e32e 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,6 +1,10 @@
2012-11-01 Glenn Morris <rgm@gnu.org>
* cl.texi: General copyedits for style, line-breaks, etc.
+ (Time of Evaluation, Iteration): Add xref to Emacs Lisp manual.
+ (Macro Bindings, Blocks and Exits):
+ Acknowledge existence of lexical-binding.
+ (Iteration): Mainly defer to doc of standard dolist, dotimes.
2012-10-31 Glenn Morris <rgm@gnu.org>
diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index 392ee61be51..4a728049ce8 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -300,6 +300,7 @@ calls to it may be expanded into in-line code by the byte compiler.
This is analogous to the @code{defsubst} form;
@code{cl-defsubst} uses a different method (compiler macros) which
works in all versions of Emacs, and also generates somewhat more
+@c Really?
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.
@@ -309,7 +310,8 @@ etc., to be done at compile-time whenever possible.
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
-described in Steele. The @code{&whole} keyword is supported only
+described in Steele's book @cite{Common Lisp, the Language}.
+The @code{&whole} keyword is supported only
within destructured lists (see below); top-level @code{&whole}
cannot be implemented with the current Emacs Lisp interpreter.
The macro expander body is enclosed in an implicit block called
@@ -462,7 +464,7 @@ Argument lists support @dfn{destructuring}. In Common Lisp,
destructuring is only allowed with @code{defmacro}; this package
allows it with @code{cl-defun} and other argument lists as well.
In destructuring, any argument variable (@var{var} in the above
-diagram) can be replaced by a list of variables, or more generally,
+example) can be replaced by a list of variables, or more generally,
a recursive argument list. The corresponding argument value must
be a list whose elements match this recursive argument list.
For example:
@@ -584,12 +586,12 @@ certain top-level forms, like @code{defmacro} (sort-of) and
@end defmac
Emacs includes two special forms related to @code{cl-eval-when}.
+@xref{Eval During Compile,,,elisp,GNU Emacs Lisp Reference Manual}.
One of these, @code{eval-when-compile}, is not quite equivalent to
any @code{cl-eval-when} construct and is described below.
The other form, @code{(eval-and-compile @dots{})}, is exactly
-equivalent to @samp{(cl-eval-when (compile load eval) @dots{})} and
-so is not itself defined by this package.
+equivalent to @samp{(cl-eval-when (compile load eval) @dots{})}.
@defmac eval-when-compile forms@dots{}
The @var{forms} are evaluated at compile-time; at execution time,
@@ -703,6 +705,7 @@ integers in the range from 0 to 255.
@item
The type symbol @code{float} uses the @code{cl-floatp-safe} predicate
defined by this package rather than @code{floatp}, so it will work
+@c FIXME are any such platforms still relevant?
correctly even in Emacs versions without floating-point support.
@item
@@ -781,8 +784,8 @@ type specifier could be implemented if desired; this package does
not implement @code{unsigned-byte} by default.
@end defmac
-The @code{cl-typecase} and @code{cl-check-type} macros also use type
-names. @xref{Conditionals}. @xref{Assertions}. The @code{cl-map},
+The @code{cl-typecase} (@pxref{Conditionals}) and @code{cl-check-type}
+(@pxref{Assertions}) macros also use type names. The @code{cl-map},
@code{cl-concatenate}, and @code{cl-merge} functions take type-name
arguments to specify the type of sequence to return. @xref{Sequences}.
@@ -1324,7 +1327,7 @@ differently. @xref{Obsolete Macros}.
The @code{cl-labels} form is like @code{cl-flet}, except that
the function bindings can be recursive. The scoping is lexical,
but you can only capture functions in closures if
-@code{lexical-binding} is non-@code{nil}.
+@code{lexical-binding} is @code{t}.
@xref{Closures,,,elisp,GNU Emacs Lisp Reference Manual}, and
@ref{Using Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
@@ -1356,12 +1359,8 @@ arguments to @code{cl-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{cl-macrolet}.
-@c FIXME this should be modified to say ``even when lexical-binding
-@c is code{nil}'', but is that true? The doc of cl-macrolet just
-@c refers us to cl-flet, which refers to cl-labels, which says that it
-@c behaves differently according to whether l-b is true or not.
-Because of the nature of macros, @code{cl-macrolet} is lexically
-scoped even in Emacs Lisp: The @code{cl-macrolet} binding will
+Because of the nature of macros, @code{cl-macrolet} is always lexically
+scoped. The @code{cl-macrolet} binding will
affect only calls that appear physically within the body
@var{forms}, possibly after expansion of other macros in the
body.
@@ -1388,12 +1387,15 @@ I.e., @code{(setq foo 4)} in the above would be equivalent to
Likewise, a @code{let} or @code{let*} binding a symbol macro is
treated like a @code{cl-letf} or @code{cl-letf*}. This differs from true
-@c FIXME does it work like this in Emacs with lexical-binding = t?
Common Lisp, where the rules of lexical scoping cause a @code{let}
-binding to shadow a @code{cl-symbol-macrolet} binding. In this package,
-@c FIXME obsolete.
-only @code{lexical-let} and @code{lexical-let*} will shadow a symbol
-macro.
+binding to shadow a @code{symbol-macrolet} binding. In this package,
+such shadowing does not occur, even when @code{lexical-binding} is
+@c See http://debbugs.gnu.org/12119
+@code{t}. (This behavior predates the addition of lexical binding to
+Emacs Lisp, and may change in future to respect @code{lexical-binding}.)
+At present in this package, only @code{lexical-let} and
+@code{lexical-let*} will shadow a symbol macro. @xref{Obsolete
+Lexical Binding}.
There is no analogue of @code{defmacro} for symbol macros; all symbol
macros are local. A typical use of @code{cl-symbol-macrolet} is in the
@@ -1401,7 +1403,7 @@ expansion of another macro:
@example
(cl-defmacro my-dolist ((x list) &rest body)
- (let ((var (gensym)))
+ (let ((var (cl-gensym)))
(list 'cl-loop 'for var 'on list 'do
(cl-list* 'cl-symbol-macrolet
(list (list x (list 'car var)))
@@ -1516,8 +1518,8 @@ simply returning @code{nil}.
@noindent
Common Lisp @dfn{blocks} provide a non-local exit mechanism very
-similar to @code{catch} and @code{throw}, but lexically rather than
-dynamically scoped. This package actually implements @code{cl-block}
+similar to @code{catch} and @code{throw}, with lexical scoping.
+This package actually implements @code{cl-block}
in terms of @code{catch}; however, the lexical scoping allows the
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.
@@ -1532,11 +1534,12 @@ a @code{cl-return-from} occurs.
The @code{cl-block}/@code{cl-return-from} mechanism is quite similar to
the @code{catch}/@code{throw} mechanism. The main differences are
that block @var{name}s are unevaluated symbols, rather than forms
-(such as quoted symbols) which evaluate to a tag at run-time; and
-also that blocks are lexically scoped whereas @code{catch}/@code{throw}
-are dynamically scoped. This means that functions called from the
-body of a @code{catch} can also @code{throw} to the @code{catch},
-but the @code{cl-return-from} referring to a block name must appear
+(such as quoted symbols) that evaluate to a tag at run-time; and
+also that blocks are always lexically scoped.
+In a dynamically scoped @code{catch}, functions called from the
+@code{catch} body can also @code{throw} to the @code{catch}. This
+is not an option for @code{cl-block}, where
+the @code{cl-return-from} referring to a block name must appear
physically within the @var{forms} that make up the body of the block.
They may not appear within other called functions, although they may
appear within macro expansions or @code{lambda}s in the body. Block
@@ -1546,20 +1549,20 @@ In true Common Lisp, @code{defun} and @code{defmacro} surround
the function or expander bodies with implicit blocks with the
same name as the function or macro. This does not occur in Emacs
Lisp, but this package provides @code{cl-defun} and @code{cl-defmacro}
-forms which do create the implicit block.
+forms, which do create the implicit block.
The Common Lisp looping constructs defined by this package,
such as @code{cl-loop} and @code{cl-dolist}, also create implicit blocks
just as in Common Lisp.
-Because they are implemented in terms of Emacs Lisp @code{catch}
+Because they are implemented in terms of Emacs Lisp's @code{catch}
and @code{throw}, blocks have the same overhead as actual
@code{catch} constructs (roughly two function calls). However,
the optimizing byte compiler will optimize away the @code{catch}
if the block does
not in fact contain any @code{cl-return} or @code{cl-return-from} calls
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
+functions that don't use @code{cl-return} don't pay the overhead to
support it.
@end defmac
@@ -1581,8 +1584,8 @@ themselves in @code{nil} blocks.
@noindent
The macros described here provide more sophisticated, high-level
-looping constructs to complement Emacs Lisp's basic @code{while}
-loop.
+looping constructs to complement Emacs Lisp's basic loop forms
+(@pxref{Iteration,,,elisp,GNU Emacs Lisp Reference Manual}).
@defmac cl-loop forms@dots{}
This package supports both the simple, old-style meaning of
@@ -1646,7 +1649,7 @@ around the loop. If @var{init} is also omitted it defaults to
in place of @samp{(@var{var})}, again following the analogy with
@code{let}.
-This example (from Steele) illustrates a loop which applies the
+This example (from Steele) illustrates a loop that applies the
function @code{f} to successive pairs of values from the lists
@code{foo} and @code{bar}; it is equivalent to the call
@code{(cl-mapcar 'f foo bar)}. Note that this loop has no body
@@ -1683,23 +1686,19 @@ Here is another way to write the above loop:
@end defmac
@defmac cl-dolist (var list [result]) forms@dots{}
-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
-turn. Finally, the @var{result} form (or @code{nil}) is evaluated
-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.
+This is exactly like the standard Emacs Lisp macro @code{dolist},
+but surrounds the loop with an implicit @code{nil} block.
@end defmac
@defmac cl-dotimes (var count [result]) forms@dots{}
-This is a more specialized loop which iterates a specified number
-of times. The body is executed with @var{var} bound to the integers
+This is exactly like the standard Emacs Lisp macro @code{dotimes},
+but surrounds the loop with an implicit @code{nil} block.
+The body is executed with @var{var} bound to the integers
from zero (inclusive) to @var{count} (exclusive), in turn. Then
+@c FIXME lispref does not state this part explicitly, could move this there.
the @code{result} form is evaluated with @var{var} bound to the total
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.
+to get the return value for the loop form.
@end defmac
@defmac cl-do-symbols (var [obarray [result]]) forms@dots{}
@@ -1798,8 +1797,8 @@ break out of the loop.)
The following sections give some examples of the Loop Macro in
action, and describe the particular loop clauses in great detail.
-Consult the second edition of Steele's @dfn{Common Lisp, the Language},
-for additional discussion and examples of the @code{loop} macro.
+Consult the second edition of Steele for additional discussion
+and examples of the @code{loop} macro.
@node Loop Examples
@subsection Loop Examples
--
2.39.5