bug#24706: 26.0.50; Minor mode functions should do strict argument type checking

[Eli Zaretskii]

> From: Philipp Stephani <p.stephani2@gmail.com>
> Date: Sun, 23 Apr 2017 17:51:32 +0000
> Cc: drew.adams@oracle.com, 24706@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> schrieb am So., 16. Okt. 2016 um 20:51 Uhr:
> 
>  > From: Philipp Stephani <p.stephani2@gmail.com>
>  > Date: Sun, 16 Oct 2016 18:25:08 +0000
>  >
>  > Attached a patch that uses the wording from `define-minor-mode'.
> 
>  The patch for the ELisp manual simply rearranges the same words, so
>  it's not clear to me why we would prefer it to what's already there.
> 
> I don't think there's any repetition or rearranging here.

Here's the ELisp manual part of your proposed change:

   If the mode command is called from Lisp (i.e., non-interactively), it
  -should enable the mode if the argument is omitted or @code{nil}; it
  -should toggle the mode if the argument is the symbol @code{toggle};
  -otherwise it should treat the argument in the same way as for an
  -interactive call with a numeric prefix argument, as described above.
  +should toggle the mode if the argument is the symbol @code{toggle}; it
  +should disable the mode if the argument is a non-positive integer;
  +otherwise, e.g., if the argument is omitted or nil or a positive
  +integer, it should enable the mode.

Don't you agree that it does little apart of re-shuffling the same
words?

> The key difference is that when called from Lisp with an
> argument that is neither nil nor an integer, the mode is also enabled.

Why would we want to require that?  This subsection describes the
conventions, it doesn't describe the effect of certain popular
implementation of those conventions, because we don't really want to
_require_ modes to behave in any way beyond the described behavior.

> "With a prefix argument ARG, enable the mode if ARG is positive, and disable 
> it if ARG is negative or zero.

This is almost exactly the same as the current:

  With a prefix argument ARG, enable %s if ARG is
  positive, and disable it otherwise.

> Additionally, when called from Lisp, toggle the mode if ARG is the symbol 
> `toggle' and interpret ARG as
> defined by `prefix-numeric-value' otherwise."

And this is exactly what I suggested back then:

>  As for the doc string, please avoid repetition, it's confusing. I
>  suggested to describe the additional features when the mode is called
>  from Lisp by using the word "also".

The wording I had in mind was similar to yours:

  When called from Lisp, also enable the mode if ARG is omitted or
  nil, and toggle it if ARG is `toggle'.