[Emacs-diffs] /srv/bzr/emacs/trunk r110747: Document cl-flet and cl-labels in doc/misc/cl.texi

[Glenn Morris]

------------------------------------------------------------
revno: 110747
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2012-10-31 00:25:18 -0700
message:
  Document cl-flet and cl-labels in doc/misc/cl.texi
  
  * doc/misc/cl.texi (Function Bindings): Update for cl-flet and cl-labels.
  (Obsolete Lexical Binding): Rename section from "Lexical Bindings".
  (Obsolete Macros): Rename section from "Obsolete Lexical Macros".
  Reword, and add details of flet and labels.
  
  * etc/NEWS: Related markup.
modified:
  doc/misc/ChangeLog
  doc/misc/cl.texi
  etc/NEWS

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-10-30 08:03:22 +0000
+++ b/doc/misc/ChangeLog        2012-10-31 07:25:18 +0000
@@ -1,3 +1,10 @@
+2012-10-31  Glenn Morris  <address@hidden>
+
+       * cl.texi (Function Bindings): Update for cl-flet and cl-labels.
+       (Obsolete Lexical Binding): Rename section from "Lexical Bindings".
+       (Obsolete Macros): Rename section from "Obsolete Lexical Macros".
+       Reword, and add details of flet and labels.
+
 2012-10-30  Glenn Morris  <address@hidden>
 
        * cl.texi (Modify Macros): Update for cl-letf changes.

=== modified file 'doc/misc/cl.texi'
--- a/doc/misc/cl.texi  2012-10-30 19:23:13 +0000
+++ b/doc/misc/cl.texi  2012-10-31 07:25:18 +0000
@@ -820,12 +820,10 @@
 standard @code{setf} facility, and a number of looping and conditional
 constructs.
 
address@hidden FIXME
address@hidden flet is not cl-flet.
 @menu
 * Assignment::             The @code{cl-psetq} form.
 * Generalized Variables::  Extensions to generalized variables.
-* Variable Bindings::      @code{cl-progv}, @code{flet}, @code{cl-macrolet}.
+* Variable Bindings::      @code{cl-progv}, @code{cl-flet}, @code{cl-macrolet}.
 * Conditionals::           @code{cl-case}, @code{cl-typecase}.
 * Blocks and Exits::       @code{cl-block}, @code{cl-return}, 
@code{cl-return-from}.
 * Iteration::              @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, 
@code{cl-do-symbols}.
@@ -1244,7 +1242,7 @@
 
 @menu
 * Dynamic Bindings::     The @code{cl-progv} form.
-* Function Bindings::    @code{flet} and @code{labels}.
+* Function Bindings::    @code{cl-flet} and @code{cl-labels}.
 * Macro Bindings::       @code{cl-macrolet} and @code{cl-symbol-macrolet}.
 @end menu
 
@@ -1275,30 +1273,25 @@
 These forms make @code{let}-like bindings to functions instead
 of variables.
 
address@hidden flet (address@hidden) address@hidden
address@hidden cl-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}
 @address@hidden)}, which defines a function exactly as if
 it were a @code{cl-defun} form.  The function @var{name} is defined
-accordingly for the duration of the body of the @code{flet}; then
+accordingly for the duration of the body of the @code{cl-flet}; then
 the old function definition, or lack thereof, is restored.
 
-While @code{flet} in Common Lisp establishes a lexical binding of
address@hidden, 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
+You can use @code{cl-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
+function cell, and so will not be affected by @code{cl-flet}.  For
 example,
 
 @example
-(flet ((message (&rest args) (push args saved-msgs)))
-  (do-something))
+(cl-flet ((message (&rest args) (push args saved-msgs)))
+    (do-something))
 @end example
 
 This code attempts to replace the built-in function @code{message}
@@ -1310,34 +1303,26 @@
 direct C-language calls to the message routines rather than going
 through the Lisp @code{message} function.
 
address@hidden 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
+Functions defined by @code{cl-flet} may use the full Common Lisp
 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}.
 @end defmac
 
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
address@hidden 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.)
address@hidden cl-labels (address@hidden) address@hidden
+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
address@hidden is address@hidden
address@hidden,,,elisp,GNU Emacs Lisp Reference Manual}, and
address@hidden Lexical Binding,,,elisp,GNU Emacs Lisp Reference Manual}.
 
 Lexical scoping means that all references to the named
 functions must appear physically within the body of the
address@hidden form.  References may appear both in the body
address@hidden 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.
address@hidden form.  References may appear both in the body
address@hidden of @code{cl-labels} itself, and in the bodies of
+the functions themselves.  Thus, @code{cl-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
@@ -1351,7 +1336,7 @@
 These forms create local macros and ``symbol macros''.
 
 @defmac cl-macrolet (address@hidden) address@hidden
-This form is analogous to @code{flet}, but for macros instead of
+This form is analogous to @code{cl-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,
 and macro-expander forms).  The macro is defined accordingly for
@@ -4598,7 +4583,7 @@
 called.
 
 Internally, this package uses lexical binding so that such problems do
-not occur.  @xref{Lexical Bindings}, for a description of the obsolete
+not occur.  @xref{Obsolete Lexical Binding}, for a description of the obsolete
 @code{lexical-let} form that emulates a Common Lisp-style lexical
 binding when dynamic binding is in use.
 
@@ -4750,13 +4735,13 @@
 in exactly the same way.
 
 @menu
-* Lexical Bindings::            An approximation of lexical binding.
-* Obsolete Lexical Macros::     Obsolete macros using lexical-let.
+* Obsolete Lexical Binding::    An approximation of lexical binding.
+* Obsolete Macros::             Obsolete macros.
 * Obsolete Setf Customization:: Obsolete ways to customize setf.
 @end menu
 
address@hidden Lexical Bindings
address@hidden Lexical Bindings
address@hidden Obsolete Lexical Binding
address@hidden Obsolete Lexical Binding
 
 The following macros are extensions to Common Lisp, where all bindings
 are lexical unless declared otherwise.  These features are likewise
@@ -4871,21 +4856,43 @@
 are made sequentially in the manner of @code{let*}.
 @end defmac
 
address@hidden Obsolete Lexical Macros
address@hidden Macros Defined Using Lexical-Let
address@hidden Obsolete Macros
address@hidden Obsolete Macros
 
-The following macros are defined using @code{lexical-let}.
-They are replaced by versions with a @samp{cl-} prefix that use true
-lexical binding (and hence rely on @code{lexical-binding} being set to
address@hidden in code using them).
+The following macros are obsolete, and are replaced by versions with
+a @samp{cl-} prefix that do not behave in exactly the same way.
+Consequently, the @file{cl.el} versions are not simply aliases to the
address@hidden versions.
 
 @defmac flet (address@hidden) address@hidden
-Replaced by @code{cl-flet} (@pxref{Function Bindings})
-or @code{cl-letf} (@pxref{Modify Macros}).
+This macro is replaced by @code{cl-flet} (@pxref{Function Bindings}),
+which behaves the same way as Common Lisp's @code{flet}.
+This @code{flet} takes the same arguments as @code{cl-flet}, but does
+not behave in precisely the same way.
+
+While @code{flet} in Common Lisp establishes a lexical function
+binding, this @code{flet} makes a dynamic binding (it dates from a
+time before Emacs had lexical binding).  The result is
+that @code{flet} affects indirect calls to a function as well as calls
+directly inside the @code{flet} form itself.
+
address@hidden Bug#411.
+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.
address@hidden Or cl-flet.
address@hidden In such cases, use @code{labels} instead.
 @end defmac
 
 @defmac labels (address@hidden) address@hidden
-Replaced by @code{cl-labels} (@pxref{Function Bindings}).
+This macro is replaced by @code{cl-labels} (@pxref{Function Bindings}),
+which behaves the same way as Common Lisp's @code{labels}.
+This @code{labels} takes the same arguments as @code{cl-labels}, but
+does not behave in precisely the same way.
+
+This version of @code{labels} uses the obsolete @code{lexical-let}
+form (@pxref{Obsolete Lexical Binding}), rather than the true
+lexical binding that @code{cl-labels} uses.
 @end defmac
 
 @defmac letf (address@hidden) address@hidden

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-10-30 07:34:37 +0000
+++ b/etc/NEWS  2012-10-31 07:25:18 +0000
@@ -315,9 +315,11 @@
 The old `cl' is now deprecated and is just a bunch of aliases that
 provide the old non-prefixed names.
 
++++
 *** `cl-flet' is not like `flet' (which is deprecated).
 Instead it obeys the behavior of Common-Lisp's `flet'.
 
++++
 *** `cl-labels' is slightly different from `labels'.
 The difference is that it relies on the `lexical-binding' machinery (as opposed
 to the `lexical-let' machinery used previously) to capture definitions in