An Overview of append-to-buffer

The append-to-buffer command uses the insert-buffer-substring function to copy the region. insert-buffer-substring is described by its name: it takes a substring from a buffer, and inserts it into another buffer.

Most of append-to-buffer is concerned with setting up the conditions for insert-buffer-substring to work: the code must specify both the buffer to which the text will go, the window it comes from and goes to, and the region that will be copied.

Here is a possible implementation of the function:

(defun append-to-buffer (buffer start end)
  "Append to specified buffer the text of the region.
It is inserted into that buffer before its point.

When calling from a program, give three arguments:
BUFFER (or buffer name), START and END.
START and END specify the portion of the current buffer to be copied."
  (interactive
   (list (read-buffer "Append to buffer: " (other-buffer
                                            (current-buffer) t))
         (region-beginning) (region-end)))

  (let ((oldbuf (current-buffer)))
    (save-excursion
      (let* ((append-to (get-buffer-create buffer))
             (windows (get-buffer-window-list append-to t t))
             point)
        (set-buffer append-to)
        (setq point (point))
        (barf-if-buffer-read-only)
        (insert-buffer-substring oldbuf start end)
        (dolist (window windows)
          (when (= (window-point window) point)
            (set-window-point window (point))))))))

The function can be understood by looking at it as a series of filled-in templates.

The outermost template is for the function definition. In this function, it looks like this (with several slots filled in):

(defun append-to-buffer (buffer start end)
  "documentation…"
  (interactive …)
  body…)

The first line of the function includes its name and three arguments. The arguments are the buffer to which the text will be copied, and the start and end of the region in the current buffer that will be copied.

The next part of the function is the documentation, which is clear and complete. As is conventional, the three arguments are written in upper case so you will notice them easily. Even better, they are described in the same order as in the argument list.

Note that the documentation distinguishes between a buffer and its name. (The function can handle either.)