bug#1164: 23.0.60; Doc strings of mode-name, mode-line-format and format-mode-line

bug#1164: 23.0.60; Doc strings of mode-name, mode-line-format and format-mode-line

[Eli Zaretskii]

Please write in English if possible, because the Emacs maintainers
usually do not have translators to read other languages for them.

Your bug report will be posted to the emacs-pretest-bug@gnu.org mailing list.

Please describe exactly what actions triggered the bug
and the precise symptoms of the bug:

"C-h v mode-name RET" produces:

    mode-name is a variable defined in `buffer.c'.
    Its value is "Emacs-Lisp"
    Local in buffer bindings.el; global value is 0

      Automatically becomes buffer-local when set in any fashion.

    Documentation:
    Pretty name of current buffer's major mode.
    Usually a string.  See `mode-line-format' for other possible forms.
    Use the function `format-mode-line' to get the value as a string.

The line before the last refers to mode-line-format for possible forms
of mode-name.  However, nothing in the doc string of mode-line-format
says anything specific about the form of mode-name, and neither does
the doc string of format-mode-line say anything about how to produce a
string out of mode-name.

In general, I loathe references to other doc strings for important
information: it's a nuisance to chase multiple links when you need to
do a simple job such as displaying the mode name.  Unless the
information is large and complex, it is better to reproduce it where
it is needed, even if that requires some duplication.

If Emacs crashed, and you have the Emacs process in the gdb debugger,
please include the output from the following gdb commands:
    `bt full' and `xbacktrace'.
If you would like to further debug the crash, please read the file
d:/gnu/emacs/etc/DEBUG for instructions.


In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-10-14 on HOME-C4E4A596F7
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: ENU
  value of $XMODIFIERS: nil
  locale-coding-system: cp1255
  default-enable-multibyte-characters: t

Major mode: Emacs-Lisp

Minor modes in effect:
  show-paren-mode: t
  tooltip-mode: t
  tool-bar-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  global-auto-composition-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <prior> 
C-x C-f <M-backspace> <M-backspace> l i s <tab> / b 
i n d <tab> <return> C-s m o d e <M-left> <next> <next> 
C-s m a j <up> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <next> C-s C-s <up> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <prior> <prior> <prior> <next> 
<next> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <up> <up> <up> <up> <up> 
<up> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <next> <next> <next> <up> <down> 
<down> <C-right> <C-right> <C-right> C-h v <return> 
C-x o <down> <down> <left> <left> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <up> 
<up> <up> <up> <up> <up> <up> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <next> <next> <prior> <prior> 
<next> <next> <next> <next> <prior> <next> <next> <next> 
<next> <next> <next> <next> C-x o <up> <up> C-h v m 
o d e - n a e <backspace> m e <return> <help-echo> 
<help-echo> <help-echo> <help-echo> <help-echo> <help-echo> 
M-x e m a c s - r e p o <tab> <M-backspace> <M-backspace> 
r e p o r t <tab> <return>

Recent messages:
Making completion list...
Quit
call-interactively: End of buffer
Mark set
Quit [2 times]
call-interactively: End of buffer
Mark saved where search started [3 times]
Mark set [3 times]
Mark saved where search started [3 times]
Type C-x 4 C-o RET to restore the other window, C-M-v to scroll help.

bug#1164: 23.0.60; Doc strings of mode-name, mode-line-format and format-mode-line

[Glenn Morris]

Eli Zaretskii wrote:

>     Usually a string.  See `mode-line-format' for other possible forms.
>     Use the function `format-mode-line' to get the value as a string.

Better?

      This is usually a string, but can take any of the forms described for
      `mode-line-format'.  Use `(format-mode-line mode-name)' to ensure a
      string value.

bug#1164: 23.0.60; Doc strings of mode-name, mode-line-format and format-mode-line

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Cc: 1164@emacsbugs.donarmstrong.com
> Date: Tue, 14 Oct 2008 15:42:09 -0400
> 
> Better?
> 
>       This is usually a string, but can take any of the forms described for
>       `mode-line-format'.  Use `(format-mode-line mode-name)' to ensure a
>       string value.

Yes, much better, if that's the whole truth and nothing but the truth.
Is it?

bug#1164: 23.0.60; Doc strings of mode-name, mode-line-format and format-mode-line

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Cc: 1164@emacsbugs.donarmstrong.com
> Date: Tue, 14 Oct 2008 15:42:09 -0400
> 
>       Use `(format-mode-line mode-name)' to ensure a string value.

Many users of format-mode-line do this:

     (format-mode-line mode-name nil nil buf)

where BUF is some buffer.  So evidently this isn't the whole story.

bug#1164: 23.0.60; Doc strings of mode-name, mode-line-format and format-mode-line

[Glenn Morris]

Pretty name of current buffer's major mode.
This is usually a string, but can take any of the forms described for
`mode-line-format'.  Pass to `format-mode-line' to get the value
as a string, as it would appear in the mode line.

?

bug#1164: 23.0.60; Doc strings of mode-name, mode-line-format and format-mode-line

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Cc: 1164@emacsbugs.donarmstrong.com
> Date: Tue, 14 Oct 2008 16:43:29 -0400
> 
> 
> Pretty name of current buffer's major mode.
> This is usually a string, but can take any of the forms described for
> `mode-line-format'.  Pass to `format-mode-line' to get the value
> as a string, as it would appear in the mode line.
> 
> ?

Thanks, I used a variant of the above.

Btw, is there any package that actually uses this new functionality?
I couldn't find one, but maybe my Grep command was too naive.

bug#1164: 23.0.60; Doc strings of mode-name, mode-line-format and format-mode-line

[Glenn Morris]

Eli Zaretskii wrote:

> Btw, is there any package that actually uses this new functionality?
> I couldn't find one, but maybe my Grep command was too naive.

textmodes/sgml-mode.el. It is hidden behind a define-derived-mode call:

(define-derived-mode sgml-mode text-mode '(sgml-xml-mode "XML" "SGML")
  "Major mode for editing SGML documents.