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

Previous Next

Full log

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

Previous Next

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