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

[Drew Adams]

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.

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

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.

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

(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.


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=3D/c/usr --host=3Di686-pc-mingw32'