bug#11407: 24.0.96; Doc for lexical binding in Elisp manual

[Drew Adams]

> tags 11407 wontfix
> thanks
> 
> > With the arrival of lexical scoping in Emacs 24, it is even more
> > important, not less, that the Elisp manual document
> > `lexical-let(*)'.
> 
> Why?  I intend to mark lexical-let as obsolete in 24.2.

Why consider it obsolete?

It gives users a choice:

a. Make a file use lexical binding by default (e.g., using a file-level
declaration, as now), and use defvars to override that to get dynamic binding
for certain vars.

b. Let a file use dynamic binding by default, and use `lexical-let' to override
that and get lexical binding for certain vars.

There is *lots* of code that expects its file to use dynamic binding in general.
And some of that code might need lexical binding here or there.  Especially
files containing code that tries to be compatible across multiple Emacs
versions.

> > (defun foo (arg)
> >   (lexical-let ((beta  (something)))
> >     #'(lambda () (alpha arg beta))))
>  
> > Does the closure here treat ARG as lexically bound by the 
> > `defun', or is ARG a dynamically bound free var in the lambda?
> > I believe the answer is that the value of ARG encapsulated
> > in the closure is the value that is passed as argument to foo.
> 
> The behavior is largely the result of some accidental design decisions
> taken years ago in the implementation of lexical-let, and I have no
> intention to document the result.

Surely, if `lexical-let' is to be used by users (see above), they deserve a
description of its behavior in this regard.  The behavior is, as I think you're
agreeing, not obvious.