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

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

> > > 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.
> 
> No, it's not, it doesn't contradict the implementation.  Did you read
> carefully?

I think I did.  We don't use exactly the same words, but
I think we do say just that.

  When called from Lisp, the mode command toggles the mode if the
  argument is `toggle', 

Verbatim the same.

  disables the mode if the argument is a non-positive integer,

Verbatim the same.

  and enables the mode otherwise (including
  if the argument is omitted or nil or a positive integer).

OK, your text doesn't say "otherwise".  Your text is less
exact, since the "otherwise" is correct - omitted/nil and
positive integer constitute a subset of what's true.

Is that really your suggestion, to not document that
something other than omitted, nil and a positive integer
enables the mode?  To me, that would be a step backward,
not forward.  That doesn't correspond to what the code does.

> > 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.
> 
> We don't know if the original author intended the semantics of the
> documentation or of the implementation.  If we are sure the current
> implementation is what was intended I would be ok with documenting it,
> but it's really far from important IMHO.

Until the code is changed, e.g. because someone thinks
the behavior is wrong, the doc should reflect it.  I,
for one, think the behavior is OK as is.  The use case
I just gave (cited above) is one argument for it.

Many commands have the `interactive' form massage the
prefix arg, to present something a bit different to
the body.  E.g., a change from raw to numeric prefix
value is done in the `interactive' form, for whatever
reason.

This command doesn't work that way.  Instead, what is
passed to Lisp is the raw prefix arg, and it is the
body (which also corresponds to a non-interactive call)
that converts that to a numeric value.

Someone (and `d-m-mode' has been worked over more than
once wrt its interactive-vs-Lisp behavior, I believe)
presumably deliberately decided that this command
should act differently.

Many commands (most, I think) make it so that the body
gets just what it needs, and any compensation for
interactivity is taken care of only in the `interactive'
spec.  Someone presumably thought this command should
be an exception in that regard.

Until someone decides otherwise, and changes the
behavior (which I doubt will happen, in particular
because of backward incompatibility), IMO it's the doc
that needs to be changed to fit the behavior, not the
other way around.

I don't understand the hesitation to make the doc say
just what the truth is.  It doesn't take any more text.
I already suggested wording, and I made clear that
other wording that says the same thing (describes the
behavior accurately) would be fine instead.

What's the pushback, here?  Why shouldn't we make the
doc tell the real story wrt the ARG that Lisp expects?