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

[martin rudalics <rudalics@gmx.at>]

 > 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.

martin