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

[Drew Adams]

With the arrival of lexical scoping in Emacs 24, it is even more
important, not less, that the Elisp manual document `lexical-let(*)'.
 
The `lexical-let(*)' doc string too could also be beefed up.  It says
only this:
 
 "Like `let', but lexically scoped.
  The main visible difference is that lambdas inside BODY will create
  lexical closures as in Common Lisp."
 
It should include something that lets users know whether such closures
close only the vars that are explicitly declared in the `lexical-let(*)'
or also the vars that are lexically available.  IOW, it should say just
what variables are encapsulated in the closures referred to.
 
E.g.:
 
(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 it
that the value of ARG encapsulated in the closure is the value that is
passed as argument to foo.  Whatever the correct answer is, it should be
made clear to users.
 
It would be fine to document this stuff together with the other info
about lexical bindings, in node (elisp) `Lexical Binding'.  But it
should be documented somewhere (whatever the exact behavior is).
 
 
 
In GNU Emacs 24.0.96.1 (i386-mingw-nt5.1.2600)
 of 2012-04-28 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --enable-checking --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include'