bug#4478: 23.1; key bindings for mouse wheel - unclear

["Drew Adams" <drew.adams@oracle.com>]

1. Doc bug: The doc is not clear about how to bind the mouse wheel
(rotations).
 
2. Code bug / enhancement request: Have a shorter way to bind wheel
actions.
 
--
 
I've been using bindings such as this:
 
(define-key map [wheel-down]   'aaa)
(define-key map [wheel-down]   'bbb)
(define-key map [C-wheel-down] 'ccc)
(define-key map [C-wheel-down] 'ddd)
 
Reading some mail on (I think) help-gnu-emacs got me a bit confused,
however. It gave me the impression that such bindings were only for MS
Windows and that on GNU/Linux `mouse-4' and `mouse-5' must be used
instead of `wheel-down' and `wheel-up'. (That sounds odd; I'd expect
`mouse-4' and `mouse-5' to be a fourth and fifth mouse button, as they
are on Windows.)
 
I looked in the Elisp manual, but I didn't find anything specifically
recommending how one should bind mouse wheel events. I was assuming
that `wheel-down' was platform independent, but now I have a doubt.
 
The Elisp doc (node Misc Events) speaks about events such as (wheel-up
POSITION), but it doesn't speak about just what to use when binding
such keys.  Further, it says that events such as (wheel-up POSITION)
are not generated on some systems and that on those systems "`mouse-4'
and `mouse-5' are used instead". (Why is that?)
 
It does say this, however: "For portable code, use the variables
`mouse-wheel-up-event' and `mouse-wheel-down-event'", and then it goes
on to say where those variables are defined (why does it say where
they are defined?).
 
So after a bit of fiddling I switched to this:
 
(define-key map (vector mouse-wheel-down-event) 'aaa)
(define-key map (vector mouse-wheel-up-event)   'bbb)
(define-key map
  (vector (list 'control mouse-wheel-down-event)) 'ccc)
(define-key map
  (vector (list 'control mouse-wheel-up-event)) 'ddd)
 
I haven't tested on GNU/Linux, but I'm assuming this is what to use
for portable code. Is there a shorter or better way to say this and
still be portable? 
 
1. If there is not, there should be (a shorter way to do this).
 
2. Until then, whatever is the current best way should at least be
documented clearly as the way to bind mouse wheel events.
 
I would even expect the Emacs manual to tell you how to bind
mouse-wheel key sequences...  But AFAICT the Emacs manual isn't too
helpful for even the basics about key binding. I filed a separate bug
(#4472) about that.
 
 
 
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)'