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

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

[Drew Adams]

OK, I assume I must be doing something wrong, but I don't know what, and
the doc does not seem to help.
 
`visual-line-mode' is a non-global minor mode defined using
`define-minor-mode' with a :keymap parameter.
 
If I redefine the keymap using `C-M-x' on a (defvar
visual-line-mode-map...), or using setq, the keymap is modified as
I would expect.  C-h v shows this clearly.
 
But that has no effect on the key bindings in `visual-line-mode'.  It
seems like variable `visual-line-mode-map' is being ignored.
 
Same thing if I evaluate the defvar in the same buffer as the mode
(though I don't really expect it would be a local variable, and C-h v
does not say it is local).
 
And toggling the mode does not change anything.  When I check the keymap
itself, it is defined exactly according to my modification.  But those
keys are not available in the mode itself; instead, the original key
bindings for the mode are still active.
 
Likewise, if instead of evaluating the defvar I use this:
(add-hook 'visual-line-mode-hook
          (lambda ()
             (define-key "\C-e" 'foobar)
             ...))
 
That too modifies the value of variable `visual-line-mode-map' just as I
expect, but it does not change the actual bindings available in in
visual-line mode.  What am I missing?
 
The only thing I have found to work is to re-evaluate the
`define-minor-mode' sexp after redefining the keymap, so that the
redefinition picks up the new defvar.  Obviously, that is not a reasonable
solution, e.g., for a library or user who wants to modify the key bindings.
 
It's as if the mode were defined once and for all using the value of the
keymap at the time of `define-minor-mode', and not defined to point to
the _variable_ `visual-line-mode-map'.

Do I have to fiddle with `minor-mode-map-alist' or something?  I do not
see this problem with other minor modes, even though the value of that
alist shows that the modes are associated with actual keymaps and not
keymap variables.

BTW, the doc in (elisp) Keymaps and Minor Modes seems incomplete.
It says: "To set up a keymap for a minor mode, add an element to the
alist `minor-mode-map-alist'."  That does not seem right, or at least
not complete.  Using `define-minor-mode' with KEYMAP or :keymap should
also be sufficient to set up a keymap for a minor mode.  For a node
that purports to cover the topic of keymaps and minor modes, this doc
seems insufficient.

(And `minor-mode-overriding-map-alist' is nil.)

Please tell me what I am missing.  I doubt that there is an Emacs bug
here, but I don't know.  Seems like one should be able to change a key
binding in `visual-line-mode-map' and have that take effect.
 
In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2012-12-18 on MS-W7-DANI
Bzr revision: 111265 eliz@gnu.org-20121218190556-x9wmq083vwecgu0f
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -Ic:/emacs/libs/libXpm-3.5.10/include -Ic:/emacs/libs/libXpm-3.5.10/src
 -Ic:/emacs/libs/libpng-dev_1.4.3-1_win32/include
 -Ic:/emacs/libs/zlib-dev_1.2.5-2_win32/include
 -Ic:/emacs/libs/giflib-4.1.4-1-lib/include
 -Ic:/emacs/libs/jpeg-6b-4-lib/include
 -Ic:/emacs/libs/tiff-3.8.2-1-lib/include
 -Ic:/emacs/libs/libxml2-2.7.8-w32-bin/include/libxml2
 -Ic:/emacs/libs/gnutls-3.0.9-w32-bin/include
 -Ic:/emacs/libs/libiconv-1.9.2-1-lib/include'
 

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.

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

[Lars Ingebrigtsen]

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

> 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.

True.  Do you have a suggestion for the doc string?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

[Drew Adams]

> > 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.
> 
> True.  Do you have a suggestion for the doc string?

Uh, see above?

 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'.

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

[Lars Ingebrigtsen]

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

>> > 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.
>> 
>> True.  Do you have a suggestion for the doc string?
>
> Uh, see above?
>
>  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'.

Apparently Philipp Stephani fixed this a couple of weeks ago.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no