GNU bug report logs - #50801
28.0.50; Emacs manual about file variables doesn't mention that major modes shouldn't end in "-mode"

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 50801 in the body.
You can then email your comments to 50801 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Daniel Martín <mardani29 <at> yahoo.es>
To: bug-gnu-emacs <at> gnu.org
Subject: 28.0.50; Emacs manual about file variables doesn't mention that
 major modes shouldn't end in "-mode"
Date: Sat, 25 Sep 2021 15:39:45 +0200

I'm reviewing the manuals for the upcoming Emacs 28 and I have a couple
of minor suggestions for node "49.2.4.1 Specifying File Variables":

The node doesn't explictly mention the crucial information that in
'mode: MODENAME' 'MODENAME' must not end in "-mode".  It's true that
there's an example down there that says "mode: Lisp", so users may infer
that you don't need to spell the major mode with "-mode", but I thought
it may be better to be explicit about in the manual.

Another suggestion I have is that the manual doesn't mention that
something like "-*- C++ -*-" (that is, omitting the "mode" keyword) is
also supported.  Many free software projects have traditionally been
using "-* C++ -*" in their C++ header files to make Emacs distinguish
them from plain C files.  See also src/epaths.in in the Emacs
repository, among others.  I see this used by Jim Blandy since 1992 at
least, but I don't really know if a) it's really a stable way to declare
a file-local mode, and we may lack the historical info to answer that,
and b) it's worth mentioning it in the manual.

Thanks.

Message #8 received at 50801 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Daniel Martín <mardani29 <at> yahoo.es>
Cc: 50801 <at> debbugs.gnu.org
Subject: Re: bug#50801: 28.0.50; Emacs manual about file variables doesn't
 mention that major modes shouldn't end in "-mode"
Date: Sat, 25 Sep 2021 10:46:12 -0700

Daniel Martín <mardani29 <at> yahoo.es> writes:

> I'm reviewing the manuals for the upcoming Emacs 28 and I have a couple
> of minor suggestions for node "49.2.4.1 Specifying File Variables":

That is extremely useful, thank you very much for working on this.

(BTW, you can press `w' in info to get a reference like "(emacs)
Specifying File Variables".  This is not super important, but a handy
feature to know about, as you can then `M-: (info "...")' and get to
that section quickly.)

> The node doesn't explictly mention the crucial information that in
> 'mode: MODENAME' 'MODENAME' must not end in "-mode".  It's true that
> there's an example down there that says "mode: Lisp", so users may infer
> that you don't need to spell the major mode with "-mode", but I thought
> it may be better to be explicit about in the manual.

Fully agreed.  Perhaps something like this?

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index d12033f841..d5f18fff35 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1084,8 +1084,9 @@ Specifying File Variables
 @noindent
 You can specify any number of variable/value pairs in this way, each
 pair with a colon and semicolon.  The special variable/value pair
-@code{mode: @var{modename};}, if present, specifies a major mode.  The
-@var{value}s are used literally, and not evaluated.
+@code{mode: @var{modename};}, if present, specifies a major mode
+(excluding the ``-mode'' part).  The @var{value}s are used literally,
+and not evaluated.

 @findex add-file-local-variable-prop-line
 @findex delete-file-local-variable-prop-line

> Another suggestion I have is that the manual doesn't mention that
> something like "-*- C++ -*-" (that is, omitting the "mode" keyword) is
> also supported.  Many free software projects have traditionally been
> using "-* C++ -*" in their C++ header files to make Emacs distinguish
> them from plain C files.  See also src/epaths.in in the Emacs
> repository, among others.  I see this used by Jim Blandy since 1992 at
> least, but I don't really know if a) it's really a stable way to declare
> a file-local mode, and we may lack the historical info to answer that,
> and b) it's worth mentioning it in the manual.

I can't remember the details, but I believe that this form is considered
obsolete and/or problematic.  So I think it's fine to not document it.

Message #11 received at 50801 <at> debbugs.gnu.org (full text, mbox):

From: Daniel Martín <mardani29 <at> yahoo.es>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 50801 <at> debbugs.gnu.org
Subject: Re: bug#50801: 28.0.50; Emacs manual about file variables doesn't
 mention that major modes shouldn't end in "-mode"
Date: Sat, 25 Sep 2021 20:22:28 +0200

Stefan Kangas <stefan <at> marxist.se> writes:

>
>> I'm reviewing the manuals for the upcoming Emacs 28 and I have a couple
>> of minor suggestions for node "49.2.4.1 Specifying File Variables":
>
> That is extremely useful, thank you very much for working on this.
>
> (BTW, you can press `w' in info to get a reference like "(emacs)
> Specifying File Variables".  This is not super important, but a handy
> feature to know about, as you can then `M-: (info "...")' and get to
> that section quickly.)

Yep, I forgot to add a direct link to the Info node, sorry.  BTW you can
'C-u w' to get the link inside a function call to `info` directly.

>
>> The node doesn't explictly mention the crucial information that in
>> 'mode: MODENAME' 'MODENAME' must not end in "-mode".  It's true that
>> there's an example down there that says "mode: Lisp", so users may infer
>> that you don't need to spell the major mode with "-mode", but I thought
>> it may be better to be explicit about in the manual.
>
> Fully agreed.  Perhaps something like this?
>
> diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
> index d12033f841..d5f18fff35 100644
> --- a/doc/emacs/custom.texi
> +++ b/doc/emacs/custom.texi
> @@ -1084,8 +1084,9 @@ Specifying File Variables
>  @noindent
>  You can specify any number of variable/value pairs in this way, each
>  pair with a colon and semicolon.  The special variable/value pair
> -@code{mode: @var{modename};}, if present, specifies a major mode.  The
> -@var{value}s are used literally, and not evaluated.
> +@code{mode: @var{modename};}, if present, specifies a major mode
> +(excluding the ``-mode'' part).  The @var{value}s are used literally,
> +and not evaluated.

I'm not a native speaker but it reads well to me, thank you.

>
>  @findex add-file-local-variable-prop-line
>  @findex delete-file-local-variable-prop-line
>
>> Another suggestion I have is that the manual doesn't mention that
>> something like "-*- C++ -*-" (that is, omitting the "mode" keyword) is
>> also supported.  Many free software projects have traditionally been
>> using "-* C++ -*" in their C++ header files to make Emacs distinguish
>> them from plain C files.  See also src/epaths.in in the Emacs
>> repository, among others.  I see this used by Jim Blandy since 1992 at
>> least, but I don't really know if a) it's really a stable way to declare
>> a file-local mode, and we may lack the historical info to answer that,
>> and b) it's worth mentioning it in the manual.
>
> I can't remember the details, but I believe that this form is considered
> obsolete and/or problematic.  So I think it's fine to not document it.

Makes sense.

Message #14 received at 50801 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 50801 <at> debbugs.gnu.org, Daniel Martín <mardani29 <at> yahoo.es>
Subject: Re: bug#50801: 28.0.50; Emacs manual about file variables doesn't
 mention that major modes shouldn't end in "-mode"
Date: Sun, 26 Sep 2021 08:59:28 +0200

Stefan Kangas <stefan <at> marxist.se> writes:

> -@code{mode: @var{modename};}, if present, specifies a major mode.  The
> -@var{value}s are used literally, and not evaluated.
> +@code{mode: @var{modename};}, if present, specifies a major mode
> +(excluding the ``-mode'' part).  The @var{value}s are used literally,
> +and not evaluated.

Makes sense to me.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #17 received at 50801 <at> debbugs.gnu.org (full text, mbox):

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 50801 <at> debbugs.gnu.org, Daniel Martín <mardani29 <at> yahoo.es>
Subject: Re: bug#50801: 28.0.50; Emacs manual about file variables doesn't
 mention that major modes shouldn't end in "-mode"
Date: Sun, 26 Sep 2021 09:09:17 +0200

On Sep 25 2021, Stefan Kangas wrote:

> diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
> index d12033f841..d5f18fff35 100644
> --- a/doc/emacs/custom.texi
> +++ b/doc/emacs/custom.texi
> @@ -1084,8 +1084,9 @@ Specifying File Variables
>  @noindent
>  You can specify any number of variable/value pairs in this way, each
>  pair with a colon and semicolon.  The special variable/value pair
> -@code{mode: @var{modename};}, if present, specifies a major mode.  The
> -@var{value}s are used literally, and not evaluated.
> +@code{mode: @var{modename};}, if present, specifies a major mode
> +(excluding the ``-mode'' part).  The @var{value}s are used literally,

without the ``-mode'' suffix

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Message #20 received at 50801 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 50801 <at> debbugs.gnu.org, Daniel Martín <mardani29 <at> yahoo.es>
Subject: Re: bug#50801: 28.0.50; Emacs manual about file variables doesn't
 mention that major modes shouldn't end in "-mode"
Date: Sun, 26 Sep 2021 03:05:24 -0700

tags 50801 fixed
close 50801 28.1
thanks

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Stefan Kangas <stefan <at> marxist.se> writes:
>
>> -@code{mode: @var{modename};}, if present, specifies a major mode.  The
>> -@var{value}s are used literally, and not evaluated.
>> +@code{mode: @var{modename};}, if present, specifies a major mode
>> +(excluding the ``-mode'' part).  The @var{value}s are used literally,
>> +and not evaluated.
>
> Makes sense to me.

Thanks, I have now made this change on master (commit 68994995db) with
the improvement suggested by Andreas.

I'm therefore closing this bug report.

Message #27 received at 50801 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: 50801 <at> debbugs.gnu.org, stefan <at> marxist.se, mardani29 <at> yahoo.es
Subject: Re: bug#50801: 28.0.50;
 Emacs manual about file variables doesn't mention that major modes
 shouldn't end in "-mode"
Date: Mon, 27 Sep 2021 18:34:49 -0400

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > +@code{mode: @var{modename};}, if present, specifies a major mode
  > > +(excluding the ``-mode'' part).  The @var{value}s are used literally,

  > without the ``-mode'' suffix

Indeed.  `-mode' is NOT part of the mode's name.  The name of Mail
mode, which I'm using now, is "Mail", not "Mail mode".

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.