Subject: Re: bug#76812: vestigial elisp manual descriptions of obsolete variables mouse-wheel-up/down-event

From: JD Smith <[email-masked]>
Date: Fri, 7 Mar 2025 15:45:40 -0500

> On Mar 7, 2025, at 12:22 PM, Stefan Kangas <[email-masked]> wrote:
> 
> Stefan Monnier <[email-masked] <mailto:[email-masked]>> writes:
> 
>>>> The following paragraph in the elisp manual section "Miscellaneous System
>>>> Events" describes blinding events based on the now obsolete variables
>>>> `mouse-wheel-down-event', etc.:
>>>> 
>>>>>     The ‘wheel-up’ and ‘wheel-down’ events are generated only on some
>>>>>     kinds of systems.  On other systems, other events like ‘mouse-4’
>>>>>     and ‘mouse-5’ are used instead.  Portable code should handle both
>>>>>     ‘wheel-up’ and ‘wheel-down’ events as well as the events specified
>>>>>     in the variables ‘mouse-wheel-up-event’ and
>>>>>     ‘mouse-wheel-down-event’, defined in ‘mwheel.el’.  Beware that for
>>>>>     historical reasons the ‘mouse-wheel-_up_-event’ is the variable
>>>>>     that holds an event that should be handled similarly to
>>>>>     ‘wheel-_down_’ and vice versa.
>>> 
>>> Stefan, WDYT?
>> 
>> To the extent that there are still cases where mouse-4/5 is used,
>> I guess we can keep that almost unchanged, except to adjust the wording
>> to indicate what is more normal.  E.g.:
>> 
>>    The ‘wheel-up’ and ‘wheel-down’ events are generated on most systems.
>>    But in some unusual configurations, other events like ‘mouse-4’
>>    and ‘mouse-5’ may still be used instead.  Portable code that wants
>>    to accommodate those cases should handle both
>>    ‘wheel-up’ and ‘wheel-down’ events as well as the events specified
>>    in the variables ‘mouse-wheel-up-event’ and
>>    ‘mouse-wheel-down-event’, defined in ‘mwheel.el’.  Beware that for
>>    historical reasons the ‘mouse-wheel-_up_-event’ is the variable
>>    that holds an event that should be handled similarly to
>>    ‘wheel-_down_’ and vice versa.
>> 
>> ?
> 
> Would it make sense we say something about what those "unusual
> configurations" are?

I think so.  The current situation is sort of odd, in that the variables are both obsoleted (conveying: do not use in new code), and also apparently required for use in new portable code.  Does that suggest they were obsoleted prematurely, if they are still required on some systems?