docstring of display-completion-list

[Roland Winkler]

In GNU Emacs 21.1.1 (i386-pc-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2002-02-01 on tfkp12
configured using `configure  --prefix=/nfs/common --libexecdir=/nfs/common/lib 
--bindir=/nfs/common/lib/emacs/21.1/bin/i686-Linux 
--mandir=/nfs/common/share/man --infodir=/nfs/common/share/info --with-gcc 
--with-pop --with-x --with-x-toolkit=athena i386-pc-linux'
Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: POSIX
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en_US
  locale-coding-system: iso-latin-1
  default-enable-multibyte-characters: nil

Attached below is the code of a function my-complete-symbol. Most of
the code I borrowed from lisp-complete-symbol. The function works
completely as expected. However, according to the docstring of
display-completion-list used at the end of this function there is
one thing I do not understand at all:

If I choose a completion from the `*Completions*' buffer, why is the
text inserted in the buffer from where I called my-complete-symbol?

According to the docstring of display-completion-list it runs the
hook completion-setup-hook which (I think by default) calls the
undocumented function completion-setup-function. Is the latter
inserting the completion in the buffer from where I called
my-complete-symbol?

It appears to me that I am using an undocumented feature. Or am I
missing something here?

Roland


(defun my-complete-symbol ()
  "Perform completion on symbol preceding point.
Compare that symbol against `my-completion-alist'."
  ;; Code borrowed from lisp-complete-symbol.
  (interactive)
  (let* ((end (point))
         ;; The following probably can be improved
         (beg (save-excursion
                (backward-sexp 1)
                (while (= (char-syntax (following-char)) ?\')
                  (forward-char 1))
                (point)))
         (pattern (buffer-substring-no-properties beg end))
         (completion (try-completion pattern my-completion-alist)))
    (cond ((eq completion t))
          ((null completion)
           (message "Can't find completion for \"%s\"" pattern)
           (ding))
          ((not (string= pattern completion))
           (delete-region beg end)
           (insert completion))
          (t
           (message "Making completion list...")
           (let ((list (sort (all-completions pattern my-completion-alist)
                             'string<)))
             (with-output-to-temp-buffer "*Completions*"
               (display-completion-list list)))
           (message "Making completion list...%s" "done")))))