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

From: Noam Postavsky <[email-masked]>
Date: Wed, 4 Jan 2017 14:27:38 -0500

On Wed, Jan 4, 2017 at 2:06 PM, Drew Adams <[email-masked]> 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.