Thank you Po, for your explanations. Indeed this clears things
up a little, but unfortunately my question was not 'precise enough',
for the answer to 'solve' the issue that motivated this question.
(I wanted to keep my `image-mode.el` out of the question, but I
guess it is necessary to add it to explain the issue I am experiencing).
So I have rewritten `image-mode.el` to scroll by `line + vscroll` instead
of using vscroll only. This solves the issue with the RAM usage for
'large documents'.
Additionally, it made the code a little 'simpler', which is a welcome 'side effect'
(I got rid of the 'gap' (page separation) overlays, and instead added margins
to the images. So now the buffer contents is just single spaces on separate
lines, where the number of lines is equal to the number of `images/pages`.
The 'gap' color can be configured by adding the overlay's face background).
It seems to work mostly correct (the 'scrolling' look a tiny bit less smooth than
with the pure vscroll version, but I would say it is very acceptable).
Anyway, I hope someone can quickly have a look at the issue explained below
(this should take less than a minute). So let me quickly provide some context
for the issue.
Currently, each overlay is overlaid on a single space on separate lines. So the
contents of the buffer is a single space (holding a page overlay) on every line.
So to jump to the next page, I can simply use 'forward-line'. Now this works fine
when the page is 'off-window` but when the next page is already within view
('on-window'), then going to the next line does not position that line at the top of
the window, nor makes it the current `window-start. To get it at the top of the
window, I could subsequently call `(set-window-start nil (point))`,
but then subsequently, `set-window-vscroll` does not work. To make
`set-window-vscroll` have effect, I can add a `redisplay` just before I call it.
This works, but the 'jump' gets very/unacceptably ugly (you see the 'recentering'
steps taking place).
However, when the next page is 'off-window' than using the 'forward-line' works
directly, and the page jump looks smooth.
So to reproduce it from `emacs -Q` you can just load the `image-roll.el` file that I
will attach here, then do `M-x image-roll-demo` and scroll down using the arrow
keys until you see the page transition between page one and two. Now press the
`page down` (PgDn) button to jump to the next page.
Because page two is already 'on-window' this only moves the cursor one page down.
If you now press a second time `PgDn` then, because page 3 is still `off-window`,
the jump takes place how it should.
I would be happy, if someone could tell me how I could 'solve' this issue. Otherwise,
all scrolling functions work fine, although I did not yet take care of the 'edge cases'
(i.e. first and last page). Also, I did not update the docstrings yet, so I am not asking
for feedback on those. My only question is if someone could have a look at what I am
describing above.