Info Catalog eintr: append-to-buffer eintr: append interactive

eintr: append-to-buffer overview

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

Info Catalog eintr: append-to-buffer eintr: append interactive