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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 26301 in the body.
You can then email your comments to 26301 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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'

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 26301 <at> debbugs.gnu.org
Subject: Re: bug#26301: 24.5; `define-derived-mode': different signatures
 for doc string & manual
Date: Fri, 26 Jul 2019 13:04:11 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

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

I guess the manual here try to describe the conceptual semantics (i.e.,
that if you put keywords there, they'll be interpreted as such), while
the doc string doesn't lie about what goes where.  Because the calling
convention is automatically generated there, which makes pretending a
bit more difficult.

I don't think describing it both ways is very confusing.

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

I've now rewritten to avoid the amusing word.

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

I don't think any of those questions are reasonable, so saying something
about that would be confusing.

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

"As a more complex example" is perhaps better.

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

I can't find the string "experimental" in that node in the manual, so I
guess this has been fixed.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 26301 <at> debbugs.gnu.org
Subject: RE: bug#26301: 24.5; `define-derived-mode': different signatures for
 doc string & manual
Date: Fri, 26 Jul 2019 07:50:37 -0700 (PDT)

> > No KEYWORD-ARGS.  They are included in BODY, so the specifications of
> > BODY differ between the two.
> 
> I guess the manual here try to describe the conceptual semantics (i.e.,
> that if you put keywords there, they'll be interpreted as such), while
> the doc string doesn't lie about what goes where.  Because the calling
> convention is automatically generated there, which makes pretending a
> bit more difficult.

"The doc string doesn't lie."  Is that the best we
can say for it?  Why gratuitously introduce a mismatch
between the two?  That just makes things harder for
users, no?

I don't know what you're saying by your last sentence,
in particular this: " which makes pretending a bit more
difficult."  No idea what pretending you mean.

What's the reason we wouldn't want KEYWORD-ARGS
described in the doc string?
 
> I don't think describing it both ways is very confusing.

Why should it be confusing at all?  Is plain confusing
OK but very confusing not OK?  It might be OK if there
were a good reason for it, but I haven't seen that yet.

> > The treatment of keyword args is not well specified.
> 
> I don't think any of those questions are reasonable,

Why?  What's unreasonable about wanting to know
whether you can specify multiple :group entries,
as you can do with defcustom, for instance?

We specifically provide such info for `defcustom'
(elisp) `Common Keywords', under `:group':

  If you use this keyword more than once, you can put
  a single item into more than one group.

`define-minor-mode' generates defcustom forms.  Its
doc should at least say that KEYWORD-ARGS can be
any list of keyword entries acceptable to defcustom,
and then point to the defcustom doc (where we say
that you can use multiple :group's to add an option
to multiple groups.

> so saying something about that would be confusing.

Do you think our saying it for defcustom is confusing
also?  Why should it be confusing here?  That's exactly
what KEYWORD-ARGS specifies: defcustom keyword entries.

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

From: Noam Postavsky <npostavs <at> gmail.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 26301 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#26301: 24.5;
 `define-derived-mode': different signatures for doc string & manual
Date: Fri, 26 Jul 2019 10:54:31 -0400

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

> Drew Adams <drew.adams <at> oracle.com> writes:
>
>> 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.
>
> I guess the manual here try to describe the conceptual semantics (i.e.,
> that if you put keywords there, they'll be interpreted as such), while
> the doc string doesn't lie about what goes where.  Because the calling
> convention is automatically generated there, which makes pretending a
> bit more difficult.

Docstrings can override the automatically generated signature by using

(fn ...)

So maybe we should do that here?

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 26301 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#26301: 24.5; `define-derived-mode': different signatures
 for doc string & manual
Date: Fri, 26 Jul 2019 17:08:35 +0200

Noam Postavsky <npostavs <at> gmail.com> writes:

> Docstrings can override the automatically generated signature by using
>
> (fn ...)
>
> So maybe we should do that here?

Hm...  didn't think about that.  I guess that makes sense?  We'd say

(fn ... &rest KEYWORDS &body body)

or something?  (Slightly Common Lispish.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Noam Postavsky <npostavs <at> gmail.com>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 26301 <at> debbugs.gnu.org
Subject: RE: bug#26301: 24.5; `define-derived-mode': different signatures for
 doc string & manual
Date: Fri, 26 Jul 2019 08:38:12 -0700 (PDT)

> Docstrings can override the automatically generated signature by using
> (fn ...)
> So maybe we should do that here?

Exactly.  I should have thought to suggest that myself.
Please do.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Noam Postavsky <npostavs <at> gmail.com>
Cc: 26301 <at> debbugs.gnu.org
Subject: RE: bug#26301: 24.5; `define-derived-mode': different signatures for
 doc string & manual
Date: Fri, 26 Jul 2019 08:51:48 -0700 (PDT)

> > Docstrings can override the automatically generated signature by
> using
> >
> > (fn ...)
> >
> > So maybe we should do that here?
> 
> Hm...  didn't think about that.  I guess that makes sense?  We'd say
> 
> (fn ... &rest KEYWORDS &body body)
> 
> or something?  (Slightly Common Lispish.)

I'm no expert on how we would write it.
But in Common Lisp you cannot have both &rest
and &body at the same level, I believe.

Maybe this?

(fn CHILD PARENT NAME &optional DOCSTRING KEYWORDS &rest BODY)

And let the doc string describe KEYWORDS properly,
to make clear that it's any number of keyword
entries (keyword followed by its value).

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 26301 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#26301: 24.5; `define-derived-mode': different signatures
 for doc string & manual
Date: Sat, 27 Jul 2019 12:03:38 +0200

Noam Postavsky <npostavs <at> gmail.com> writes:

> Docstrings can override the automatically generated signature by using
>
> (fn ...)
>
> So maybe we should do that here?

I grepped a bit and had a look at what a few other functions that have
the same general issue (i.e., that the BODY argument may be prepended
with stuff that's "logically" a different argument):

(defmacro cl-defgeneric (name args &rest options-and-methods)
\(fn NAME ARGS [DOC-STRING] [OPTIONS-AND-METHODS...] &rest DEFAULT-BODY)

(defmacro cl-defmethod (name args &rest body)
\(fn NAME [QUALIFIER] ARGS &rest [DOCSTRING] BODY)"

(defmacro pcase-defmacro (name args &rest body)
\(fn NAME ARGS [DOC] &rest BODY...)

So if we model ourself after cl-defgeneric here, that'd be:

(defmacro define-derived-mode (child parent name &optional docstring &rest body)
\(fn CHILD PARENT NAME [DOCSTRING] [KEYWORDS...] &rest BODY)

So I've now done this and adjusted the rest of the doc string
accordingly.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Noam Postavsky <npostavs <at> gmail.com>
Cc: 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 09:54:45 -0700 (PDT)

> \(fn CHILD PARENT NAME [DOCSTRING] [KEYWORDS...] &rest BODY)
> 
> So I've now done this and adjusted the rest of the doc string
> accordingly.

Sounds good.  That's what I suggested, but with the
addition of the `...' (good).

However, in that case, KEYWORDS is the _wrong_ name.

It is not _keywords_, which is presumably a _list_
of keywords (or more exactly, keyword key-value
pairs), that is repeated.  What is optional is not
a list of lists.  What is optional is a list of
keywords (or more exactly...).

The name should be KEYWORD or KEYWORD-ENTRY or
KEYWORD-PAIR or some such.  It should not be
KEYWORDS.

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Drew Adams <drew.adams <at> oracle.com>
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: Sun, 28 Jul 2019 00:19:27 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> > \(fn CHILD PARENT NAME [DOCSTRING] [KEYWORDS...] &rest BODY)
> >
> > So I've now done this and adjusted the rest of the doc string
> > accordingly.
>
> Sounds good.  That's what I suggested, but with the
> addition of the `...' (good).
>
> 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).

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

Michael.

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

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Drew Adams <drew.adams <at> oracle.com>
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: Sun, 28 Jul 2019 02:14:45 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

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

No, that's not the case.

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

Yes, or even [[KEYWORD VALUE]...]?

I don't know if we have an official convention at all.  In this case
here, since &rest is following this specification, I think eldoc will be
confused in any case since it can't distinguish between keyword-value
pairs and the following &rest BODY.

Michael.

Previous Next

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