Merge from origin/emacs-29

3296031ad7 ; Another improvement for documentation of pixelwise scro...
baeb2d71ae Support defun navigation for DEFUN in c-ts-mode (bug#64442)
781ddd7e7d Fix touchpad scrolling on MS-Windows
c125bd060e Fix order in which package-vc dependencies are resolved
500ced133a Fix building of VC package manuals with relative org link...
456ecabe9e Fix the documentation of 'cl-flet'
f6ebd1ef0d ; * src/treesit.c (Ftreesit_node_parent): Improve comment...
fac0e2d533 Avoid false "wrong passphrase" messages in EPA
8f683b51d8 Fix jsx font-lock in older tree-sitter-js grammars
d9af79ae39 Fix cloning 'face-remapping-alist' for indirect buffers
636fb267c4 Improve documentation of case transfer in replacement com...
7856d51436 Fix horizontal scrolling of images with C-f
8cf5659ec2 ; Fix defcustom in completion.el
a8c8a4e368 ; * src/fns.c (Fcopy_sequence): Doc fix.  (Bug#64960)
205d87cdca Fix unpacking ZIP archives on MS-Windows
3712e8bc38 ; Fix typos in lisp/keymap.el doc strings (bug#65329).
21b2ecee66 Fix command example in Eshell manual
26949819df ; lisp/progmodes/csharp-mode.el (treesit-query-capture): ...
221ed70b90 ; Improve documentation of 'define-alternatives'
32280205e2 Add user options mentioned in the Eshell manual to the va...
cf3145a486 * Add missing alias to `native-comp-enable-subr-trampolin...
922b649028 * Add missing alias to `native-comp-enable-subr-trampolin...
6962823c83 ; * etc/PROBLEMS: Fix typo and clarify wording.

# Conflicts:
#	doc/misc/eshell.texi

doc/lispref/commands.texi

@@ -710,29 +710,77 @@ context.
 @node Generic Commands
 @subsection Select among Command Alternatives
 @cindex generic commands
-@cindex alternatives, defining
+@cindex alternative commands, defining
 
-The macro @code{define-alternatives} can be used to define
-@dfn{generic commands}.  These are interactive functions whose
-implementation can be selected from several alternatives, as a matter
-of user preference.
+Sometimes it is useful to define a command that serves as a ``generic
+dispatcher'' capable of invoking one of a set of commands according to
+the user's needs.  For example, imagine that you want to define a
+command named @samp{open} that can ``open'' and display several
+different types of objects.  Or you could have a command named
+@samp{mua} (which stands for Mail User Agent) that can read and send
+email using one of several email backends, such as Rmail, Gnus, or
+MH-E.  The macro @code{define-alternatives} can be used to define such
+@dfn{generic commands}.  A generic command is an interactive function
+whose implementation can be selected from several alternatives, as a
+matter of user preference.
 
 @defmac define-alternatives command &rest customizations
-Define the new command @var{command}, a symbol.
+This macro defines the new generic @var{command}, which can have
+several alternative implementations.  The argument @var{command}
+should be an unquoted symbol.
 
-When a user runs @kbd{M-x @var{command} @key{RET}} for the first time,
-Emacs prompts for which real form of the command to use, and records
-the selection by way of a custom variable.  Using a prefix argument
-repeats this process of choosing an alternative.
+When invoked, the macro creates an interactive Lisp closure
+(@pxref{Closures}).  When the user runs @w{@kbd{M-x @var{command}
+@key{RET}}} for the first time, Emacs asks to select one of the
+alternative implementations of @var{command}, offering completion for
+the names of these alternatives.  These names come from the user
+option whose name is @code{@var{command}-alternatives}, which the
+macro creates (if it didn't exist before).  To be useful, this
+variable's value should be an alist whose elements have the form
+@w{@code{(@var{alt-name} . @var{alt-func})}}, where @var{alt-name} is
+the name of the alternative and @var{alt-func} is the interactive
+function to be called if this alternative is selected.  When the user
+selects an alternative, Emacs remembers the selection, and will
+thereafter automatically call that selected alternative without
+prompting when the user invokes @kbd{M-x @var{command}} again.  To
+choose a different alternative, type @w{@kbd{C-u M-x @var{command}
+@key{RET}}}--then Emacs will again prompt for one of the alternatives,
+and the selection will override the previous one.
 
-The variable @code{@var{command}-alternatives} should contain an alist
-with alternative implementations of @var{command}.
-Until this variable is set, @code{define-alternatives} has no effect.
+The variable @code{@var{command}-alternatives} can be created before
+calling @code{define-alternatives}, with the appropriate values;
+otherwise the macro creates the variable with a @code{nil} value, and
+it should then be populated with the associations describing the
+alternatives.  Packages that wish to provide their own implementation
+of an existing generic command can use @code{autoload} cookies
+(@pxref{Autoload}) to add to the alist, for example:
+
+@lisp
+;;;###autoload (push '("My name" . my-foo-symbol) foo-alternatives
+@end lisp
+
+If the optional argument @var{customizations} is non-@code{nil}, it
+should consist of alternating @code{defcustom} keywords (typically
+@code{:group} and @code{:version}) and values to add to the definition
+of the @code{defcustom} @code{@var{command}-alternatives}.
+
+Here is an example of a simple generic dispatcher command named
+@code{open} with 3 alternative implementations:
+
+@example
+@group
+(define-alternatives open
+  :group 'files
+  :version "42.1")
+@end group
+@group
+(setq open-alternatives
+      '(("file" . find-file)
+	("directory" . dired)
+	("hexl" . hexl-find-file)))
+@end group
+@end example
 
-If @var{customizations} is non-@code{nil}, it should consist of
-alternating @code{defcustom} keywords (typically @code{:group} and
-@code{:version}) and values to add to the declaration of
-@code{@var{command}-alternatives}.
 @end defmac
 
 @node Interactive Call
@@ -2433,35 +2481,48 @@ 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 number of screen lines that should
-be scrolled.  @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}.
+present and not @code{nil}, is the positive number of screen lines
+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}.  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