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

Previous Next

Full log

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, Noam Postavsky <npostavs <at> gmail.com>,
 26301 <at> debbugs.gnu.org
Subject: RE: bug#26301: 24.5; `define-derived-mode': different signatures for
 doc string & manual
Date: Sat, 27 Jul 2019 17:01:30 -0700 (PDT)

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

Previous Next

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