bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands

[Drew Adams <drew.adams@oracle.com>]

> > That's misleading enough to make me wonder whether,
> > in that case, it might be better to say nothing at
> > all about the call-from-Lisp case, forcing Lisp
> > users to consult the code.
> 
> How about leaving only cases like ARG -> '- undocumented?
> 
>   When called from Lisp, the mode command toggles the mode if the argument
>   is `toggle', disables the mode if the argument is a non-positive
>   integer, and enables the mode if the argument is a positive integer or
>   omitted or nil.

That's what we say now, and the reason I filed the bug.

> Good enough for daily business.  ...

Not good enough for me. ;-)

Consider a case where some command A invokes a minor-mode
command B, to turn B on or off for some purpose/extent.
Consider the case where A's prefix arg is passed to B, to
do that.

The programmer writing the Lisp code to define A should
know that s?he can just pass the raw prefix arg.  The
resulting code will be simpler, easier to read, etc.

I see no reason at all why we wouldn't provide an accurate
(complete) description of what ARG is for Lisp use.

What do we gain by not doing this right?