Function: describe-mode

describe-mode is an autoloaded, interactive and byte-compiled function defined in help-fns.el.gz.

Signature

(describe-mode &optional BUFFER)

Documentation

Display documentation of current major mode and minor modes.

A brief summary of the minor modes comes first, followed by the major mode description. This is followed by detailed descriptions of the minor modes, each on a separate page.

For this to work correctly for a minor mode, the mode's indicator variable (listed in minor-mode-alist) must also be a function whose documentation describes the minor mode.

If called from Lisp with a non-nil BUFFER argument, display documentation for the major and minor modes of that buffer.

View in manual

Probably introduced at or before Emacs version 29.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/help-fns.el.gz
;;;###autoload
(defun describe-mode (&optional buffer)
  "Display documentation of current major mode and minor modes.
A brief summary of the minor modes comes first, followed by the
major mode description.  This is followed by detailed
descriptions of the minor modes, each on a separate page.

For this to work correctly for a minor mode, the mode's indicator
variable \(listed in `minor-mode-alist') must also be a function
whose documentation describes the minor mode.

If called from Lisp with a non-nil BUFFER argument, display
documentation for the major and minor modes of that buffer."
  (interactive "@")
  (unless buffer
    (setq buffer (current-buffer)))
  (let ((help-buffer-under-preparation t)
        (local-minors (buffer-local-value 'local-minor-modes buffer)))
    (help-setup-xref (list #'describe-mode buffer)
		     (called-interactively-p 'interactive))
    ;; For the sake of help-do-xref and help-xref-go-back,
    ;; don't switch buffers before calling `help-buffer'.
    (with-help-window (help-buffer)
      (with-current-buffer (help-buffer)
        ;; Add the local minor modes at the start.
        (when local-minors
          (insert (format "Minor mode%s enabled in this buffer:"
                          (if (length> local-minors 1)
                              "s" "")))
          (describe-mode--minor-modes local-minors))

        ;; Document the major mode.
        (let ((major (buffer-local-value 'major-mode buffer)))
          (insert "The major mode is "
                  (buttonize
                   (propertize (format-mode-line
                                (buffer-local-value 'mode-name buffer)
                                nil nil buffer)
                               'face 'bold)
                   (lambda (_)
                     (describe-function major))))
          (insert " mode")
          (when-let ((file-name (find-lisp-object-file-name major nil)))
	    (insert (format " defined in %s:\n\n"
                            (buttonize
                             (help-fns-short-filename file-name)
                             (lambda (_)
                               (help-function-def--button-function
                                major file-name))))))
          (insert (help-split-fundoc (documentation major) nil 'doc)
                  (with-current-buffer buffer
                    (help-fns--list-local-commands)))
          (ensure-empty-lines 1)

          ;; Insert the global minor modes after the major mode.
          (when global-minor-modes
            (insert (format "Global minor mode%s enabled:"
                            (if (length> global-minor-modes 1)
                                "s" "")))
            (describe-mode--minor-modes global-minor-modes)
            (when (re-search-forward "^\f")
              (beginning-of-line)
              (ensure-empty-lines 1)))
          ;; For the sake of IELM and maybe others
          nil)))))