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.