bug#57263: 29.0.50; Obsolete documentation of `cl-symbol-macrolet'

bug#57263: 29.0.50; Obsolete documentation of `cl-symbol-macrolet'

[Wing Hei Chan]

The documentation of `cl-symbol-macrolet' fails to reflect the changes
in "Fix bug#26073", that is, `let'-bindings shadow symbol macro
bindings.

bug#57263: 29.0.50; Obsolete documentation of `cl-symbol-macrolet'

[Eli Zaretskii]

> Date: Wed, 17 Aug 2022 18:26:44 +0800
> From: Wing Hei Chan <whmunkchan@outlook.com>
> 
> The documentation of `cl-symbol-macrolet' fails to reflect the changes
> in "Fix bug#26073", that is, `let'-bindings shadow symbol macro
> bindings.

Stefan, could you please fix the documentation, or suggest how it
should be fixed?

Thanks.

bug#57263: 29.0.50; Obsolete documentation of `cl-symbol-macrolet'

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> Stefan, could you please fix the documentation, or suggest how it
> should be fixed?

Does the patch below seem readable to you?


        Stefan


diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index 07c19e37ce4..a7548bb1f8a 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -1381,19 +1381,10 @@ Macro Bindings
 
 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{cl-letf} or @code{cl-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,
-such shadowing does not occur, even when @code{lexical-binding} is
-@c See https://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}.
+@code{(setf foo 4)}, which in turn expands to @code{(setf (car bar)
+4)}.  A @code{let} (or @code{let*}, @code{lambda}, ...) binding of
+the same symbol will locally shadow the symbol macro as is the case in
+Common Lisp.
 
 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

bug#57263: 29.0.50; Obsolete documentation of `cl-symbol-macrolet'

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Wing Hei Chan <whmunkchan@outlook.com>,  57263@debbugs.gnu.org
> Date: Thu, 18 Aug 2022 10:08:10 -0400
> 
> > Stefan, could you please fix the documentation, or suggest how it
> > should be fixed?
> 
> Does the patch below seem readable to you?

LGTM, thanks.

bug#57263: 29.0.50; Obsolete documentation of `cl-symbol-macrolet'

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> Does the patch below seem readable to you?
> LGTM, thanks.

Installed,


        Stefan