bug#4393: 23.1; doc string of accessible-keymaps

[Drew Adams]

emacs -Q
 
In *scratch* type this:
(accessible-keymaps (current-global-map))
 
Put point after the sexp, and do `C-u C-x C-e'.
 
You get the eval result inserted just after the sexp. The result has a
mouse-face property (highlight).
 
Put point at the beginning of the result (just after the initial
sexp). Hit RET - the display of the result changes between full and
abbreviated.
 
An aside: it took me a while to figure out what was happening, and why
RET didn't insert a newline here. (You can't use C-j to insert a
newline in *scratch*, so I'm in the habit of hitting RET.)
 
I wonder if something shouldn't be added to the doc for C-x C-e about
this. There is nothing that prepares the user for the effect
(highlighted sexp, hijacked mouse-2 behavior, so you can no longer
yank into the sexp, hijacked RET behavior, so you cannot shorten
lines, etc.). And there should be some explanation of how to turn OFF
this wonderful highlighting and RET/mouse-2 behavior.
 
Since it seems to be C-x C-e that has this effect, it is the doc of
C-x C-e that should cover this.
 
Anyway, on to the bug...
 
Search for [f2] in the result sexp. You'll find this:
([f2] . t). That's one of the entries in the alist returned by
`accessible-keymaps'.
 
There are two other entries with cdr = t: ([24 11] . t) and
([24 54] . t). All the other entries have a keymap as cdr.
 
However, the doc string of `accessible-keymaps' says this:
 
 "Returns a list of elements of the form (KEYS . MAP),
  where the sequence KEYS starting from keymap gets you to MAP."
 
You'll note that it doesn't tell you what MAP is. But you could
presume that MAP would be a keymap, since the doc string also says,
"Find all keymaps accessible...".
 
However, (keymapp t) returns nil; `t' is not a keymap. The doc needs
to make clear what MAP is. In particular, it needs to explain that it
is not necessarily a keymap. It should perhaps explain what `t' means
as a value for MAP, or at least point you to the manual section that
explains it (which section is it?).
 
I searched the Elisp manual for some possibility of a keymap being
just `t', but I didn't find anything related to this. The manual says
clearly that a keymap is a cons whose car is `keymap' and whose cdr...
`t' is not a cons with car `keymap'. The doc for `keymapp' says,
similarly, that a keymap must be a cons with car `keymap'.
 
So at a minimum there is a doc bug here (for `accessible-keymaps', at
least). I wonder too if there isn't a code bug - is it correct for the
MAP of an entry to be `t'?
 

In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'