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

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

> > However, in that case, KEYWORDS is the _wrong_ name.
> 
> In a similar case, `define-globalized-minor-mode' uses the name KEYS
> (it's the name of the &rest arg though).

If each of the args in the &rest list is a KEY
then that's fine.

> > The name should be KEYWORD or KEYWORD-ENTRY or KEYWORD-PAIR or some
> > such.
> 
> I all find that not better.  KEYWORD fails to say that values are
> included.  KEYWORD-ENTRY and KEYWORD-PAIR are confising, they make it
> look like you would have to specify conses or two element lists.
> 
> I would prefer something like [KEYWORD VALUE ...], though I guess that
> would then confuse eldoc.

That's incorrect, I think, because it indicates
that VALUE is what is possibly repeated.  If the
convention doesn't actually specify that (I'm not
sure) that's at least what someone might suppose.

Dunno whether our convention allows [KEYWORD VALUE]...
(i.e., with the ... after the optional indication).

Otherwise, I'd suggest a name such as KEYWORD+VALUE:

 [KEYWORD+VALUE...]

(If this were not something added automatically by
handling (fn ...) then a single name (e.g. FOOBAR)
could be broken down in the doc string, saying that
FOOBAR is a keyword followed by its value.)