all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#26301: 24.5; `define-derived-mode': different signatures for doc string & manual
@ 2017-03-29 15:03 Drew Adams
  2019-07-26 11:04 ` Lars Ingebrigtsen
  0 siblings, 1 reply; 12+ messages in thread
From: Drew Adams @ 2017-03-29 15:03 UTC (permalink / raw)
  To: 26301

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'





^ permalink raw reply	[flat|nested] 12+ messages in thread

end of thread, other threads:[~2019-07-28  0:14 UTC | newest]

Thread overview: 12+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2017-03-29 15:03 bug#26301: 24.5; `define-derived-mode': different signatures for doc string & manual Drew Adams
2019-07-26 11:04 ` Lars Ingebrigtsen
2019-07-26 14:50   ` Drew Adams
2019-07-26 14:54   ` Noam Postavsky
2019-07-26 15:08     ` Lars Ingebrigtsen
2019-07-26 15:51       ` Drew Adams
2019-07-26 15:38     ` Drew Adams
2019-07-27 10:03     ` Lars Ingebrigtsen
2019-07-27 16:54       ` Drew Adams
2019-07-27 22:19         ` Michael Heerdegen
2019-07-28  0:01           ` Drew Adams
2019-07-28  0:14             ` Michael Heerdegen

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.