bug#26301: 24.5; `define-derived-mode': different signatures for doc string & manual

[Lars Ingebrigtsen <larsi@gnus.org>]

Drew Adams <drew.adams@oracle.com> writes:

> The signature is ultimately the same but it is documented differently.
> It would be better to use the same signature spec for both, unless
> there is a good reason not to.
>
> In the manual it is declared as being:
>
>  define-derived-mode variant parent name docstring keyword-args… body…
>
> In the doc string it is declared as being:
>
>  (define-derived-mode CHILD PARENT NAME &optional DOCSTRING &rest BODY)
>
> No KEYWORD-ARGS.  They are included in BODY, so the specifications of
> BODY differ between the two.

I guess the manual here try to describe the conceptual semantics (i.e.,
that if you put keywords there, they'll be interpreted as such), while
the doc string doesn't lie about what goes where.  Because the calling
convention is automatically generated there, which makes pretending a
bit more difficult.

I don't think describing it both ways is very confusing.

> The doc string says: "BODY can start with a bunch of keyword arguments."
> What's a "bunch" here?  Any number?  Not very clear.

I've now rewritten to avoid the amusing word.

> For both doc string and manual: Can any of the keyword args be repeated?
> Can you, for example, use :group more than once, to specify belonging to
> multiple groups?  If not, and if a keyword arg is present more than once,
> which one gets used?  Or is an error raised?  The treatment of keyword
> args is not well specified.

I don't think any of those questions are reasonable, so saying something
about that would be confusing.

> In the doc string, this expression is not good: "On a more complicated
> level".  Unclear, misleading, unhelpful.

"As a more complex example" is perhaps better.

> (On the plus sign, this doc string xrefs the node in the manual.)
>
> The manual also says this:
>
> "Only the (still experimental and unadvertised) command ‘customize-mode’
> currently uses this [the customization group]."
>
> The "still experimental and unadvertised" part is inappropriate, IMHO.
> And by including it we've just advertised it!  It is unclear what this
> statement is trying to convey to users, and why.

I can't find the string "experimental" in that node in the manual, so I
guess this has been fixed.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no