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,

     (insert-buffer-substring (get-buffer buffer))


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.