bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete

bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete

[Göktuğ Kayaalp]

[-- Attachment #1: Type: text/plain, Size: 501 bytes --]

The docstring for the mentioned variable is unclear in that it does not
really tell what kind of scrolling (horizontal) is enabled and
incomplete because setting it enables horizontal scrolling and that’s
not mentioned (or, maybe tilt scrolling means that but that’s probably
an obscure term for many).

A patch is attached which is proposed as a tentative improvement. If
it’s good enough to apply, I do have my copyright assingment paperwork
done so it can be committed right away.


[-- Attachment #2: the patch --]
[-- Type: text/x-diff, Size: 817 bytes --]

From b9cf4c16d48e8b5b28748481d6649a31d92df1bd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C4=B0=2E=20G=C3=B6ktu=C4=9F=20Kayaalp?= <self@gkayaalp.com>
Date: Sun, 8 Mar 2020 00:15:01 +0300
Subject: [PATCH] * lisp/mwheel.el (mouse-wheel-tilt-scroll): improve docstring

---
 lisp/mwheel.el | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/lisp/mwheel.el b/lisp/mwheel.el
index 56150c803f..9264af1214 100644
--- a/lisp/mwheel.el
+++ b/lisp/mwheel.el
@@ -145,7 +145,8 @@ mouse-wheel-follow-mouse
 ;;; For tilt-scroll
 ;;;
 (defcustom mouse-wheel-tilt-scroll nil
-  "Enable scroll using tilting mouse wheel."
+  "Enable horizontal scrolling via mouse or touchpad. Also see
+  ‘mouse-wheel-flip-direction’."
   :group 'mouse
   :type 'boolean
   :version "26.1")
-- 
2.20.1

bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete

[martin rudalics]

 > A patch is attached which is proposed as a tentative improvement. If
 > it’s good enough to apply, I do have my copyright assingment paperwork
 > done so it can be committed right away.

Thanks for looking into this.  But

-  "Enable scroll using tilting mouse wheel."
+  "Enable horizontal scrolling via mouse or touchpad. Also see
+  ‘mouse-wheel-flip-direction’."

violates the rule from D.6 of the Elisp manual:

  The first line of the documentation string should consist of one or
      two complete sentences that stand on their own as a summary.

Also, 'mouse-wheel-flip-direction' does not have a great doc-string
either.  Maybe we should add a reference to section 21.1 of the Emacs
manual?

martin

bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete

[Göktuğ Kayaalp]

[-- Attachment #1: Type: text/plain, Size: 1585 bytes --]

On 2020-03-09 10:02 +01, martin rudalics <rudalics@gmx.at> wrote:
>  > A patch is attached which is proposed as a tentative improvement. If
>  > it’s good enough to apply, I do have my copyright assingment paperwork
>  > done so it can be committed right away.
>
> Thanks for looking into this.  But
>
> -  "Enable scroll using tilting mouse wheel."
> +  "Enable horizontal scrolling via mouse or touchpad. Also see
> +  ‘mouse-wheel-flip-direction’."
>
> violates the rule from D.6 of the Elisp manual:
>
>   The first line of the documentation string should consist of one or
>       two complete sentences that stand on their own as a summary.

New patch added, with some improvement to the ‘...-flip-direction’
variable too.

> Also, 'mouse-wheel-flip-direction' does not have a great doc-string
> either.  Maybe we should add a reference to section 21.1 of the Emacs
> manual?

There is this, assuming you meant "(emacs) Mouse Commands":

,----
|    Emacs can also support horizontal scrolling if your mouse’s wheel can
| be tilted.  This feature is off by default; the variable
| ‘mouse-wheel-tilt-scroll’ turns it on.  If you’d like to reverse the
| direction of horizontal scrolling, customize the variable
| ‘mouse-wheel-flip-direction’ to a non-‘nil’ value.
`----

I think a little mention of touchpads would suffice.  The added patch
addresses this too.

Cheers,

        -gk.

P.S. I never know if it’s better to send Debbugs patches inline or as
attachments.  Sorry if I’m doing the wrong thing.



[-- Attachment #2: Improved patch --]
[-- Type: text/x-diff, Size: 2363 bytes --]

From 66906d5a680f61528ae1eaee1f101eecebd5a0aa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C4=B0=2E=20G=C3=B6ktu=C4=9F=20Kayaalp?= <self@gkayaalp.com>
Date: Sun, 8 Mar 2020 00:15:01 +0300
Subject: [PATCH] Improve docs for horizontal scrolling with mouse and touchpad

* lisp/mwheel.el (mouse-wheel-tilt-scroll,
mouse-wheel-flip-direction): Improve docstrings.
* doc/emacs/frames.texi (Mouse Commands): Mention touchpads.
---
 doc/emacs/frames.texi | 9 +++++----
 lisp/mwheel.el        | 7 +++++--
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 002297c259..16205e6e0c 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -217,10 +217,11 @@ Mouse Commands
 @vindex mouse-wheel-tilt-scroll
 @vindex mouse-wheel-flip-direction
 Emacs can also support horizontal scrolling if your mouse's wheel can
-be tilted.  This feature is off by default; the variable
-@code{mouse-wheel-tilt-scroll} turns it on.  If you'd like to reverse
-the direction of horizontal scrolling, customize the variable
-@code{mouse-wheel-flip-direction} to a non-@code{nil} value.
+be tilted, or your touchpad supports it.  This feature is off by
+default; the variable @code{mouse-wheel-tilt-scroll} turns it on.  If
+you'd like to reverse the direction of horizontal scrolling, customize
+the variable @code{mouse-wheel-flip-direction} to a non-@code{nil}
+value.
 
 When the mouse pointer is over an image, scrolling the mouse wheel
 with the @key{Ctrl} modifier scales the image under the mouse pointer.
diff --git a/lisp/mwheel.el b/lisp/mwheel.el
index 56150c803f..41ae3769c1 100644
--- a/lisp/mwheel.el
+++ b/lisp/mwheel.el
@@ -145,13 +145,16 @@ mouse-wheel-follow-mouse
 ;;; For tilt-scroll
 ;;;
 (defcustom mouse-wheel-tilt-scroll nil
-  "Enable scroll using tilting mouse wheel."
+  "Enable horizontal scrolling via mouse or touchpad.
+Also see ‘mouse-wheel-flip-direction’."
   :group 'mouse
   :type 'boolean
   :version "26.1")
 
 (defcustom mouse-wheel-flip-direction nil
-  "Swap direction of `wheel-right' and `wheel-left'."
+  "Swap direction of `wheel-right' and `wheel-left'.
+This inverts the direction of horizontal scrolling. Also see
+`mouse-wheel-tilt-scroll'."
   :group 'mouse
   :type 'boolean
   :version "26.1")
-- 
2.20.1

bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete

[Noam Postavsky]

Göktuğ Kayaalp <self@gkayaalp.com> writes:

> P.S. I never know if it’s better to send Debbugs patches inline or as
> attachments.  Sorry if I’m doing the wrong thing.

Generally, sending as attachment (as you did) is safer because some
mail-clients will word-wrap the text otherwise.  CONTRIBUTE recommends
attaching as well.

bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete

[martin rudalics]

 > I think a little mention of touchpads would suffice.  The added patch
 > addresses this too.

Thanks.  Please also fix the quotation

‘mouse-wheel-flip-direction’ ~> `mouse-wheel-flip-direction'

Noam, could you please install this then.  I'm afraid I'll never be able
to enter "Göktuğ" correctly from here.

Thanks, martin

bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete

[Göktuğ Kayaalp]

[-- Attachment #1: Type: text/plain, Size: 189 bytes --]

On 2020-03-11 09:52 +01, martin rudalics <rudalics@gmx.at> wrote:
> ‘mouse-wheel-flip-direction’ ~> `mouse-wheel-flip-direction'

Done, patch attached.

Cheers,

        -gk.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: fixed quotes --]
[-- Type: text/x-diff, Size: 2300 bytes --]

From fafa8c72ffc6648961da90fa7a3b95cfd57dec14 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C4=B0=2E=20G=C3=B6ktu=C4=9F=20Kayaalp?= <self@gkayaalp.com>
Date: Sun, 8 Mar 2020 00:15:01 +0300
Subject: [PATCH] Improve docs for horizontal scrolling with mouse and touchpad

* lisp/mwheel.el (mouse-wheel-tilt-scroll,
mouse-wheel-flip-direction): Improve docstrings.
* doc/emacs/frames.texi (Mouse Commands): Mention touchpads.
---
 doc/emacs/frames.texi | 9 +++++----
 lisp/mwheel.el        | 7 +++++--
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 002297c259..16205e6e0c 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -217,10 +217,11 @@ Mouse Commands
 @vindex mouse-wheel-tilt-scroll
 @vindex mouse-wheel-flip-direction
 Emacs can also support horizontal scrolling if your mouse's wheel can
-be tilted.  This feature is off by default; the variable
-@code{mouse-wheel-tilt-scroll} turns it on.  If you'd like to reverse
-the direction of horizontal scrolling, customize the variable
-@code{mouse-wheel-flip-direction} to a non-@code{nil} value.
+be tilted, or your touchpad supports it.  This feature is off by
+default; the variable @code{mouse-wheel-tilt-scroll} turns it on.  If
+you'd like to reverse the direction of horizontal scrolling, customize
+the variable @code{mouse-wheel-flip-direction} to a non-@code{nil}
+value.
 
 When the mouse pointer is over an image, scrolling the mouse wheel
 with the @key{Ctrl} modifier scales the image under the mouse pointer.
diff --git a/lisp/mwheel.el b/lisp/mwheel.el
index 56150c803f..bfba1f4e1e 100644
--- a/lisp/mwheel.el
+++ b/lisp/mwheel.el
@@ -145,13 +145,16 @@ mouse-wheel-follow-mouse
 ;;; For tilt-scroll
 ;;;
 (defcustom mouse-wheel-tilt-scroll nil
-  "Enable scroll using tilting mouse wheel."
+  "Enable horizontal scrolling via mouse or touchpad.
+Also see `mouse-wheel-flip-direction'."
   :group 'mouse
   :type 'boolean
   :version "26.1")
 
 (defcustom mouse-wheel-flip-direction nil
-  "Swap direction of `wheel-right' and `wheel-left'."
+  "Swap direction of `wheel-right' and `wheel-left'.
+This inverts the direction of horizontal scrolling. Also see
+`mouse-wheel-tilt-scroll'."
   :group 'mouse
   :type 'boolean
   :version "26.1")
-- 
2.20.1

bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete

[Tak Kunihiro]

The old docstring was written by me, who is (I think) okay but not good
in English.  Thank you.

bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete

[Noam Postavsky]

tags 39979 fixed
close 39979 27.1
quit

Göktuğ Kayaalp <self@gkayaalp.com> writes:

> On 2020-03-11 09:52 +01, martin rudalics <rudalics@gmx.at> wrote:
>> ‘mouse-wheel-flip-direction’ ~> `mouse-wheel-flip-direction'
>
> Done, patch attached.

> +This inverts the direction of horizontal scrolling. Also see
                                                      ^
Added the missing space and pushed to emacs-27.

[1: ef5744a988]: 2020-03-11 19:48:47 -0400
  Improve docs for horizontal scrolling with mouse and touchpad (Bug#39979)
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=ef5744a988f299c1b8b4726ee0d5bf9c1c1074f5

bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete

[martin rudalics]

 > Added the missing space and pushed to emacs-27.

Thank you very much, martin