bug#10872: 24.0.93; doc of `where-is-internal'

bug#10872: 24.0.93; doc of `where-is-internal'

[Drew Adams]

1. The doc string says nothing about `overriding-local-map', but that
now changes what a nil value searches.  The doc string is wrong in
saying that nil means search all currently active keymaps.
 
2. The doc string does not say that nil NO-REMAP also means return nil
if COMMAND will not be invoked by any key because it has been remapped.
This is as important as the other characteristic that is mentioned:
"don't search for key sequences that invoke a command which is remapped
to DEFINITION".  In fact, in the manual the latter is not even mentioned
explicitly, while the former is.  The manual is much clearer in this
regard, and no more verbose.
 
3. `(elisp) Scanning Keymaps' says, for NO-REMAP, that "if COMMAND won't
really be run", but it should say will not be invoked by any *key* (it
could be run by `M-x').
 
4. `(elisp) Scanning Keymaps' says to "pass" `(keymap)' if you want to
search only the global map.
 
4a. First, it should make it clear that it is _not_ about passing that
sexp/list, but rather about passing the value of that sexp,
i.e. evaluating that sexp as the arg.  IOW, its value is passed, not the
sexp/list itself.
 
4b. Second, this doc should say something about why it is preferable to
pass an empty keymap by evaluating that sexp, rather than passing the
global keymap by evaluating variable `global-map' or sexp
`(current-global-map)'.  This part of the doc is not clear at all.

In GNU Emacs 24.0.93.1 (i386-mingw-nt5.1.2600)
 of 2012-02-15 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'
 

bug#10872: 24.0.93; doc of `where-is-internal'

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

> 1. The doc string says nothing about `overriding-local-map', but that
> now changes what a nil value searches.  The doc string is wrong in
> saying that nil means search all currently active keymaps.

Fixed, thanks.

The discussion of the NO-REMAP argument to where-is-internal in the Lisp
manual and the docstring were out of date; that is also fixed now.