GNU bug report logs - #13791
24.3.50; scroll-margin docstring says "recenter"

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 13791 in the body.
You can then email your comments to 13791 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: Dmitry Gutov <dgutov <at> yandex.ru>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.3.50; scroll-margin docstring says "recenter"
Date: Sat, 23 Feb 2013 04:21:24 +0400

The docstring says: "Recenter the window whenever point gets within this
many lines of the top or bottom of the window."

That's not entirely accurate. Depending on the value of
`scroll-conservatively', the window may get scrolled instead.

Bzr revision: 111828 michael.albinus <at> gmx.de-20130219151755-yklhdrlp26loxg2v

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: 13791 <at> debbugs.gnu.org
Subject: Re: bug#13791: 24.3.50; scroll-margin docstring says "recenter"
Date: Sat, 23 Feb 2013 12:18:12 +0200

> From: Dmitry Gutov <dgutov <at> yandex.ru>
> Date: Sat, 23 Feb 2013 04:21:24 +0400
> 
> The docstring says: "Recenter the window whenever point gets within this
> many lines of the top or bottom of the window."
> 
> That's not entirely accurate. Depending on the value of
> `scroll-conservatively', the window may get scrolled instead.

That's true.  However, how to describe this in a manner that will not
confuse the reader is less clear.  "Recenter or scroll" is not very
useful, IMO, as it doesn't say which will happen.  Suggestions are
welcome.

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

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 13791 <at> debbugs.gnu.org
Subject: Re: bug#13791: 24.3.50; scroll-margin docstring says "recenter"
Date: Sat, 23 Feb 2013 17:08:35 +0400

On 23.02.2013 14:18, Eli Zaretskii wrote:
>> That's not entirely accurate. Depending on the value of
>> `scroll-conservatively', the window may get scrolled instead.
>
> That's true.  However, how to describe this in a manner that will not
> confuse the reader is less clear.  "Recenter or scroll" is not very
> useful, IMO, as it doesn't say which will happen.  Suggestions are
> welcome.

How about the following?

"""
Recenter or scroll the window whenever point gets within this many lines 
of the top or bottom of the window.

If the value of `scroll-conservatively' is positive, the window is 
scrolled, otherwise it's recentered.
"""

Adjust for actual behavior.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: 13791 <at> debbugs.gnu.org
Subject: Re: bug#13791: 24.3.50; scroll-margin docstring says "recenter"
Date: Sat, 23 Feb 2013 16:50:25 +0200

> Date: Sat, 23 Feb 2013 17:08:35 +0400
> From: Dmitry Gutov <dgutov <at> yandex.ru>
> CC: 13791 <at> debbugs.gnu.org
> 
> If the value of `scroll-conservatively' is positive, the window is 
> scrolled, otherwise it's recentered.

This is not true, because if scroll-conservatively is below 101, the
window could still be recentered.

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

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 13791 <at> debbugs.gnu.org
Subject: Re: bug#13791: 24.3.50; scroll-margin docstring says "recenter"
Date: Sat, 23 Feb 2013 22:08:56 +0400

On 23.02.2013 18:50, Eli Zaretskii wrote:
>> Date: Sat, 23 Feb 2013 17:08:35 +0400
>> From: Dmitry Gutov <dgutov <at> yandex.ru>
>> CC: 13791 <at> debbugs.gnu.org
>>
>> If the value of `scroll-conservatively' is positive, the window is
>> scrolled, otherwise it's recentered.
>
> This is not true, because if scroll-conservatively is below 101, the
> window could still be recentered.

Like I said, you can adjust the description with how things actually work.

But I'm not sure we're talking about the same thing. I meant to describe 
what will happen to the window when point "gets within this many lines 
of the top or bottom of the window", not when it moves outside the 
visible area.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: 13791 <at> debbugs.gnu.org
Subject: Re: bug#13791: 24.3.50; scroll-margin docstring says "recenter"
Date: Sat, 23 Feb 2013 20:47:18 +0200

> Date: Sat, 23 Feb 2013 22:08:56 +0400
> From: Dmitry Gutov <dgutov <at> yandex.ru>
> CC: 13791 <at> debbugs.gnu.org
> 
> But I'm not sure we're talking about the same thing.

I think we are.

> I meant to describe what will happen to the window when point "gets
> within this many lines of the top or bottom of the window", not when
> it moves outside the visible area.

That's how I understood it.  But if you lean on the up or down key,
you can easily cause point go off the screen before Emacs enters
redisplay.

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

From: Dmitry Gutov <dgutov <at> yandex.ru>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 13791 <at> debbugs.gnu.org
Subject: Re: bug#13791: 24.3.50; scroll-margin docstring says "recenter"
Date: Sat, 23 Feb 2013 23:19:32 +0400

On 23.02.2013 22:47, Eli Zaretskii wrote:
>> Date: Sat, 23 Feb 2013 22:08:56 +0400
>> From: Dmitry Gutov <dgutov <at> yandex.ru>
>> CC: 13791 <at> debbugs.gnu.org
>>
>> But I'm not sure we're talking about the same thing.
>
> I think we are.
>
>> I meant to describe what will happen to the window when point "gets
>> within this many lines of the top or bottom of the window", not when
>> it moves outside the visible area.
>
> That's how I understood it.  But if you lean on the up or down key,
> you can easily cause point go off the screen before Emacs enters
> redisplay.

Yes, but in this case point is not "within this many lines of the top or 
bottom of the window" anymore technically.

Or maybe it is, if you interpret "top" and "bottom" as just buffer lines 
and "gets within" as "within absolute distance". In this case we can 
additionally qualify the conditions:

"whenever point gets within this many lines of the top or bottom of the 
window without going off screen."

Either way, this description is more accurate than what we have currently.

Alternatively, we can mention the "off screen" situation in the second 
paragraph, where the values of `scroll-conservatively' are considered.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Dmitry Gutov <dgutov <at> yandex.ru>
Cc: 13791 <at> debbugs.gnu.org
Subject: Re: bug#13791: 24.3.50; scroll-margin docstring says "recenter"
Date: Sat, 23 Feb 2013 22:19:56 +0200

> Date: Sat, 23 Feb 2013 23:19:32 +0400
> From: Dmitry Gutov <dgutov <at> yandex.ru>
> CC: 13791 <at> debbugs.gnu.org
> 
> On 23.02.2013 22:47, Eli Zaretskii wrote:
> >> Date: Sat, 23 Feb 2013 22:08:56 +0400
> >> From: Dmitry Gutov <dgutov <at> yandex.ru>
> >> CC: 13791 <at> debbugs.gnu.org
> >>
> >> But I'm not sure we're talking about the same thing.
> >
> > I think we are.
> >
> >> I meant to describe what will happen to the window when point "gets
> >> within this many lines of the top or bottom of the window", not when
> >> it moves outside the visible area.
> >
> > That's how I understood it.  But if you lean on the up or down key,
> > you can easily cause point go off the screen before Emacs enters
> > redisplay.
> 
> Yes, but in this case point is not "within this many lines of the top or 
> bottom of the window" anymore technically.

"Within this many lines of top" actually means higher than top + this
many lines (and similarly for bottom).

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

From: Noam Postavsky <npostavs <at> users.sourceforge.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 13791 <at> debbugs.gnu.org, Dmitry Gutov <dgutov <at> yandex.ru>
Subject: Re: bug#13791: 24.3.50; scroll-margin docstring says "recenter"
Date: Mon, 29 Jan 2018 18:28:24 -0500

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Dmitry Gutov <dgutov <at> yandex.ru>
>> Date: Sat, 23 Feb 2013 04:21:24 +0400
>> 
>> The docstring says: "Recenter the window whenever point gets within this
>> many lines of the top or bottom of the window."
>> 
>> That's not entirely accurate. Depending on the value of
>> `scroll-conservatively', the window may get scrolled instead.
>
> That's true.  However, how to describe this in a manner that will not
> confuse the reader is less clear.  "Recenter or scroll" is not very
> useful, IMO, as it doesn't say which will happen.  Suggestions are
> welcome.

Can't we just add a sentence?  "Depending the value of
`scroll-conservatively', the window may be scrolled instead of
recentered."  The details in `scroll-conservatively's docstring should
give sufficient accuracy.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Noam Postavsky <npostavs <at> users.sourceforge.net>
Cc: 13791 <at> debbugs.gnu.org, dgutov <at> yandex.ru
Subject: Re: bug#13791: 24.3.50; scroll-margin docstring says "recenter"
Date: Tue, 30 Jan 2018 15:56:24 +0200

> From: Noam Postavsky <npostavs <at> users.sourceforge.net>
> Cc: Dmitry Gutov <dgutov <at> yandex.ru>,  13791 <at> debbugs.gnu.org
> Date: Mon, 29 Jan 2018 18:28:24 -0500
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >> From: Dmitry Gutov <dgutov <at> yandex.ru>
> >> Date: Sat, 23 Feb 2013 04:21:24 +0400
> >> 
> >> The docstring says: "Recenter the window whenever point gets within this
> >> many lines of the top or bottom of the window."
> >> 
> >> That's not entirely accurate. Depending on the value of
> >> `scroll-conservatively', the window may get scrolled instead.
> >
> > That's true.  However, how to describe this in a manner that will not
> > confuse the reader is less clear.  "Recenter or scroll" is not very
> > useful, IMO, as it doesn't say which will happen.  Suggestions are
> > welcome.
> 
> Can't we just add a sentence?  "Depending the value of
> `scroll-conservatively', the window may be scrolled instead of
> recentered."  The details in `scroll-conservatively's docstring should
> give sufficient accuracy.

It's not just scroll-conservatively, AFAIR.

I actually like what the manual says better:

     The variable ‘scroll-margin’ restricts how close point can come to
  the top or bottom of a window (even if aggressive scrolling specifies a
  fraction F that is larger than the window portion between the top and
  the bottom margins).  Its value is a number of screen lines; if point
  comes within that many lines of the top or bottom of the window, Emacs
  performs automatic scrolling.

Note the last sentence: it leaves the exact manner of scrolling vague.

Would it be okay to say the same in the doc string?

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

From: Noam Postavsky <npostavs <at> users.sourceforge.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 13791 <at> debbugs.gnu.org, dgutov <at> yandex.ru
Subject: Re: bug#13791: 24.3.50; scroll-margin docstring says "recenter"
Date: Tue, 30 Jan 2018 22:42:21 -0500

tags 13791 fixed
close 13791 26.1
quit

Eli Zaretskii <eliz <at> gnu.org> writes:

> It's not just scroll-conservatively, AFAIR.
>
> I actually like what the manual says better:
>
>      The variable ‘scroll-margin’ restricts how close point can come to
>   the top or bottom of a window (even if aggressive scrolling specifies a
>   fraction F that is larger than the window portion between the top and
>   the bottom margins).  Its value is a number of screen lines; if point
>   comes within that many lines of the top or bottom of the window, Emacs
>   performs automatic scrolling.
>
> Note the last sentence: it leaves the exact manner of scrolling vague.
>
> Would it be okay to say the same in the doc string?

Makes sense, I added a similar note, with a link to the auto scrolling
manual page in emacs-26.

[1: db6564cde0]: 2018-01-30 22:29:13 -0500
  Fix scroll-margin docstring (Bug#13791)
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=db6564cde0a9001311c38600d61f503e9d32bf0b

Previous Next

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