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

-- 
Juri Linkov
http://www.jurta.org/emacs/