Breaks with scroll-magin>0
I'm glad I've found iscroll! It seems to be the only way to scroll through images which are taller than the current buffer. Thanks for that!
I noticed though that it behaves poorly when scroll-margin is set to any non-zero value. The behavior is really hard to describe (in some cases it behaves as if scroll-margin was zero, otherwise it results in unpredictable jumps), so the best way to experience this is to a have a buffer with some inline images and set scroll-margin to a non-zero value (I normally use 5).
If the image is on the edge of the buffer, attempting to scroll through it breaks iscroll and scroll-margin at the same time.
IIRC I tried to fix it and failed. The redisplay logic around this area is rather convoluted. I can try again when I find some time, of course. I use this function to scroll without moving the relative position of point in the window, maybe you can use this and set scroll margin to 0 like I do.
(defvar luna-scroll-map
(let ((map (make-sparse-keymap)))
(define-key map (kbd "n") #'luna-scroll-up-reserve-point)
(define-key map (kbd "s-n") #'luna-scroll-up-reserve-point)
(define-key map (kbd "p") #'luna-scroll-down-reserve-point)
(define-key map (kbd "s-n") #'luna-scroll-up-reserve-point)
map)
"Transient map for `luna-scroll-mode'.")
(defun luna-scroll-down-reserve-point ()
"Scroll down `luna-scroll-amount' lines.
Keeps the relative position of point against window."
(interactive)
(scroll-down 3)
(vertical-motion -3)
;; Prevent me from accidentally inserting n and p.
(set-transient-map luna-scroll-map t))
(defun luna-scroll-up-reserve-point ()
"Scroll up `luna-scroll-amount' lines.
Keeps the relative position of point against window."
(interactive)
(scroll-up 3)
(vertical-motion 3)
(set-transient-map luna-scroll-map t))
scroll-margin does behave weird in some contexts (I fixed a few bugs myself in emacs regarding this) so I'm not too surprised.
Maybe an interim solution would be to let-bind scroll-margin to 0 while doing iscroll within an image? This would at least avoid some of broken while you're "inside" the image.
Ironically I frequently use C-y/C-e in vim to scroll manually the buffer without moving the point, but I have to say I really prefer scroll-margin in general to always keep some context around. Scroll-margin and the cycling C-l is something I wouldn't have expected to like ;)