scroll-margin - does it work as advertized?

["Drew Adams" <drew.adams@oracle.com>]

I've read the doc (Emacs and Elisp manuals, and doc string) for `scroll-margin',
and what I understand from that doc doesn't seem to correspond to the behavior I
see. If others don't think there is a bug, then perhaps someone can help me
understand better how this option works.

My understanding from the doc is that you cannot move the window point to within
`scroll-margin' lines of the top or bottom of the window - as soon as you try to
do so, the window is scrolled to move the window point `scroll-margin' lines
from the top or bottom.

What I see, however, is that the effective margin as I (mis?)understand it is
sometimes much smaller than the value of `scroll-margin'. And any
`scroll-margin' value greater than about 1/3 of the window height seems to give
the same effective margin. I see this in both Emacs 22 and 23 (which supports my
guess that I'm misunderstanding the doc).

If I set `scroll-margin' to 5 or 10, then, with a window-height of 39
(window-text-height of 38), I can move the window point to within 6 or 10 lines
of the top or bottom, but not to within 5 or 9 lines. That's about what I would
expect (I'd expect 10 instead of 9).

But if I set `scroll-margin' to 20 or 15 (same window height), then I can move
the window point to within 10 lines of the top or bottom, but not to within 8
(bottom) or 9 lines (top).

Similarly, with a window-height of 27 and a `scroll-margin' of 20, 15, or 10, I
can move the window point to within 7 lines of the top or bottom, but not to
within 6 lines. With a `scroll-margin' of 5, I get the behavior I'd expect:
can't get within 5 lines of the top/bottom.

That the window-height affects the behavior of `scroll-margin' doesn't surprise
me (though that fact and just how it affects it do not seem to be documented).
It's how it seems to affect it that puzzles me. I would expect that if the value
`scroll-margin' is >= half of the window height, then the cursor would just stay
in the middle of the window, since Emacs would try to keep the window point at
least `scroll-margin' from both top and bottom.

In one particular context, keeping the window point in the middle of the window
is the behavior I was looking for: keep the window point fixed relative to the
window, while scrolling the text relative to the window, when I move point.

That is somewhat like what `scroll-preserve-screen-position' does, but for
point-movement commands, not scroll commands. I wanted the window point's line
to remain fixed wrt the window, regardless of how I move point relative to the
buffer. IOW, in this particular context, I want the window to follow the cursor
as I move point, and I want the window point's line to remain constant.

What is a good way to get that behavior using vanilla Emacs? I've since found a
couple of things on Emacs Wiki that offer this behavior, in particular this
library:
http://www.emacswiki.org/cgi-bin/emacs/centered-cursor-mode.el, by Andre
Riemann. It keeps the cursor centered in the window, as you move point.

That library does what I was looking for. But beyond meeting that particular use
case, I wonder what I'm missing wrt how `scroll-margin' works, or should work.