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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 39979 in the body.
You can then email your comments to 39979 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Göktuğ Kayaalp <self <at> gkayaalp.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete
Date: Sun, 08 Mar 2020 00:25:58 +0300

[Message part 1 (text/plain, inline)]

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.

[0001-lisp-mwheel.el-mouse-wheel-tilt-scroll-improve-docst.patch (text/x-diff, inline)]

From b9cf4c16d48e8b5b28748481d6649a31d92df1bd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C4=B0=2E=20G=C3=B6ktu=C4=9F=20Kayaalp?= <self <at> 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

Message #8 received at 39979 <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: Göktuğ Kayaalp <self <at> gkayaalp.com>,
 39979 <at> debbugs.gnu.org
Subject: Re: bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is
 unclear/incomplete
Date: Mon, 9 Mar 2020 10:02:35 +0100

> 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

Message #11 received at 39979 <at> debbugs.gnu.org (full text, mbox):

From: Göktuğ Kayaalp <self <at> gkayaalp.com>
To: martin rudalics <rudalics <at> gmx.at>
Cc: 39979 <at> debbugs.gnu.org
Subject: Re: bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is
 unclear/incomplete
Date: Tue, 10 Mar 2020 19:39:43 +0300

[Message part 1 (text/plain, inline)]

On 2020-03-09 10:02 +01, martin rudalics <rudalics <at> 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.

[0001-Improve-docs-for-horizontal-scrolling-with-mouse-and.patch (text/x-diff, attachment)]

Message #14 received at 39979 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> gmail.com>
To: Göktuğ Kayaalp <self <at> gkayaalp.com>
Cc: martin rudalics <rudalics <at> gmx.at>, 39979 <at> debbugs.gnu.org
Subject: Re: bug#39979: 28.0.50;
 `mouse-wheel-tilt-scroll' docstring is unclear/incomplete
Date: Tue, 10 Mar 2020 13:36:39 -0400

Göktuğ Kayaalp <self <at> 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.

Message #17 received at 39979 <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: Göktuğ Kayaalp <self <at> gkayaalp.com>
Cc: 39979 <at> debbugs.gnu.org, Noam Postavsky <npostavs <at> gmail.com>
Subject: Re: bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is
 unclear/incomplete
Date: Wed, 11 Mar 2020 09:52:27 +0100

> 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

Message #20 received at 39979 <at> debbugs.gnu.org (full text, mbox):

From: Göktuğ Kayaalp <self <at> gkayaalp.com>
To: martin rudalics <rudalics <at> gmx.at>
Cc: 39979 <at> debbugs.gnu.org, npostavs <at> gmail.com
Subject: Re: bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is
 unclear/incomplete
Date: Wed, 11 Mar 2020 16:08:36 +0300

[Message part 1 (text/plain, inline)]

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

Done, patch attached.

Cheers,

        -gk.

[0001-Improve-docs-for-horizontal-scrolling-with-mouse-and.patch (text/x-diff, attachment)]

Message #23 received at 39979 <at> debbugs.gnu.org (full text, mbox):

From: Tak Kunihiro <homeros.misasa <at> gmail.com>
To: Göktuğ Kayaalp <self <at> gkayaalp.com>
Cc: martin rudalics <rudalics <at> gmx.at>, 39979 <at> debbugs.gnu.org,
 tkk <at> misasa.okayama-u.ac.jp, npostavs <at> gmail.com
Subject: Re: bug#39979: 28.0.50;
 `mouse-wheel-tilt-scroll' docstring is unclear/incomplete
Date: Thu, 12 Mar 2020 08:09:58 +0900

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

Message #26 received at 39979 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> gmail.com>
To: Göktuğ Kayaalp <self <at> gkayaalp.com>
Cc: martin rudalics <rudalics <at> gmx.at>, 39979 <at> debbugs.gnu.org
Subject: Re: bug#39979: 28.0.50;
 `mouse-wheel-tilt-scroll' docstring is unclear/incomplete
Date: Wed, 11 Mar 2020 19:52:18 -0400

tags 39979 fixed
close 39979 27.1
quit

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

> On 2020-03-11 09:52 +01, martin rudalics <rudalics <at> 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

Message #33 received at 39979 <at> debbugs.gnu.org (full text, mbox):

From: martin rudalics <rudalics <at> gmx.at>
To: Noam Postavsky <npostavs <at> gmail.com>, Göktuğ Kayaalp
 <self <at> gkayaalp.com>
Cc: 39979 <at> debbugs.gnu.org
Subject: Re: bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is
 unclear/incomplete
Date: Thu, 12 Mar 2020 09:22:30 +0100

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

Thank you very much, martin

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.