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.

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)))
  (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 buffer
      (let (minors)
	;; Older packages do not register in minor-mode-list but only in
	;; minor-mode-alist.
	(dolist (x minor-mode-alist)
	  (setq x (car x))
	  (unless (memq x minor-mode-list)
	    (push x minor-mode-list)))
	;; Find enabled minor mode we will want to mention.
	(dolist (mode minor-mode-list)
	  ;; Document a minor mode if it is listed in minor-mode-alist,
	  ;; non-nil, and has a function definition.
	  (let ((fmode (or (get mode :minor-mode-function) mode)))
	    (and (boundp mode) (symbol-value mode)
		 (fboundp fmode)
		 (let ((pretty-minor-mode
			(if (string-match "\\(\\(-minor\\)?-mode\\)?\\'"
					  (symbol-name fmode))
			    (capitalize
			     (substring (symbol-name fmode)
					0 (match-beginning 0)))
			  fmode)))
		   (push (list fmode pretty-minor-mode
			       (format-mode-line (assq mode minor-mode-alist)))
			 minors)))))
	;; Narrowing is not a minor mode, but its indicator is part of
	;; mode-line-modes.
	(when (buffer-narrowed-p)
	  (push '(narrow-to-region "Narrow" " Narrow") minors))
	(setq minors
	      (sort minors
		    (lambda (a b) (string-lessp (cadr a) (cadr b)))))
	(when minors
	  (princ "Enabled minor modes:\n")
	  (make-local-variable 'help-button-cache)
	  (with-current-buffer standard-output
	    (dolist (mode minors)
	      (let ((mode-function (nth 0 mode))
		    (pretty-minor-mode (nth 1 mode))
		    (indicator (nth 2 mode)))
		(save-excursion
		  (goto-char (point-max))
		  (princ "\n\f\n")
		  (push (point-marker) help-button-cache)
		  ;; Document the minor modes fully.
                  (insert-text-button
                   pretty-minor-mode 'type 'help-function
                   'help-args (list mode-function)
                   'button '(t))
		  (princ (format " minor mode (%s):\n"
				 (if (zerop (length indicator))
				     "no indicator"
				   (format "indicator%s"
					   indicator))))
		  (princ (help-split-fundoc (documentation mode-function)
                                            nil 'doc)))
		(insert-button pretty-minor-mode
			       'action (car help-button-cache)
			       'follow-link t
			       'help-echo "mouse-2, RET: show full information")
		(newline)))
	    (forward-line -1)
	    (fill-paragraph nil)
	    (forward-line 1))

	  (princ "\n(Information about these minor modes follows the major mode info.)\n\n"))
	;; Document the major mode.
	(let ((mode mode-name))
	  (with-current-buffer standard-output
            (let ((start (point)))
              (insert (format-mode-line mode nil nil buffer))
              (add-text-properties start (point) '(face bold)))))
	(princ " mode")
	(let* ((mode major-mode)
	       (file-name (find-lisp-object-file-name mode nil)))
	  (if (not file-name)
              (setq help-mode--current-data (list :symbol mode))
	    (princ (format-message " defined in `%s'"
                                   (help-fns-short-filename file-name)))
	    ;; Make a hyperlink to the library.
	    (with-current-buffer standard-output
	      (save-excursion
		(re-search-backward (substitute-command-keys "`\\([^`']+\\)'")
                                    nil t)
                (setq help-mode--current-data (list :symbol mode
                                                    :file file-name))
                (help-xref-button 1 'help-function-def mode file-name)))))
        (let ((fundoc (help-split-fundoc (documentation major-mode) nil 'doc)))
          (with-current-buffer standard-output
            (insert ":\n")
            (insert fundoc)
            (insert (help-fns--list-local-commands)))))))
  ;; For the sake of IELM and maybe others
  nil)