bug#13791: 24.3.50; scroll-margin docstring says "recenter"

bug#13791: 24.3.50; scroll-margin docstring says "recenter"

[Dmitry Gutov]

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@gmx.de-20130219151755-yklhdrlp26loxg2v

bug#13791: 24.3.50; scroll-margin docstring says "recenter"

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@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.

bug#13791: 24.3.50; scroll-margin docstring says "recenter"

[Dmitry Gutov]

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.

bug#13791: 24.3.50; scroll-margin docstring says "recenter"

[Eli Zaretskii]

> Date: Sat, 23 Feb 2013 17:08:35 +0400
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: 13791@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.

bug#13791: 24.3.50; scroll-margin docstring says "recenter"

[Dmitry Gutov]

On 23.02.2013 18:50, Eli Zaretskii wrote:
>> Date: Sat, 23 Feb 2013 17:08:35 +0400
>> From: Dmitry Gutov <dgutov@yandex.ru>
>> CC: 13791@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.

bug#13791: 24.3.50; scroll-margin docstring says "recenter"

[Eli Zaretskii]

> Date: Sat, 23 Feb 2013 22:08:56 +0400
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: 13791@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.

bug#13791: 24.3.50; scroll-margin docstring says "recenter"

[Dmitry Gutov]

On 23.02.2013 22:47, Eli Zaretskii wrote:
>> Date: Sat, 23 Feb 2013 22:08:56 +0400
>> From: Dmitry Gutov <dgutov@yandex.ru>
>> CC: 13791@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.

bug#13791: 24.3.50; scroll-margin docstring says "recenter"

[Eli Zaretskii]

> Date: Sat, 23 Feb 2013 23:19:32 +0400
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: 13791@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@yandex.ru>
> >> CC: 13791@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).

bug#13791: 24.3.50; scroll-margin docstring says "recenter"

[Noam Postavsky]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Dmitry Gutov <dgutov@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.

bug#13791: 24.3.50; scroll-margin docstring says "recenter"

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@users.sourceforge.net>
> Cc: Dmitry Gutov <dgutov@yandex.ru>,  13791@debbugs.gnu.org
> Date: Mon, 29 Jan 2018 18:28:24 -0500
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Dmitry Gutov <dgutov@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?

bug#13791: 24.3.50; scroll-margin docstring says "recenter"

[Noam Postavsky]

tags 13791 fixed
close 13791 26.1
quit

Eli Zaretskii <eliz@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