eintr: New insert-buffer
5.2.6 New Body for ‘insert-buffer’
----------------------------------
The body in the GNU Emacs 22 version is more confusing than the
original.
It consists of two expressions,
(push-mark
(save-excursion
(insert-buffer-substring (get-buffer buffer))
(point)))
nil
except, and this is what confuses novices, very important work is done
inside the ‘push-mark’ expression.
The ‘get-buffer’ function returns a buffer with the name provided.
You will note that the function is _not_ called ‘get-buffer-create’; it
does not create a buffer if one does not already exist. The buffer
returned by ‘get-buffer’, an existing buffer, is passed to
‘insert-buffer-substring’, which inserts the whole of the buffer (since
you did not specify anything else).
The location into which the buffer is inserted is recorded by
‘push-mark’. Then the function returns ‘nil’, the value of its last
command. Put another way, the ‘insert-buffer’ function exists only to
produce a side effect, inserting another buffer, not to return any
value.