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

From: [email-masked]
Date: Thu, 05 Jan 2017 22:58:09 -0500

Drew Adams <[email-masked]> 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 <[email-masked]> 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.

>From e2b2fa4cf18949f7ad4cbe17eb36b0abf7b0ad0c Mon Sep 17 00:00:00 2001
From: Noam Postavsky <[email-masked]>
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