From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!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: Wed, 29 Mar 2017 08:03:43 -0700 (PDT) Message-ID: <8cad00f7-f86e-4d12-ad36-05214708aff1@default> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1490799931 5648 195.159.176.226 (29 Mar 2017 15:05:31 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 29 Mar 2017 15:05:31 +0000 (UTC) To: 26301@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Mar 29 17:05:27 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ctF9t-0008Lw-Rj for geb-bug-gnu-emacs@m.gmane.org; Wed, 29 Mar 2017 17:05:14 +0200 Original-Received: from localhost ([::1]:59550 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ctFA0-0006dH-0F for geb-bug-gnu-emacs@m.gmane.org; Wed, 29 Mar 2017 11:05:20 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49450) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ctF9m-0006XD-DQ for bug-gnu-emacs@gnu.org; Wed, 29 Mar 2017 11:05:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ctF9i-0005IJ-5a for bug-gnu-emacs@gnu.org; Wed, 29 Mar 2017 11:05:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:53269) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1ctF9i-0005IF-3B for bug-gnu-emacs@gnu.org; Wed, 29 Mar 2017 11:05:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ctF9h-0005Cc-Qf for bug-gnu-emacs@gnu.org; Wed, 29 Mar 2017 11:05:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 29 Mar 2017 15:05:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 26301 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.149079984419866 (code B ref -1); Wed, 29 Mar 2017 15:05:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 29 Mar 2017 15:04:04 +0000 Original-Received: from localhost ([127.0.0.1]:51465 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ctF8l-0005AM-Rk for submit@debbugs.gnu.org; Wed, 29 Mar 2017 11:04:04 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:58043) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ctF8k-00059l-0a for submit@debbugs.gnu.org; Wed, 29 Mar 2017 11:04:02 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ctF8e-0004zv-46 for submit@debbugs.gnu.org; Wed, 29 Mar 2017 11:03:56 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:54022) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1ctF8e-0004zp-1R for submit@debbugs.gnu.org; Wed, 29 Mar 2017 11:03:56 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:48977) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ctF8c-0006Dm-PF for bug-gnu-emacs@gnu.org; Wed, 29 Mar 2017 11:03:55 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ctF8V-0004x7-At for bug-gnu-emacs@gnu.org; Wed, 29 Mar 2017 11:03:54 -0400 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:40016) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1ctF8V-0004wq-2P for bug-gnu-emacs@gnu.org; Wed, 29 Mar 2017 11:03:47 -0400 Original-Received: from aserv0021.oracle.com (aserv0021.oracle.com [141.146.126.233]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v2TF3jKu012611 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Wed, 29 Mar 2017 15:03:45 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by aserv0021.oracle.com (8.13.8/8.14.4) with ESMTP id v2TF3jma026342 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL) for ; Wed, 29 Mar 2017 15:03:45 GMT Original-Received: from abhmp0007.oracle.com (abhmp0007.oracle.com [141.146.116.13]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id v2TF3j9c026065 for ; Wed, 29 Mar 2017 15:03:45 GMT X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6753.5000 (x86)] X-Source-IP: aserv0021.oracle.com [141.146.126.233] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x 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: 208.118.235.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:131060 Archived-At: 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 bo= dy=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. 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 =E2=80=98customize-= 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. 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=3D3D/c/usr --host=3D3Di686-pc-mingw32'