GNU bug report logs -
#25357
25.1; Doc for `cursor-sensor-mode' (and modes generally)
Previous Next
Reported by: Drew Adams <drew.adams <at> oracle.com>
Date: Wed, 4 Jan 2017 17:46:01 UTC
Severity: wishlist
Tags: fixed
Found in version 25.1
Fixed in version 25.2
Done: npostavs <at> users.sourceforge.net
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 25357 in the body.
You can then email your comments to 25357 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Wed, 04 Jan 2017 17:46:01 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
Drew Adams <drew.adams <at> oracle.com>:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org.
(Wed, 04 Jan 2017 17:46:01 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
The doc string does not say anything about the argument, ARG. It should
tell you what it means/does when the function is called from Lisp - IOW, how to use it.
More generally, I do not see, in either the Emacs or the Elisp manuals,
anywhere where we explain the argument to a major mode, telling you how
to turn the mode on/off from Lisp. Maybe I didn't search well enough?
In GNU Emacs 25.1.1 (x86_64-w64-mingw32)
of 2016-09-17 built on LAPHROAIG
Windowing system distributor 'Microsoft Corp.', version 6.1.7601
Configured using:
'configure --without-dbus --without-compress-install CFLAGS=-static'
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Wed, 04 Jan 2017 18:00:02 GMT)
Full text and
rfc822 format available.
Message #8 received at 25357 <at> debbugs.gnu.org (full text, mbox):
> Date: Wed, 4 Jan 2017 09:44:45 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
>
> More generally, I do not see, in either the Emacs or the Elisp manuals,
> anywhere where we explain the argument to a major mode, telling you how
> to turn the mode on/off from Lisp.
It's mentioned in "Minor Modes" in the user manual.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Wed, 04 Jan 2017 18:06:02 GMT)
Full text and
rfc822 format available.
Message #11 received at 25357 <at> debbugs.gnu.org (full text, mbox):
> Date: Wed, 04 Jan 2017 19:59:07 +0200
> From: Eli Zaretskii <eliz <at> gnu.org>
> Cc: 25357 <at> debbugs.gnu.org
>
> > Date: Wed, 4 Jan 2017 09:44:45 -0800 (PST)
> > From: Drew Adams <drew.adams <at> oracle.com>
> >
> > More generally, I do not see, in either the Emacs or the Elisp manuals,
> > anywhere where we explain the argument to a major mode, telling you how
> > to turn the mode on/off from Lisp.
>
> It's mentioned in "Minor Modes" in the user manual.
Also in "Minor Mode Conventions" in the ELisp manual. The
corresponding "Major Mode Conventions" node could say that as well, of
course.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Wed, 04 Jan 2017 18:08:01 GMT)
Full text and
rfc822 format available.
Message #14 received at 25357 <at> debbugs.gnu.org (full text, mbox):
> > More generally, I do not see, in either the Emacs or the Elisp manuals,
> > anywhere where we explain the argument to a major mode, telling you how
> > to turn the mode on/off from Lisp.
>
> It's mentioned in "Minor Modes" in the user manual.
But it's a major mode... I tried `i' for major mode etc.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Wed, 04 Jan 2017 18:09:02 GMT)
Full text and
rfc822 format available.
Message #17 received at 25357 <at> debbugs.gnu.org (full text, mbox):
> > > More generally, I do not see, in either the Emacs or the Elisp manuals,
> > > anywhere where we explain the argument to a major mode, telling you how
> > > to turn the mode on/off from Lisp.
> >
> > It's mentioned in "Minor Modes" in the user manual.
>
> Also in "Minor Mode Conventions" in the ELisp manual. The
> corresponding "Major Mode Conventions" node could say that as well, of
> course.
It's not a convention in the sense that the other content there
describes conventions. Those are conventions for writing, not
using, a major mode.
It should be explained in both manuals, I think, how to turn on/off
a major mode using Lisp.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Wed, 04 Jan 2017 18:57:01 GMT)
Full text and
rfc822 format available.
Message #20 received at 25357 <at> debbugs.gnu.org (full text, mbox):
On Wed, Jan 4, 2017 at 1:07 PM, Drew Adams <drew.adams <at> oracle.com> wrote:
>> > More generally, I do not see, in either the Emacs or the Elisp manuals,
>> > anywhere where we explain the argument to a major mode, telling you how
>> > to turn the mode on/off from Lisp.
>>
>> It's mentioned in "Minor Modes" in the user manual.
>
> But it's a major mode... I tried `i' for major mode etc.
>
Why do you think it's a major mode? cursor-sensor.el has:
(define-minor-mode cursor-sensor-mode ...
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Wed, 04 Jan 2017 19:07:01 GMT)
Full text and
rfc822 format available.
Message #23 received at 25357 <at> debbugs.gnu.org (full text, mbox):
> >> > More generally, I do not see, in either the Emacs or the Elisp manuals,
> >> > anywhere where we explain the argument to a major mode, telling you how
> >> > to turn the mode on/off from Lisp.
> >>
> >> It's mentioned in "Minor Modes" in the user manual.
> >
> > But it's a major mode... I tried `i' for major mode etc.
>
> Why do you think it's a major mode? cursor-sensor.el has:
> (define-minor-mode cursor-sensor-mode ...
In that case, there are two bugs:
1. The doc string should say that it is a minor mode, and say how
to change the value (on/off). I think this has been addressed by
bug #20462.
2. (This bug) The manuals should document how to turn on/off a major mode
using Lisp. Please retitle this bug appropriately.
Sorry if this mode is not an example of a major mode.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Wed, 04 Jan 2017 19:28:01 GMT)
Full text and
rfc822 format available.
Message #26 received at 25357 <at> debbugs.gnu.org (full text, mbox):
On Wed, Jan 4, 2017 at 2:06 PM, Drew Adams <drew.adams <at> oracle.com> wrote:
>
> 1. The doc string should say that it is a minor mode, and say how
> to change the value (on/off). I think this has been addressed by
> bug #20462.
I agree.
>
> 2. (This bug) The manuals should document how to turn on/off a major mode
> using Lisp. Please retitle this bug appropriately.
`(emacs) Major Modes' says
You can explicitly select a new major mode by using an M-x
command. Take the name of the mode and add -mode to get the name of
the command to select that mode (e.g., M-x lisp-mode enters Lisp
mode).
Do you really think it's necessary to explain here how evaluating
(foo-mode) is equivalent to running M-x foo-mode?
`(elisp) Major Modes' says
Major modes specialize Emacs for editing particular kinds of text.
Each buffer has one major mode at a time. Every major mode is
associated with a major mode command, whose name should end in
‘-mode’. This command takes care of switching to that mode in the
current buffer
Do you really think it's necessary to explain how to call a command
from elisp here? The first hit in the index for `command' gives
command
An object which can be invoked via the command-execute primitive,
usually due to the user typing in a key sequence bound to that
command. See Interactive Call. A command is usually a function; if the
function is written in Lisp, it is made into a command by an
interactive form in the function definition (see Defining Commands).
Commands that are functions can also be called from Lisp expressions,
just like other functions.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Wed, 04 Jan 2017 21:03:02 GMT)
Full text and
rfc822 format available.
Message #29 received at 25357 <at> debbugs.gnu.org (full text, mbox):
> > 2. (This bug) The manuals should document how to turn on/off a major mode
> > using Lisp. Please retitle this bug appropriately.
>
> `(emacs) Major Modes' says
>
> You can explicitly select a new major mode by using an M-x
> command. Take the name of the mode and add -mode to get the name of
> the command to select that mode (e.g., M-x lisp-mode enters Lisp
> mode).
>
> Do you really think it's necessary to explain here how evaluating
> (foo-mode) is equivalent to running M-x foo-mode?
Yes, absolutely I do.
And how to turn it OFF using Lisp. Yes, the answer is to just turn
on some other major mode. But how are users to know that if we don't
tell them?
http://emacs.stackexchange.com/q/29813/105
> `(elisp) Major Modes' says
>
> Major modes specialize Emacs for editing particular kinds of text.
> Each buffer has one major mode at a time. Every major mode is
> associated with a major mode command, whose name should end in
> ‘-mode’. This command takes care of switching to that mode in the
> current buffer
I even think it would help to emphasize that "one" - not zero.
IOW, you cannot turn off a major mode without turning on another one.
> Do you really think it's necessary to explain how to call a command
> from elisp here? The first hit in the index for `command' gives
>
> command
>
> An object which can be invoked via the command-execute primitive,
> usually due to the user typing in a key sequence bound to that
> command. See Interactive Call. A command is usually a function; if the
> function is written in Lisp, it is made into a command by an
> interactive form in the function definition (see Defining Commands).
> Commands that are functions can also be called from Lisp expressions,
> just like other functions.
Yes, I do think it's necessary - see above.
It is sufficient to explain this once (in each manual, I think - or
at least cross-reference the Elisp explanation from the Emacs manual).
I don't think it is ever really explained anywhere. And the way minor
and major modes work in this regard is quite different. There is
always some major mode that is "on" - only one at a time. There can
be many minor modes that are on at the same time.
It will already help a lot if the doc strings of modes make clear
whether a mode is a major or a minor mode.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Thu, 05 Jan 2017 03:45:01 GMT)
Full text and
rfc822 format available.
Message #32 received at 25357 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
Drew Adams <drew.adams <at> oracle.com> writes:
>
> I even think it would help to emphasize that "one" - not zero.
> IOW, you cannot turn off a major mode without turning on another one.
Sure, here's a patch to the manuals to clarify that. I don't think
explaining about the relationship between M-x and Lisp functions again
is needed though.
[0001-Clarify-major-mode-switching.patch (text/x-diff, inline)]
From ebea8363cc02fded1a98d0fffcda460faee9e72d Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs <at> gmail.com>
Date: Wed, 4 Jan 2017 20:35:13 -0500
Subject: [PATCH] Clarify major mode switching
* doc/emacs/modes.texi (Major Modes):
* doc/lispref/modes.texi (Modes, Major Modes): Explictly say that each
buffer has exactly one major mode and can't be "turned off", only
switched away from (Bug#25357).
---
doc/emacs/modes.texi | 5 ++++-
doc/lispref/modes.texi | 20 +++++++++++---------
2 files changed, 15 insertions(+), 10 deletions(-)
diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi
index 0acb82d..6b8bd92 100644
--- a/doc/emacs/modes.texi
+++ b/doc/emacs/modes.texi
@@ -66,7 +66,10 @@ Major Modes
first visit a file or create a buffer (@pxref{Choosing Modes}). You
can explicitly select a new major mode by using an @kbd{M-x} command.
Take the name of the mode and add @code{-mode} to get the name of the
-command to select that mode (e.g., @kbd{M-x lisp-mode} enters Lisp mode).
+command to select that mode (e.g., @kbd{M-x lisp-mode} enters Lisp
+mode). Since every buffer has exactly one major mode, there is no way
+to ``turn off'' a major mode, instead you must switch to a different
+one.
@vindex major-mode
The value of the buffer-local variable @code{major-mode} is a symbol
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index b24ab36..3704e03 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -7,11 +7,11 @@ Modes
@chapter Major and Minor Modes
@cindex mode
- A @dfn{mode} is a set of definitions that customize Emacs and can be
-turned on and off while you edit. There are two varieties of modes:
-@dfn{major modes}, which are mutually exclusive and used for editing
-particular kinds of text, and @dfn{minor modes}, which provide features
-that users can enable individually.
+ A @dfn{mode} is a set of definitions that customize Emacs' behavior
+in useful ways. There are two varieties of modes: @dfn{minor modes},
+which provide features that users can turn on and off while editing.
+And @dfn{major modes}, which are used for editing a particular kind of
+text. Each buffer has exactly one @dfn{major mode}.
This chapter describes how to write both major and minor modes, how to
indicate them in the mode line, and how they run hooks supplied by the
@@ -197,11 +197,13 @@ Major Modes
@cindex major mode command
Major modes specialize Emacs for editing particular kinds of text.
-Each buffer has one major mode at a time. Every major mode is
+Each buffer has exactly one major mode at a time. Every major mode is
associated with a @dfn{major mode command}, whose name should end in
-@samp{-mode}. This command takes care of switching to that mode in the
-current buffer, by setting various buffer-local variables such as a
-local keymap. @xref{Major Mode Conventions}.
+@samp{-mode}. This command takes care of switching to that mode in
+the current buffer, by setting various buffer-local variables such as
+a local keymap. @xref{Major Mode Conventions}. Note that unlike
+minor modes, the only way to ``turn off'' a major mode is to switch to
+a different one.
The least specialized major mode is called @dfn{Fundamental mode},
which has no mode-specific definitions or variable settings.
--
2.9.3
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Thu, 05 Jan 2017 04:30:03 GMT)
Full text and
rfc822 format available.
Message #35 received at 25357 <at> debbugs.gnu.org (full text, mbox):
> > I even think it would help to emphasize that "one" - not zero.
> > IOW, you cannot turn off a major mode without turning on another one.
>
> Sure, here's a patch to the manuals to clarify that.
Thanks. Some minor comments. If they help, fine; if not, ignore.
One not-so-minor comment, flagged by ** (in two places).
---
The comma here should be a semicolon (or use two sentences);
otherwise it is a comma splice:
``turn off'' a major mode, instead you must switch
;
> I don't think explaining about the relationship between M-x and
> Lisp functions again is needed though.
** How so, "again"? Here we are telling someone how to turn it
on interactively. I think we should also tell them how to do it
using Lisp.
Or at least cross-reference some Elisp manual reference doc that
tells you that you "turn on" a major mode by calling the function
with no arguments. Examples where you add a major-mode function
as a normal hook imply that (no args), but it would be good to
spell it out once.
Here, I would drop the apostrophe - not needed:
definitions that customize Emacs' behavior
Here, I would say for a particular kind of editing or
interaction:
used for editing a particular kind of text
(Not all modes are for editing, in the usually understood sense.)
Here, I would append "at a time".
Each buffer has exactly one @dfn{major mode}.
Otherwise it sounds like the mode-buffer association is fixed.
For this:
Major modes specialize Emacs for editing particular kinds of text.
see above. We should not give the impression that a major mode
is only for editing. `Info-mode' is not an editing mode (in the
usual sense), for example. (Yes, I know that this particular text
was already there.)
This is OK, and I see that you put it in quotes (which is good):
the only way to ``turn off'' a major mode is to switch to
a different one.
But it is different from what you said in the Emacs manual, where
(I thought that) you specifically avoided any mention of turning
a major mode on or off, and instead spoke about putting the buffer
into the given mode.
IOW, either we say that you CANNOT turn off (with quotes) a major
mode, and INSTEAD of turning it off you switch the buffer to a
different mode, or we say that THE WAY TO turn it off (with quotes)
is to switch to a different mode. Those are different statements.
Either is OK by me, but it might be better not to use both.
** Again, though, I think we should say explicitly somewhere
(in the Elisp manual, as reference, and either linked to that
or repeated in the Emacs manual) that you put a buffer into a
major mode by invoking the mode function with no args.
I repeat: feel free to ignore any of the above, and please make
the changes you feel are best at this point. Thx.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Thu, 05 Jan 2017 15:29:02 GMT)
Full text and
rfc822 format available.
Message #38 received at 25357 <at> debbugs.gnu.org (full text, mbox):
> From: npostavs <at> users.sourceforge.net
> Cc: 25357 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
> Date: Wed, 04 Jan 2017 22:45:17 -0500
>
> > I even think it would help to emphasize that "one" - not zero.
> > IOW, you cannot turn off a major mode without turning on another one.
>
> Sure, here's a patch to the manuals to clarify that.
Thanks.
> + A @dfn{mode} is a set of definitions that customize Emacs' behavior
> +in useful ways. There are two varieties of modes: @dfn{minor modes},
> +which provide features that users can turn on and off while editing.
> +And @dfn{major modes}, which are used for editing a particular kind of
> +text.
I'd suggest not to start a sentence with "And". Instead, something
like this should be better:
@dfn{major modes}, which ...; and @dfn {minor modes}, which ...
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Fri, 06 Jan 2017 03:58:01 GMT)
Full text and
rfc822 format available.
Message #41 received at 25357 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
Drew Adams <drew.adams <at> oracle.com> writes:
>
> Thanks. Some minor comments. If they help, fine; if not, ignore.
> One not-so-minor comment, flagged by ** (in two places).
Thanks, that was helpful.
>
> ** How so, "again"? Here we are telling someone how to turn it
> on interactively. I think we should also tell them how to do it
> using Lisp.
This is a subjective thing of course. I guess it seems obvious to me
that a command can be called as a function, and it's explained in
`(elisp) What Is a Function'. Adding cross references to that in every
place we talk about invoking some command is just clutter.
Eli Zaretskii <eliz <at> gnu.org> writes:
> I'd suggest not to start a sentence with "And". Instead, something
> like this should be better:
>
> @dfn{major modes}, which ...; and @dfn {minor modes}, which ...
Fixed this too.
[v2-0001-Clarify-major-mode-switching.patch (text/plain, attachment)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Fri, 06 Jan 2017 05:51:02 GMT)
Full text and
rfc822 format available.
Message #44 received at 25357 <at> debbugs.gnu.org (full text, mbox):
> > ** How so, "again"? Here we are telling someone how to turn it
> > on interactively. I think we should also tell them how to do it
> > using Lisp.
>
> This is a subjective thing of course. I guess it seems obvious to me
> that a command can be called as a function, and it's explained in
> `(elisp) What Is a Function'. Adding cross references to that in every
> place we talk about invoking some command is just clutter.
Yes, of course. But I don't think it is obvious to some
who read the _Emacs_ manual how they might turn on a major
mode using Lisp.
I've seen enough people confused about this, especially
given the very different way they turn on a minor mode
(which is better documented, if still inadequate - see
the bug about minor-mode doc strings).
You may say that such users do not _need_ to invoke a
major mode function from Lisp. And if they do, and
they do it the usual way (for a file), they do it using
`auto-mode-alist'.
Still, some try to do it using `(the-mode-name ...)',
passing various things as argument. They guess...
I don't see anywhere in the Elisp manual a simple
statement that they just need to use `(the-mode-name)'.
AND that it is generally a good idea to use
`auto-mode-alist' when the buffer is a file buffer.
I don't feel strongly about any of this, but I do think
it could help some users to lay it out explicitly.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Fri, 06 Jan 2017 07:58:02 GMT)
Full text and
rfc822 format available.
Message #47 received at 25357 <at> debbugs.gnu.org (full text, mbox):
> Date: Thu, 5 Jan 2017 21:50:29 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 25357 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
>
> > This is a subjective thing of course. I guess it seems obvious to me
> > that a command can be called as a function, and it's explained in
> > `(elisp) What Is a Function'. Adding cross references to that in every
> > place we talk about invoking some command is just clutter.
>
> Yes, of course. But I don't think it is obvious to some
> who read the _Emacs_ manual how they might turn on a major
> mode using Lisp.
People who write Lisp should read the ELisp manual, and expect issues
related to Lisp to be covered there. The user manual is not the right
place for that.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Fri, 06 Jan 2017 14:51:02 GMT)
Full text and
rfc822 format available.
Message #50 received at 25357 <at> debbugs.gnu.org (full text, mbox):
> > Yes, of course. But I don't think it is obvious to some
> > who read the _Emacs_ manual how they might turn on a major
> > mode using Lisp.
>
> People who write Lisp should read the ELisp manual, and expect issues
> related to Lisp to be covered there. The user manual is not the right
> place for that.
Did you read the part about this also not being explicitly
spelled out in the Elisp manual? And about it being OK to
just link to that (missing) part from the Emacs manual.
It's clear to me that at least some users have been confused
about how to "turn on" a major mode using Lisp. Sure, we
can cop out and say they haven't studied the Elisp manual
well enough... I think we can help them more. And I think
that, so far, the doc (including doc strings) is not as helpful
as it could be wrt using minor and major modes from Lisp.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#25357; Package
emacs.
(Sun, 08 Jan 2017 17:15:02 GMT)
Full text and
rfc822 format available.
Message #53 received at 25357 <at> debbugs.gnu.org (full text, mbox):
tags 25357 fixed
close 25357 25.2
quit
Patch pushed to emacs-25.
1: 2017-01-07 09:30:00 -0500 a2a20739331a216826b9c76d49b0aa2abd68deee
Clarify major mode switching
Added tag(s) fixed.
Request was from
npostavs <at> users.sourceforge.net
to
control <at> debbugs.gnu.org.
(Sun, 08 Jan 2017 17:15:04 GMT)
Full text and
rfc822 format available.
bug marked as fixed in version 25.2, send any further explanations to
25357 <at> debbugs.gnu.org and Drew Adams <drew.adams <at> oracle.com>
Request was from
npostavs <at> users.sourceforge.net
to
control <at> debbugs.gnu.org.
(Sun, 08 Jan 2017 17:15:05 GMT)
Full text and
rfc822 format available.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org.
(Mon, 06 Feb 2017 12:24:03 GMT)
Full text and
rfc822 format available.
This bug report was last modified 8 years and 137 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.