insert-buffer vs insert-buffer-substring

[Juri Linkov]

`insert-buffer-substring' is not equivalent to `insert-buffer' in regard
to the point position after calling these functions. `insert-buffer' leaves
point before inserted text, but `insert-buffer-substring' - after it.

I just fixed a bug in info.el caused by replacing `insert-buffer' with
`insert-buffer-substring'. Instead of `(insert-buffer-substring buffer)',
I added the following construct:

(goto-char (prog1 (point) (insert-buffer-substring buffer)))

Is it the right replacement? Shouldn't it be documented in the
docstring of `insert-buffer' which currently says:

This function is meant for the user to run interactively.
Don't call it from programs: use `insert-buffer-substring' instead!

which gives the impression that `insert-buffer-substring' is
a complete equivalent of `insert-buffer'.

[Richard M. Stallman]

I just fixed a bug in info.el caused by replacing `insert-buffer' with
`insert-buffer-substring'. Instead of `(insert-buffer-substring buffer)',

Sorry. I didn't see that the change caused a problem.

I added the following construct:

(goto-char (prog1 (point) (insert-buffer-substring buffer)))

That is rather idiomatic. I would prefer

(let ((foo (point)))
(insert-buffer-substring buffer)
(goto-char (point)))

However, for this particular job, you can do

(save-excursion
(insert-buffer-substring buffer))