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

From: Eli Zaretskii <[email-masked]>
Date: Tue, 30 Jan 2018 15:56:24 +0200

> From: Noam Postavsky <[email-masked]>
> Cc: Dmitry Gutov <[email-masked]>,  [email-masked]
> Date: Mon, 29 Jan 2018 18:28:24 -0500
> 
> Eli Zaretskii <[email-masked]> writes:
> 
> >> From: Dmitry Gutov <[email-masked]>
> >> 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?