bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[Drew Adams]

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'

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[Eli Zaretskii]

> Date: Wed, 4 Jan 2017 09:44:45 -0800 (PST)
> From: Drew Adams <drew.adams@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.

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[Eli Zaretskii]

> Date: Wed, 04 Jan 2017 19:59:07 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: 25357@debbugs.gnu.org
> 
> > Date: Wed, 4 Jan 2017 09:44:45 -0800 (PST)
> > From: Drew Adams <drew.adams@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.

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[Drew Adams]

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

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[Drew Adams]

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

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[Noam Postavsky]

On Wed, Jan 4, 2017 at 1:07 PM, Drew Adams <drew.adams@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 ...

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[Drew Adams]

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

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[Noam Postavsky]

On Wed, Jan 4, 2017 at 2:06 PM, Drew Adams <drew.adams@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.

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[Drew Adams]

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

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[npostavs]

[-- Attachment #1: Type: text/plain, Size: 341 bytes --]

Drew Adams <drew.adams@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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: patch --]
[-- Type: text/x-diff, Size: 3315 bytes --]

From ebea8363cc02fded1a98d0fffcda460faee9e72d Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@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

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[Drew Adams]

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

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[Eli Zaretskii]

> From: npostavs@users.sourceforge.net
> Cc: 25357@debbugs.gnu.org,  Eli Zaretskii <eliz@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 ...

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[npostavs]

[-- Attachment #1: Type: text/plain, Size: 845 bytes --]

Drew Adams <drew.adams@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@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.


[-- Attachment #2: patch --]
[-- Type: text/plain, Size: 3562 bytes --]

From e2b2fa4cf18949f7ad4cbe17eb36b0abf7b0ad0c Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Wed, 4 Jan 2017 20:35:13 -0500
Subject: [PATCH v2] 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 | 26 +++++++++++++++-----------
 2 files changed, 19 insertions(+), 12 deletions(-)

diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi
index 0acb82d..be89340 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..0015a9f 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -7,11 +7,12 @@ 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 or interacting with
+a particular kind of text.  Each buffer has exactly one @dfn{major
+mode} at a time.
 
   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
@@ -196,12 +197,15 @@ Major Modes
 @cindex major mode
 
 @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
-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}.
+  Major modes specialize Emacs for editing or interacting with
+particular kinds of text.  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}.  Note that unlike minor modes there is no way to ``turn
+off'' a major mode, instead the buffer must be switched 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

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[Drew Adams]

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

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[Eli Zaretskii]

> Date: Thu, 5 Jan 2017 21:50:29 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 25357@debbugs.gnu.org, Eli Zaretskii <eliz@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.

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[Drew Adams]

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

bug#25357: 25.1; Doc for `cursor-sensor-mode' (and modes generally)

[npostavs]

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