From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#26301: 24.5; `define-derived-mode': different signatures for doc string & manual Date: Fri, 26 Jul 2019 07:50:37 -0700 (PDT) Message-ID: <45b0c967-edca-4ffa-b854-859965486828@default> References: <8cad00f7-f86e-4d12-ad36-05214708aff1@default> <8736itnjkk.fsf@mouse.gnus.org> 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="149328"; mail-complaints-to="usenet@blaine.gmane.org" Cc: 26301@debbugs.gnu.org To: Lars Ingebrigtsen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Jul 26 16:51:21 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 1hr1Z3-000cix-9y for geb-bug-gnu-emacs@m.gmane.org; Fri, 26 Jul 2019 16:51:21 +0200 Original-Received: from localhost ([::1]:40796 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hr1Z1-0004d5-LO for geb-bug-gnu-emacs@m.gmane.org; Fri, 26 Jul 2019 10:51:19 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:57172) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hr1Ym-0003wF-Tw for bug-gnu-emacs@gnu.org; Fri, 26 Jul 2019 10:51:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hr1Yk-00081x-U0 for bug-gnu-emacs@gnu.org; Fri, 26 Jul 2019 10:51:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:34325) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hr1Yk-00081C-31 for bug-gnu-emacs@gnu.org; Fri, 26 Jul 2019 10:51:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1hr1Yk-0000wP-01 for bug-gnu-emacs@gnu.org; Fri, 26 Jul 2019 10:51:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 26 Jul 2019 14:51:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 26301 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: fixed Original-Received: via spool by 26301-submit@debbugs.gnu.org id=B26301.15641526493599 (code B ref 26301); Fri, 26 Jul 2019 14:51:01 +0000 Original-Received: (at 26301) by debbugs.gnu.org; 26 Jul 2019 14:50:49 +0000 Original-Received: from localhost ([127.0.0.1]:43146 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hr1YW-0000vy-J8 for submit@debbugs.gnu.org; Fri, 26 Jul 2019 10:50:48 -0400 Original-Received: from aserp2120.oracle.com ([141.146.126.78]:60968) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hr1YV-0000vl-91 for 26301@debbugs.gnu.org; Fri, 26 Jul 2019 10:50:47 -0400 Original-Received: from pps.filterd (aserp2120.oracle.com [127.0.0.1]) by aserp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x6QEmM7u136973; Fri, 26 Jul 2019 14:50:40 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=jFfU+lXcPJXLqczBJ0zMthRrxoffja1MFxGIn8t39RI=; b=F4fiIk5PqzjF7U5Mh4qoQW0tffsOWeafxZK6RF6ilbM8aaCCsx9g39fEgG7P3bHoVjDM ylTkTK+WLVAj9vXQOlm5gIsHRFV+7gJhZovG/PRvm3AytIpAz1Cm1HHihlmhrjQrf6BL u5mUT3fb78Iq21WIfuLdao/XDRXS5iF/Kz8rVb96eK9sBwggQ2I8Vk11I14ylNCIGmm8 tnod/XLzW+fuv20vcEplCAe7yuLkg8wfEbR8M++r3xsElQ2vFBL3mkvI/cwRFMEZX1xS YHAM1YddA5q+VEPIxEwTu85k10aNzMOH9ZQzhCQ8s/Nwgl6nszrKTZo0GHUD/09Nv5GV LQ== Original-Received: from aserp3030.oracle.com (aserp3030.oracle.com [141.146.126.71]) by aserp2120.oracle.com with ESMTP id 2tx61canyx-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 26 Jul 2019 14:50:40 +0000 Original-Received: from pps.filterd (aserp3030.oracle.com [127.0.0.1]) by aserp3030.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x6QElY2s015385; Fri, 26 Jul 2019 14:50:39 GMT Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by aserp3030.oracle.com with ESMTP id 2tx60yg557-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 26 Jul 2019 14:50:39 +0000 Original-Received: from abhmp0011.oracle.com (abhmp0011.oracle.com [141.146.116.17]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id x6QEocAX013634; Fri, 26 Jul 2019 14:50:38 GMT In-Reply-To: <8736itnjkk.fsf@mouse.gnus.org> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4873.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9330 signatures=668685 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1906280000 definitions=main-1907260182 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9330 signatures=668685 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1011 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1906280000 definitions=main-1907260182 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:163793 Archived-At: > > No KEYWORD-ARGS. They are included in BODY, so the specifications of > > BODY differ between the two. >=20 > 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? =20 > 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. >=20 > 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.