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
string of characters from part of a buffer, a “substring”, and
inserts them into another buffer.
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 the complete text 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
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.)