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.