bug#18992: 24.4; describe-mode

[Tassilo Horn <tsdh@gnu.org>]

Andreas Röhler <andreas.roehler@easy-emacs.de> writes:

> M-x describe-mode RET should report the major-mode.
> Currently it tells the value of "mode-name".
>
> Several issues with this:
>
> - Value of mode-name is displayed in current-buffers mode-line allready

I guess the main usage of `describe-mode' is to get its documentation
and key bindings.

> - mode-name often will be a quit shortened, as space in mode-line is precious

Usually it's just the capitalized version of the major-mode function
with the `-mode' stripped.  And sometimes it contains more information
that just the mode function, e.g., "Dired by name", "Dired by date",
etc.

> - don't see a usage of mode-name beyond mode-line

The other important usage is printing the pretty name with
describe-mode. ;-)

> - user will be interested in value of major-mode, which isn't told

describe-mode prints a link you can click to jump to the major-mode
function.

> See for example from inside a M-x shell RET
>
> M-x describe-mode says: "Shell mode"
> while the real major-mode is sh-mode

No, the real mode function is `shell-mode'.  `sh-mode' is the editing
mode for shell scripts, and that has mode-names like "Shell-script[zsh]"
or "Shell-script[bash]" which are even more informative than just the
plain mode function.

Well, but of course having the mode functions printed in `describe-mode'
wouldn't hurt anyway.  This patch does that:

--8<---------------cut here---------------start------------->8---
=== modified file 'lisp/help.el'
--- lisp/help.el	2014-08-07 03:25:09 +0000
+++ lisp/help.el	2014-11-08 14:27:54 +0000
@@ -946,7 +946,8 @@
             (let ((start (point)))
               (insert (format-mode-line mode nil nil buffer))
               (add-text-properties start (point) '(face bold)))))
-	(princ " mode")
+	(princ " mode ")
+	(princ (format "(`%s')" major-mode))
 	(let* ((mode major-mode)
 	       (file-name (find-lisp-object-file-name mode nil)))
 	  (when file-name
--8<---------------cut here---------------end--------------->8---

With that, in this message buffer I get:

--8<---------------cut here---------------start------------->8---
Message mode (`message-mode') defined in `message.el':
Major mode for editing mail and news to be sent.
Like Text Mode but with these additional commands:
...
--8<---------------cut here---------------end--------------->8---

With the following patch, the same would be done for the active minor
modes, too:

--8<---------------cut here---------------start------------->8---
=== modified file 'lisp/help.el'
--- lisp/help.el	2014-08-07 03:25:09 +0000
+++ lisp/help.el	2014-11-08 14:31:30 +0000
@@ -924,7 +924,8 @@
 		  (push (point-marker) help-button-cache)
 		  ;; Document the minor modes fully.
 		  (insert pretty-minor-mode)
-		  (princ (format " minor mode (%s):\n"
+		  (princ (format " minor mode (`%s'; %s):\n"
+				 mode-function
 				 (if (zerop (length indicator))
 				     "no indicator"
 				   (format "indicator%s"
@@ -946,7 +947,8 @@
             (let ((start (point)))
               (insert (format-mode-line mode nil nil buffer))
               (add-text-properties start (point) '(face bold)))))
-	(princ " mode")
+	(princ " mode ")
+	(princ (format "(`%s')" major-mode))
 	(let* ((mode major-mode)
 	       (file-name (find-lisp-object-file-name mode nil)))
 	  (when file-name
--8<---------------cut here---------------end--------------->8---

However, in contrast to major-modes, minor mode names tend to be much
longer, so we can get some long lines like:

Global-Edit-Server-Edit minor mode (`global-edit-server-edit-mode'; no indicator):

Bye,
Tassilo