bug#18992: 24.4; describe-mode

bug#18992: 24.4; describe-mode

[Andreas Röhler]

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
- mode-name often will be a quit shortened, as space in mode-line is precious
- don't see a usage of mode-name beyond mode-line
- user will be interested in value of major-mode, which isn't told

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

Thanks all,

Andreas Röhler

In GNU Emacs 24.4.1 (i686-pc-linux-gnu, X toolkit, Xaw3d scroll bars)
  of 2014-10-24
Windowing system distributor `The X.Org Foundation', version 11.0.11204000
System Description:	Debian GNU/Linux 7.7 (wheezy)

Important settings:
   value of $LANG: de_DE.utf8
   locale-coding-system: utf-8-unix

Major mode: Shell-script

Minor modes in effect:
   sh-electric-here-document-mode: t
   shell-dirtrack-mode: t
   tooltip-mode: t
   electric-indent-mode: t
   mouse-wheel-mode: t
   tool-bar-mode: t
   menu-bar-mode: t
   file-name-shadow-mode: t
   global-font-lock-mode: t
   font-lock-mode: t
   blink-cursor-mode: t
   auto-composition-mode: t
   auto-encryption-mode: t
   auto-compression-mode: t
   line-number-mode: t
   transient-mark-mode: t

Recent input:
<help-echo> C-h f d e s c r i b e - m o d e <return>
C-x o C-x 1 <down> <left> <left> <left> <left> <left>
<return> C-x 1 <help-echo> <help-echo> <help-echo>
<help-echo> <help-echo> <help-echo> <help-echo> <help-echo>
<help-echo> <help-echo> <help-echo> <help-echo> <help-echo>
<menu-bar> <options> <menu-set-font> C-s m o d e -
n a m e <left> M-x s h e l l <return> C-h v m a j p
r - <backspace> <backspace> <backspace> o r - m o <tab>
<return> C-x C-f <M-backspace> <M-backspace> <M-backspace>
<M-backspace> e i n . s h <return> C-h f <up> <return>
C-d C-g C-h v m a j o r - m o d e <return> s h - m
o d e C-x C-w <return> M-x d e s c r i b e - m o d
e <return> C-x o <down> <down> <down> <down> <down>
<down> <down> <down> <down> <down> C-SPC C-e M-w C-x
o M-x r e p o r t - e m a c s - b u g <return>

Recent messages:
(New file)
Setting up indent for shell type sh
Indentation variables are now local.
Indentation setup for shell type sh
Quit

You can run the command `describe-mode' with C-h m

Load-path shadows:
None found.

Features:
(shadow sort gnus-util mail-extr emacsbug message format-spec rfc822 mml
mml-sec mm-decode mm-bodies mm-encode mail-parse rfc2231 mailabbrev
gmm-utils mailheader sendmail rfc2047 rfc2045 ietf-drums mm-util
mail-prsvr mail-utils sh-script smie executable pp shell pcomplete
comint ansi-color ring misearch multi-isearch find-func help-mode
easymenu help-fns time-date tooltip electric uniquify ediff-hook
vc-hooks lisp-float-type mwheel x-win x-dnd tool-bar dnd fontset image
regexp-opt fringe tabulated-list newcomment lisp-mode prog-mode register
page menu-bar rfn-eshadow timer select scroll-bar mouse jit-lock
font-lock syntax facemenu font-core frame cham georgian utf-8-lang
misc-lang vietnamese tibetan thai tai-viet lao korean japanese hebrew
greek romanian slovak czech european ethiopic indian cyrillic chinese
case-table epa-hook jka-cmpr-hook help simple abbrev minibuffer nadvice
loaddefs button faces cus-face macroexp files text-properties overlay
sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote make-network-process inotify
dynamic-setting x-toolkit x multi-tty emacs)

Memory information:
((conses 8 122385 5181)
  (symbols 24 36505 0)
  (miscs 20 123 292)
  (strings 16 50339 4912)
  (string-bytes 1 680645)
  (vectors 8 11520)
  (vector-slots 4 437709 3282)
  (floats 8 67 468)
  (intervals 28 565 16)
  (buffers 512 16)
  (heap 1024 30852 417))

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

bug#18992: 24.4; describe-mode

[Andreas Röhler]

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

bug#18992: 24.4; describe-mode

[Drew Adams]

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

This is an improvement.

> 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):

Yes, that violates *Help* conventions.  It is better to use this
(or similar):

;; Document the minor modes fully.
(insert pretty-minor-mode)
(princ (format " minor mode:\n(`%s'; %s)\n"
       mode-function
       (if (zerop (length indicator))
           "no indicator"
         (format "indicator%s" indicator))))
(save-excursion
  (fill-region-as-paragraph
    (line-beginning-position 0) (line-end-position 0) nil t t))

bug#18992: 24.4; describe-mode

[Drew Adams]

> 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.

There is no variable `minor-mode'.  And users can find out about 
`major-mode' elsewhere.

bug#18992: 24.4; describe-mode

[Drew Adams]

> > 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):
> 
> Yes, that violates *Help* conventions.  It is better to use this
> (or similar): ...

Actually, we should do similarly for the major mode, even if major
mode names (including `mode-name') *tend* to be shorter.  It is good
behavior for functions printing unknown stuff to *Help* to ensure
that lines are not too long, when possible.

Something like this:

(princ " mode")
(let* ((mode       major-mode)
       (file-name  (find-lisp-object-file-name mode nil)))
  (when file-name
    (princ (concat " defined in `"
                   (file-name-nondirectory file-name) "'"))
    (with-current-buffer standard-output ; Hyperlink to library.
      (save-excursion (re-search-backward "`\\([^`']+\\)'" nil t)
                      (help-xref-button 1 'help-function-def
                                        mode file-name))))
  (with-current-buffer standard-output
    (insert (format " (`%s'):\n" mode))
    (save-excursion
      (fill-region-as-paragraph
        (line-beginning-position 0) (line-end-position 0) nil t t))))

bug#18992: 24.4; describe-mode

[Stefan Kangas]

Tassilo Horn <tsdh@gnu.org> writes:

> Well, but of course having the mode functions printed in `describe-mode'
> wouldn't hurt anyway.  This patch does that:
[...]
> With that, in this message buffer I get:
>
> 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:

I don't think this is an improvement.  It risks confusing more than it
helps, especially for beginning users.

We can already say `C-h v major-mode RET' which to my mind is wholly
sufficient for anyone who needs to know the value of the `major-mode'
variable.

> With the following patch, the same would be done for the active minor
> modes, too:
[...]
> 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):

I think this is even less of an improvement.

I suggest to close this as wontfix.  If I don't see any objections,
I'll just go ahead and do that within a couple of weeks.  Please send
any opinions on this issue before then.

Best regards,
Stefan Kangas

bug#18992: 24.4; describe-mode

[Stefan Kangas]

tags 18992 + wontfix notabug
close 18992
thanks

Stefan Kangas <stefan@marxist.se> writes:

> I suggest to close this as wontfix.  If I don't see any objections,
> I'll just go ahead and do that within a couple of weeks.  Please send
> any opinions on this issue before then.

No objections within 6 weeks; closing this bug now.

Best regards,
Stefan Kangas