From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Lars Ingebrigtsen Newsgroups: gmane.emacs.bugs Subject: bug#26301: 24.5; `define-derived-mode': different signatures for doc string & manual Date: Fri, 26 Jul 2019 13:04:11 +0200 Message-ID: <8736itnjkk.fsf@mouse.gnus.org> References: <8cad00f7-f86e-4d12-ad36-05214708aff1@default> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="227685"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) Cc: 26301@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Jul 26 13:05:15 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1hqy2E-000x7H-Qq for geb-bug-gnu-emacs@m.gmane.org; Fri, 26 Jul 2019 13:05:14 +0200 Original-Received: from localhost ([::1]:38460 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hqy2D-0000BZ-CM for geb-bug-gnu-emacs@m.gmane.org; Fri, 26 Jul 2019 07:05:13 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:50670) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hqy29-00008L-3C for bug-gnu-emacs@gnu.org; Fri, 26 Jul 2019 07:05:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hqy24-0007IJ-8f for bug-gnu-emacs@gnu.org; Fri, 26 Jul 2019 07:05:06 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:60374) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hqy22-0007Ga-KI for bug-gnu-emacs@gnu.org; Fri, 26 Jul 2019 07:05:04 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hqy22-0007Z0-EV for bug-gnu-emacs@gnu.org; Fri, 26 Jul 2019 07:05:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Lars Ingebrigtsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 26 Jul 2019 11:05:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 26301 X-GNU-PR-Package: emacs Original-Received: via spool by 26301-submit@debbugs.gnu.org id=B26301.156413905928987 (code B ref 26301); Fri, 26 Jul 2019 11:05:02 +0000 Original-Received: (at 26301) by debbugs.gnu.org; 26 Jul 2019 11:04:19 +0000 Original-Received: from localhost ([127.0.0.1]:40955 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hqy1L-0007XT-5d for submit@debbugs.gnu.org; Fri, 26 Jul 2019 07:04:19 -0400 Original-Received: from quimby.gnus.org ([80.91.231.51]:59746) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hqy1I-0007XI-VU for 26301@debbugs.gnu.org; Fri, 26 Jul 2019 07:04:17 -0400 Original-Received: from cm-84.212.202.86.getinternet.no ([84.212.202.86] helo=marnie) by quimby.gnus.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1hqy1D-0005fn-Vs; Fri, 26 Jul 2019 13:04:14 +0200 In-Reply-To: <8cad00f7-f86e-4d12-ad36-05214708aff1@default> (Drew Adams's message of "Wed, 29 Mar 2017 08:03:43 -0700 (PDT)") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:163763 Archived-At: Drew Adams 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=E2=80=A6 = body=E2=80=A6 > > 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 =E2=80=98customiz= e-mode=E2=80=99 > 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. --=20 (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no