feat: add 'mousescroll' option (#12355)

Add 'mousescroll' option to control how many lines to scroll by when a
mouse wheel keycode is received. The mousescroll option controls both
horizontal and vertical scrolling. The option is a string in the format:

    set mousescroll=direction:count,direction:count

Where direction is either "ver" or "hor", and count is a non negative
integer. If a direction is omitted, a default value is used. The default
values remain unchanged, that is 3 for vertical scrolling, and 6 for
horizontal scrolling. As such, the mousescroll default is "ver:3,hor:6".

Add mousescroll documentation
 - Add option documentation in options.txt
 - Add brief summary in quickref.txt

Update :help scroll-mouse-wheel
 - Mention mousescroll option as a means of controlling scrolling.
 - Remove obsolete suggestion to map scroll wheel keys to <C-U> to
   scroll by a single line -- users should prefer the mousescroll option.
 - Add some information about the consequences of remapping scroll wheel
   keys (they lose their magic ability to affect inactive windows).

Update :help vim-differences
 - Add brief mousescroll summary under Options

Add mousescroll tests
 - Test option validation
 - Test default mousescroll value and behavior
 - Test fallback to default values
 - Test mouse vertical and horizontal scrolling in normal mode
 - Test mouse vertical and horizontal scrolling in insert mode

4 files changed, 33 insertions, 7 deletions

diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index eb377697e9..74ba353e0a 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -4210,6 +4210,26 @@ A jump table for the options with a short description can be found at |Q_op|.
 
 	The 'mousemodel' option is set by the |:behave| command.
 
+					*mousescroll*
+'mousescroll'		string	(default "ver:3,hor:6")
+			global
+	This option controls the number of lines / columns to scroll by when
+	scrolling with a mouse. The option is a comma separated list of parts.
+	Each part consists of a direction and a count as follows:
+		direction:count,direction:count
+	Direction is one of either "hor" or "ver", "hor" controls horizontal
+	scrolling and "ver" controls vertical scrolling. Count sets the amount
+	to scroll by for the given direction, it should be a non negative
+	integer. Each direction should be set at most once. If a direction
+	is omitted, a default value is used (6 for horizontal scrolling and 3
+	for vertical scrolling). You can disable mouse scrolling by using
+	a count of 0.
+
+	Example: >
+		:set mousescroll=ver:5,hor:2
+<	Will make Nvim scroll 5 lines at a time when scrolling vertically, and
+	scroll 2 columns at a time when scrolling horizontally.
+
 					*'mouseshape'* *'mouses'* *E547*
 'mouseshape' 'mouses'	string	(default "i:beam,r:beam,s:updown,sd:cross,
 					m:no,ml:up-arrow,v:rightup-arrow")
diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt
index a380088e98..6f16db5cc2 100644
--- a/runtime/doc/quickref.txt
+++ b/runtime/doc/quickref.txt
@@ -785,6 +785,7 @@ Short explanation of each option:		*option-list*
 'mousefocus'	  'mousef'  keyboard focus follows the mouse
 'mousehide'	  'mh'	    hide mouse pointer while typing
 'mousemodel'	  'mousem'  changes meaning of mouse buttons
+'mousescroll'		    amount to scroll by when scrolling with a mouse
 'mouseshape'	  'mouses'  shape of the mouse pointer in different modes
 'mousetime'	  'mouset'  max time between mouse double-click
 'nrformats'	  'nf'	    number formats recognized for CTRL-A command
diff --git a/runtime/doc/scroll.txt b/runtime/doc/scroll.txt
index 7d1da3b409..170c87a1a4 100644
--- a/runtime/doc/scroll.txt
+++ b/runtime/doc/scroll.txt
@@ -239,12 +239,16 @@ the "h" flag in 'guioptions' is set, the cursor moves to the longest visible
 line if the cursor line is about to be scrolled off the screen (similarly to
 how the horizontal scrollbar works).
 
-You can modify the default behavior by mapping the keys.  For example, to make
-the scroll wheel move one line or half a page in Normal mode: >
-   :map <ScrollWheelUp> <C-Y>
-   :map <S-ScrollWheelUp> <C-U>
-   :map <ScrollWheelDown> <C-E>
-   :map <S-ScrollWheelDown> <C-D>
-You can also use Alt and Ctrl modifiers.
+You can control the number of lines / columns to scroll by using the
+'mousescroll' option. You can also modify the default behavior by mapping
+the keys. For example, to scroll a page at a time in normal mode: >
+   :map <ScrollWheelUp> <C-B>
+   :map <ScrollWheelDown> <C-F>
+Scroll keys can also be combined with modifiers such as Shift, Ctrl, and Alt.
+
+When scrolling with a mouse, the window currently under the cursor is
+scrolled. This allows you to scroll inactive windows. Note that when scroll
+keys are remapped to keyboard keys, the active window is affected regardless
+of the current cursor position.
 
  vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 4b26e5501c..8e853aaf9e 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -238,6 +238,7 @@ Options:
   'inccommand'  shows interactive results for |:substitute|-like commands
                 and |:command-preview| commands
   'laststatus'  global statusline support
+  'mousescroll' amount to scroll by when scrolling with a mouse
   'pumblend'    pseudo-transparent popupmenu
   'scrollback'
   'signcolumn'  supports up to 9 dynamic/fixed columns