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

Previous Next

Package: emacs;

Reported by: Drew Adams <drew.adams <at> oracle.com>

Date: Wed, 29 Mar 2017 15:05:01 UTC

Severity: wishlist

Tags: fixed

Found in version 24.5

Fixed in version 27.1

Done: Lars Ingebrigtsen <larsi <at> gnus.org>

Bug is archived. No further changes may be made.

Full log


Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.5; `define-derived-mode': different signatures for doc string &
 manual
Date: Wed, 29 Mar 2017 08:03:43 -0700 (PDT)
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'




This bug report was last modified 5 years and 321 days ago.

Previous Next


GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.