bug#18992: 24.4; describe-mode

["Andreas Röhler" <andreas.roehler@easy-emacs.de>]

On 08.11.2014 15:34, Tassilo Horn wrote:
> 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
>

What about mentioning the variable at stake, i.e. "major-mode: " resp. "minor-mode: " in format-function?
As said, repeating the rather arbitrary mode-line string doesn't contribute, is confusing.

Thanks,

Andreas