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.

When describe-mode-outline is non-nil, Outline minor mode is enabled in the Help 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.

When `describe-mode-outline' is non-nil, Outline minor mode
is enabled in the Help 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
          (unless describe-mode-outline
            (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)))
          (when describe-mode-outline
            (goto-char (point-min))
            (put-text-property
             (point) (progn (insert (format "Major mode %S" major)) (point))
             'outline-level 1)
            (insert "\n\n"))
          (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"
                            (buttonize
                             (help-fns-short-filename file-name)
                             (lambda (_)
                               (help-function-def--button-function
                                major file-name))))))
          (insert ":\n\n"
                  (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
            (unless describe-mode-outline
              (insert (format "Global minor mode%s enabled:"
                              (if (length> global-minor-modes 1)
                                  "s" ""))))
            (describe-mode--minor-modes global-minor-modes t)
            (unless describe-mode-outline
              (when (re-search-forward "^\f")
                (beginning-of-line)
                (ensure-empty-lines 1))))

          (when describe-mode-outline
            (setq-local outline-search-function #'outline-search-level)
            (setq-local outline-level (lambda () 1))
            (setq-local outline-minor-mode-cycle t
                        outline-minor-mode-highlight t
                        outline-minor-mode-use-buttons 'insert)
            (outline-minor-mode 1))

          ;; For the sake of IELM and maybe others
          nil)))))