bug#18739: 24.3; Request for a hook to be provided when scrolling will move the cursor

[Stefan Monnier <monnier@iro.umontreal.ca>]

>> >> It would be helpful to have a hook that would be called before any
>> >> scrolling command moves the cursor.  In other words, I want to be
>> >> notified when an update to the display will force the location of
>> >> `point' to change in the current buffer.
>> > What's wrong with window-scroll-functions?
>> But these are also called when point is not affected, right?
> Yes.  But it's easy to detect that situation, I think.

Is it?

I think the main reason why I ask is because I truly have no idea when
window-scroll-functions is called.  You seem to be somewhat familiar
with it, so could you try and clarify it in the docstring?

Currently I see "List of functions to call before redisplaying a window
with scrolling" and "Note that these functions are also called by
`set-window-buffer'".

Here are some of the questions this brings up for me:
- is it called during set-window-buffer itself, or is it called in the
  first redisplay after set-window-buffer?
- what means "redisplaying a window with scrolling" exactly?  Does it
  mean "redisplay with a different window-start then during the last
  redisplay"?  Does that include the case where window-start is changed
  so as to follow point or is it only the cases where window-start was
  changed explicitly by a scrolling command?
- how could a window-scroll-function distinguish the 3 cases:
  "set-window-buffer", "used a scroll command", "moved point out of viewport".

I tried already a few times to understand window-scroll-functions, but
so far it has eluded me.  FWIW, I found 3 kinds of uses:
- A crutch from when jit-lock didn't exist (in linum and lazy-lock).
- A way to try and keep a window fully empty showing only point-max by
  calling set-window-start with the same window-start (in follow-mode).
  Not clear exactly why this should work, and arguably goes against the
  warning in window-scroll-functions's docstring.
- Do fancy auto-scrolling in eshell/em-smart (which does exactly what
  window-scroll-functions's docstring warns not to do, AFAICT), calling
  redisplay internally.


        Stefan