23.0.50; `mode-name' variable docs out of date WRT features

23.0.50; `mode-name' variable docs out of date WRT features

[sand]

Recent Emacs snapshots have extended the `mode-name' variable, so that
constructs such as

  '(sgml-xml-mode "XML" "SGML")

are allowed.  (See, for example, the definition of `sgml-mode'.)  The
documentation does not cover this list representation at all.  The
node "(elisp) Major Mode Conventions" states:

   * The major mode command should set the variable `mode-name' to the
     "pretty" name of the mode, as a string.  This string appears in the
     mode line.

and the node "(elisp) Mode Line Variables" states:

 -- Variable: mode-name
     This buffer-local variable holds the "pretty" name of the current
     buffer's major mode.  Each major mode should set this variable so
     that the mode name will appear in the mode line.

which implies (via "pretty") that this is a string, but doesn't
actually say what is allowed and what isn't.

The docs need to be updated to describe the new list-based
representation and how it is interpreted.

Derek

Re: 23.0.50; `mode-name' variable docs out of date WRT features

[Richard Stallman]

    Recent Emacs snapshots have extended the `mode-name' variable, so that
    constructs such as

      '(sgml-xml-mode "XML" "SGML")

We never discussed the question of using this variable that way.  I
think someone just noticed that this value works -- in the mode line,
at least -- and started using it.

But this value doesn't work everywhere.  There are files (bookmark.el
is one) that expect the value to be a string, as the manual says.

I think that the change in sgml-mode.el needs to be backed out.
Stefan, could you redo that differently, then ack?

Re: 23.0.50; `mode-name' variable docs out of date WRT features

[Stefan Monnier]

> Stefan, could you redo that differently, then ack?

No, it'd be a step backward.


        Stefan

Re: 23.0.50; `mode-name' variable docs out of date WRT features

[Miles Bader]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
> > But this value doesn't work everywhere.  There are files (bookmark.el
> > is one) that expect the value to be a string, as the manual says.
>
> > Stefan, could you redo that differently, then ack?
>
> No, it'd be a step backward.

Er, but the documentation _does_ say: "Pretty name of current buffer's
major mode (a string)." ... and presumably many coders have relied on
that description... what should they do?

-Miles

-- 
We are all lying in the gutter, but some of us are looking at the stars.
-Oscar Wilde

Re: 23.0.50; `mode-name' variable docs out of date WRT features

[Stefan Monnier]

>> > But this value doesn't work everywhere.  There are files (bookmark.el
>> > is one) that expect the value to be a string, as the manual says.
>> 
>> > Stefan, could you redo that differently, then ack?
>> 
>> No, it'd be a step backward.

> Er, but the documentation _does_ say: "Pretty name of current buffer's
> major mode (a string)." ... and presumably many coders have relied on
> that description... what should they do?

Adapt?
It's not like we never break backward compatibility in such minor ways,
is it?


        Stefan


PS: I would more cynically say that even if the doc had always said it
could contain any "mode-line-format" thingy, 99% of those same coders
would still not have written code to handle the non-string case.
My experience dealing with Elisp packages is that it's mostly written
by copying bad examples on the web rather than by reading the doc.

Re: 23.0.50; `mode-name' variable docs out of date WRT features

[Richard Stallman]

    > Stefan, could you redo that differently, then ack?

    No, it'd be a step backward.

If your aim was to change the meaning of the variable mode-name to
allow any mode-line spec, you implemented just a part of that change.
You didn't change the documentation, and you didn't fix the code that
expects the value to be a string.  The result is broken.  It needs to
be fixed somehow.  We need to either fully implement this change in
mode-name, or not implement it at all.

There are several places in Emacs that assume it is a string.  And the
change would be an incompatible change.  So unless there is some
strong reason to make the change, better we should undo the incomplete
change.

Can you offer a strong reason?

Re: 23.0.50; `mode-name' variable docs out of date WRT features

[Glenn Morris]

Richard Stallman wrote:

> Can you offer a strong reason?

Apparently not, but whatever.

Can you please just change the mode-name doc-string (eg "The value is
not guaranteed to be a string, use (blah) to get a string value"), add
a NEWS entry in the incompatible changes section, and delete this from
FOR-RELEASE.

Thanks.