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

[npostavs]

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.

>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