unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete
@ 2020-03-07 21:25 Göktuğ Kayaalp
  2020-03-09  9:02 ` martin rudalics
  0 siblings, 1 reply; 9+ messages in thread
From: Göktuğ Kayaalp @ 2020-03-07 21:25 UTC (permalink / raw)
  To: 39979

[-- 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


^ permalink raw reply related	[flat|nested] 9+ messages in thread

* bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete
  2020-03-07 21:25 bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete Göktuğ Kayaalp
@ 2020-03-09  9:02 ` martin rudalics
  2020-03-10 16:39   ` Göktuğ Kayaalp
  0 siblings, 1 reply; 9+ messages in thread
From: martin rudalics @ 2020-03-09  9:02 UTC (permalink / raw)
  To: Göktuğ Kayaalp, 39979

 > 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






^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete
  2020-03-09  9:02 ` martin rudalics
@ 2020-03-10 16:39   ` Göktuğ Kayaalp
  2020-03-10 17:36     ` Noam Postavsky
  2020-03-11  8:52     ` martin rudalics
  0 siblings, 2 replies; 9+ messages in thread
From: Göktuğ Kayaalp @ 2020-03-10 16:39 UTC (permalink / raw)
  To: martin rudalics; +Cc: 39979

[-- 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


^ permalink raw reply related	[flat|nested] 9+ messages in thread

* bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete
  2020-03-10 16:39   ` Göktuğ Kayaalp
@ 2020-03-10 17:36     ` Noam Postavsky
  2020-03-11  8:52     ` martin rudalics
  1 sibling, 0 replies; 9+ messages in thread
From: Noam Postavsky @ 2020-03-10 17:36 UTC (permalink / raw)
  To: Göktuğ Kayaalp; +Cc: 39979

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.





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete
  2020-03-10 16:39   ` Göktuğ Kayaalp
  2020-03-10 17:36     ` Noam Postavsky
@ 2020-03-11  8:52     ` martin rudalics
  2020-03-11 13:08       ` Göktuğ Kayaalp
  1 sibling, 1 reply; 9+ messages in thread
From: martin rudalics @ 2020-03-11  8:52 UTC (permalink / raw)
  To: Göktuğ Kayaalp; +Cc: 39979, Noam Postavsky

 > 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






^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete
  2020-03-11  8:52     ` martin rudalics
@ 2020-03-11 13:08       ` Göktuğ Kayaalp
  2020-03-11 23:09         ` Tak Kunihiro
  2020-03-11 23:52         ` Noam Postavsky
  0 siblings, 2 replies; 9+ messages in thread
From: Göktuğ Kayaalp @ 2020-03-11 13:08 UTC (permalink / raw)
  To: martin rudalics; +Cc: 39979, npostavs

[-- 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


^ permalink raw reply related	[flat|nested] 9+ messages in thread

* bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete
  2020-03-11 13:08       ` Göktuğ Kayaalp
@ 2020-03-11 23:09         ` Tak Kunihiro
  2020-03-11 23:52         ` Noam Postavsky
  1 sibling, 0 replies; 9+ messages in thread
From: Tak Kunihiro @ 2020-03-11 23:09 UTC (permalink / raw)
  To: Göktuğ Kayaalp; +Cc: 39979, tkk, npostavs

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete
  2020-03-11 13:08       ` Göktuğ Kayaalp
  2020-03-11 23:09         ` Tak Kunihiro
@ 2020-03-11 23:52         ` Noam Postavsky
  2020-03-12  8:22           ` martin rudalics
  1 sibling, 1 reply; 9+ messages in thread
From: Noam Postavsky @ 2020-03-11 23:52 UTC (permalink / raw)
  To: Göktuğ Kayaalp; +Cc: 39979

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete
  2020-03-11 23:52         ` Noam Postavsky
@ 2020-03-12  8:22           ` martin rudalics
  0 siblings, 0 replies; 9+ messages in thread
From: martin rudalics @ 2020-03-12  8:22 UTC (permalink / raw)
  To: Noam Postavsky, Göktuğ Kayaalp; +Cc: 39979

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

Thank you very much, martin





^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2020-03-12  8:22 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-03-07 21:25 bug#39979: 28.0.50; `mouse-wheel-tilt-scroll' docstring is unclear/incomplete Göktuğ Kayaalp
2020-03-09  9:02 ` martin rudalics
2020-03-10 16:39   ` Göktuğ Kayaalp
2020-03-10 17:36     ` Noam Postavsky
2020-03-11  8:52     ` martin rudalics
2020-03-11 13:08       ` Göktuğ Kayaalp
2020-03-11 23:09         ` Tak Kunihiro
2020-03-11 23:52         ` Noam Postavsky
2020-03-12  8:22           ` martin rudalics

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).