bug#18992: 24.4; describe-mode

[Tassilo Horn]

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