bug#20421: 25.0.50; doc string of `insert-buffer-substring'

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

>  > I think that reader misunderstood something else: the difference
>  > between point and window-point.
>
> IIUC the issue at hand is more contrived.  Conceptually, `window-
> point' prescribes the position where to display the cursor in the
> corresponding window and `window-point-insertion-type' prescribes
> how the cursor should move when text is inserted at that position.  
> But we also say:
> 
>    As long as the selected window displays the current buffer, the
>    window's point and the buffer's point always move together; they
>    remain equal.
> 
> So inherently Emacs does override [at least the default value which
> is nil of] `window-point-insertion-type' when appending at `window-
> point' in the selected window.
> 
> Now apparently that code in `append-to-buffer'
> 
>          (dolist (window windows)
>            (when (= (window-point window) point)
>              (set-window-point window (point))))
> 
> tries to mimic the same behavior for all non-selected windows that
> show the same buffer and whose `window-point' equals the pre-append
> position of `point' in that buffer.
> 
> Our reader should be able to see why this code makes a difference
> with emacs -Q as follows:
> 
> - Make a frame with two windows showing the same buffer
> - Make one of these windows the selected one
> - Make sure that both windows have the same value of `window-point'
>    (show the cursor at the same position)
> - Call `append-to-buffer' to add some text to these windows' buffer.
> 
> With the code above, both windows should have the same value of
> `window-point' now.  Without that code, the point of the non-
> selected window should have staid behind the added text.
> 
> I have no idea why `append-to-buffer' deliberately overrides the
> value of `window-point-insertion-type' or why the default value of
> `window-point-insertion-type' is nil.  Maybe Stefan can clarify.

Good info, which helps supplement the Q&A at SE (which links to
this thread).

I wasn't even aware of `window-point-insertion-type', which was
introduced in Emacs 23 apparently.