emacs-29 3296031ad74: ; Another improvement for documentation of pixelwise scrolling

[Eli Zaretskii]

branch: emacs-29
commit 3296031ad74f8cdc9638ae948b5372a81a43a2d1
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Another improvement for documentation of pixelwise scrolling
    
    * doc/lispref/commands.texi (Misc Events): More details about
    pixelwise mouse-wheel scrolling events.  (Bug#65070)
---
 doc/lispref/commands.texi | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 028209b2bc1..110b2479d11 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -2242,11 +2242,12 @@ mouse cursor when the finger moved off the mouse wheel.
 @cindex @code{wheel-down} event
 @item (wheel-up @var{position} @var{clicks} @var{lines} @var{pixel-delta})
 @itemx (wheel-down @var{position} @var{clicks} @var{lines} @var{pixel-delta})
-These kinds of event are generated by moving a mouse wheel.  The
+These events are generated by moving a mouse wheel.  The
 @var{position} element is a mouse position list (@pxref{Click
 Events}), specifying the position of the mouse cursor when the event
 occurred.
 
+@vindex mwheel-coalesce-scroll-events
 @var{clicks}, if present, is the number of times that the wheel was
 moved in quick succession.  @xref{Repeat Events}.  @var{lines}, if
 present and not @code{nil}, is the positive number of screen lines
@@ -2254,24 +2255,35 @@ that should be scrolled (either up, when the event is 
@code{wheel-up},
 or down when the event is @code{wheel-down}).  @var{pixel-delta}, if
 present, is a cons cell of the form @w{@code{(@var{x} . @var{y})}},
 where @var{x} and @var{y} are the numbers of pixels by which to scroll
-in each axis, a.k.a.@: @dfn{pixelwise deltas}.
+in each axis, a.k.a.@: @dfn{pixelwise deltas}.  Usually, only one of
+the two will be non-zero, the other will be either zero or very close
+to zero; the larger number indicates the axis to scroll the window.
+When the variable @code{mwheel-coalesce-scroll-events} is @code{nil},
+the scroll commands ignore the @var{lines} element, even if it's
+non-@code{nil}, and use the @var{pixel-delta} data instead; in that
+case, the direction of scrolling is determined by the sign of the
+pixelwise deltas, and the direction (up or down) implied by the event
+kind is ignored.
 
 @cindex pixel-resolution wheel events
 You can use these @var{x} and @var{y} pixelwise deltas to determine
 how much the mouse wheel has actually moved at pixel resolution.  For
 example, the pixelwise deltas could be used to scroll the display at
 pixel resolution, exactly according to the user's turning the mouse
-wheel.
+wheel.  This pixelwise scrolling is possible only when
+@code{mwheel-coalesce-scroll-events} is @code{nil}, and in general the
+@var{pixel-delta} data is not generated when that variable is
+non-@code{nil}.
 
 @vindex mouse-wheel-up-event
 @vindex mouse-wheel-down-event
-This kind of event is generated only on some kinds of systems.  On
-some systems, @code{mouse-4} and @code{mouse-5} are used instead.  For
-portable code, use the variables @code{mouse-wheel-up-event},
-@code{mouse-wheel-up-alternate-event}, @code{mouse-wheel-down-event}
-and @code{mouse-wheel-down-alternate-event} defined in
-@file{mwheel.el} to determine what event types to expect for the mouse
-wheel.
+The @code{wheel-up} and @code{wheel-down} events are generated only on
+some kinds of systems.  On other systems, @code{mouse-4} and
+@code{mouse-5} are used instead.  For portable code, use the variables
+@code{mouse-wheel-up-event}, @code{mouse-wheel-up-alternate-event},
+@code{mouse-wheel-down-event} and
+@code{mouse-wheel-down-alternate-event} defined in @file{mwheel.el} to
+determine what event types to expect from the mouse wheel.
 
 @vindex mouse-wheel-left-event
 @vindex mouse-wheel-right-event