bug#13269: 24.3.50; modifying bindings in `visual-line-mode-map' has no effect

[Drew Adams]

My bad.  Using the add-hook to change bindings does work OK.  (Though I forgot
to include the map var in the add-hook sexp that I wrote in the report.)

And I guess this is why evalling the defvar has no effect: The defvar value
starts from a virgin map, so the var then points to a different keymap object
(i.e., cons cell) than it did initially, when it was used to define the mode.  I
did not realize that that would be a problem.  I thought that the mode function
looked up the variable value to get the actual keymap.

If I do the add-hook or just
(define-key visual-line-mode-map "\C-e" 'foobar)
then the binding does take effect.

Doing that, the var still points to the same keymap object, i.e., the same cons
as originally, and the define-key just adds or modifies a binding there.

If my understanding is now correct, this is a gotcha that should clarified in
the doc.  The minor mode does not go through the variable at all, it goes
directly to the keymap value (i.e., the cons cell) that the variable had at the
time the mode was defined.

This is not obvious, given that `define-minor-mode' is a macro, so does not in
general evaluate its args.  It is not clear from the doc that the keymap object
itself is what is used by the mode and not first the variable.

The doc does not say that the KEYMAP arg or :keymap parameter is _evaluated_,
but it does kind of suggest it indirectly:

Optional KEYMAP is the default keymap bound to the mode keymap.
  If non-nil, it should be a variable name (whose value is a keymap),
  or an expression that returns either a keymap or a list of
  arguments for `easy-mmode-define-keymap'.  If you supply a KEYMAP
  argument that is not a symbol, this macro defines the variable
  MODE-map and gives it the value that KEYMAP specifies.

First, "it should be a variable name" is wrong, since a variable name is a
string, the `symbol-name' of the variable (which is a symbol).  You cannot pass
a variable name for KEYMAP.

Second, "variable name (whose value is a keymap)" is wrong.  The name has no
value (except itself: the same string).  It is the variable's value that is a
keymap, not the variable's name's value.

This text is generally confusing.  It should simply say that KEYMAP is
_evaluated_ when the mode is defined, and the resulting value must be either a
keymap or "a list of arguments for `easy-mmode-define-keymap'."  Less verbose,
correct, and clear.

All the talk about a variable and its name is noise and confusing (and wrong as
written).

HTH.  If you think I have still not understood correctly, please set me
straight.  Thx.