Function: describe-key

describe-key is an interactive and byte-compiled function defined in help.el.gz.

Signature

(describe-key KEY-LIST &optional BUFFER)

Documentation

Display documentation of the function invoked by KEY-LIST.

KEY-LIST can be any kind of a key sequence; it can include keyboard events, mouse events, and/or menu events. When calling from a program, pass KEY-LIST as a list of elements (SEQ . RAW-SEQ) where SEQ is a key-sequence and RAW-SEQ is its untranslated form.

While reading KEY-LIST interactively, this command temporarily enables menu items or tool-bar buttons that are disabled to allow getting help on them.

BUFFER is the buffer in which to lookup those keys; it defaults to the current buffer.

Probably introduced at or before Emacs version 22.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/help.el.gz
(defun describe-key (&optional key-list buffer up-event)
  "Display documentation of the function invoked by KEY-LIST.
KEY-LIST can be any kind of a key sequence; it can include keyboard events,
mouse events, and/or menu events.  When calling from a program,
pass KEY-LIST as a list of elements (SEQ . RAW-SEQ) where SEQ is
a key-sequence and RAW-SEQ is its untranslated form.

While reading KEY-LIST interactively, this command temporarily enables
menu items or tool-bar buttons that are disabled to allow getting help
on them.

BUFFER is the buffer in which to lookup those keys; it defaults to the
current buffer."
  (declare (advertised-calling-convention (key-list &optional buffer) "27.1"))
  (interactive (list (help--read-key-sequence)))
  (when (arrayp key-list)
    ;; Compatibility with old calling convention.
    (setq key-list (cons (list key-list) (if up-event (list up-event))))
    (when buffer
      (let ((raw (if (numberp buffer) (this-single-command-raw-keys) buffer)))
        (setf (cdar (last key-list)) raw)))
    (setq buffer nil))
  (let* ((buf (or buffer (current-buffer)))
         (on-link
          (mapcar (lambda (kr)
                    (let ((raw (cdr kr)))
                      (and (not (memq mouse-1-click-follows-link '(nil double)))
                           (> (length raw) 0)
                           (eq (car-safe (aref raw 0)) 'mouse-1)
                           (with-current-buffer buf
                             (mouse-on-link-p (event-start (aref raw 0)))))))
                  key-list))
         (info-list
          (help--filter-info-list
           (with-current-buffer buf
             (mapcar (lambda (x)
                       (pcase-let* ((`(,seq . ,raw-seq) x)
                                    (`(,brief-desc ,defn ,event ,_mouse-msg)
                                     (help--analyze-key seq raw-seq buffer))
                                    (locus
                                     (help--binding-locus
                                      seq (event-start event))))
                         `(,seq ,brief-desc ,defn ,locus)))
                     key-list))
           2)))
    (help-setup-xref (list #'describe-key--helper key-list buf)
		     (called-interactively-p 'interactive))
    (if (and (<= (length info-list) 1)
             (help--binding-undefined-p (nth 2 (car info-list))))
        (message "%s" (nth 1 (car info-list)))
      (with-help-window (help-buffer)
        (when (> (length info-list) 1)
          ;; FIXME: Make this into clickable hyperlinks.
          (princ "There were several key-sequences:\n\n")
          (princ (mapconcat (lambda (info)
                              (pcase-let ((`(,_seq ,brief-desc ,_defn ,_locus)
                                           info))
                                (concat "  " brief-desc)))
                            info-list
                            "\n"))
          (when (delq nil on-link)
            (princ "\n\nThose are influenced by `mouse-1-click-follows-link'"))
          (princ "\n\nThey're all described below."))
        (pcase-dolist (`(,_seq ,brief-desc ,defn ,locus)
                       info-list)
          (when defn
            (when (> (length info-list) 1)
              (with-current-buffer standard-output
                (insert "\n\n" (make-separator-line) "\n")))

            (princ brief-desc)
            (when locus
              (princ (format " (found in %s)" locus)))
            (princ ", which is ")
	    (describe-function-1 defn)))))))