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

1 files changed, 20 insertions, 0 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")