From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#56217: 26.3; Elisp manual: Document keyword parameters to a function (lambda list) Date: Sat, 25 Jun 2022 16:27:04 +0000 Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="6921"; mail-complaints-to="usenet@ciao.gmane.io" To: 56217@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Jun 25 18:28:17 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1o58ds-0001di-1g for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 25 Jun 2022 18:28:16 +0200 Original-Received: from localhost ([::1]:42436 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1o58dq-0002BU-Ji for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 25 Jun 2022 12:28:14 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:37812) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1o58de-00029L-Jo for bug-gnu-emacs@gnu.org; Sat, 25 Jun 2022 12:28:05 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:52183) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1o58de-0001Sb-Bq for bug-gnu-emacs@gnu.org; Sat, 25 Jun 2022 12:28:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1o58de-0005Pi-81 for bug-gnu-emacs@gnu.org; Sat, 25 Jun 2022 12:28: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: Sat, 25 Jun 2022 16:28:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 56217 X-GNU-PR-Package: emacs X-Debbugs-Original-To: "bug-gnu-emacs@gnu.org" Original-Received: via spool by submit@debbugs.gnu.org id=B.165617444420763 (code B ref -1); Sat, 25 Jun 2022 16:28:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 25 Jun 2022 16:27:24 +0000 Original-Received: from localhost ([127.0.0.1]:46079 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1o58d2-0005Oo-CN for submit@debbugs.gnu.org; Sat, 25 Jun 2022 12:27:24 -0400 Original-Received: from lists.gnu.org ([209.51.188.17]:49630) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1o58cy-0005Oe-9Z for submit@debbugs.gnu.org; Sat, 25 Jun 2022 12:27:22 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:37338) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1o58cy-0001pC-3C for bug-gnu-emacs@gnu.org; Sat, 25 Jun 2022 12:27:20 -0400 Original-Received: from mx0a-00069f02.pphosted.com ([205.220.165.32]:48866) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1o58cs-0001K4-RS for bug-gnu-emacs@gnu.org; Sat, 25 Jun 2022 12:27:19 -0400 Original-Received: from pps.filterd (m0246629.ppops.net [127.0.0.1]) by mx0b-00069f02.pphosted.com (8.17.1.5/8.17.1.5) with ESMTP id 25PDEZMI011589 for ; Sat, 25 Jun 2022 16:27:07 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : subject : date : message-id : content-type : content-transfer-encoding : mime-version; s=corp-2021-07-09; bh=ibY8Blz4bkEeZSNV9VhXUlj9eW6o9s2nmXSdGCLDfdQ=; b=FiruGeG9j31Pr2j5KV19AxNoBehoRxV7AXv+biV3/Vq3duUTlJ7lkbApP8ADYiQzLU19 By2CQy9tM3dFlU4lmmDv0lywlDsDOpro3ICS8+Ski46Q0OSfbUmlqkUmMVnQHHN7kRnM GB9FWH3O0mYC3KUatnrfjw/rWSv0jK7RznOumyuXYcu84L6vfbgsLEcM0cYwO5szK5Dp FcQH1Y58j4Nq1+e5fZD/yhpZcMZ9swoxcxTlnk6e5yTDt2pXtKB+o2Q327szuJx6YFIC Az6aa9TUH1zy7cS88cb5rzQRyGNic1y7NfeKYRRukXnOweLwr5K7JEuJ/zbIipvSVkJd 3w== Original-Received: from iadpaimrmta01.imrmtpd1.prodappiadaev1.oraclevcn.com (iadpaimrmta01.appoci.oracle.com [130.35.100.223]) by mx0b-00069f02.pphosted.com (PPS) with ESMTPS id 3gwt89rk9r-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Sat, 25 Jun 2022 16:27:07 +0000 Original-Received: from pps.filterd (iadpaimrmta01.imrmtpd1.prodappiadaev1.oraclevcn.com [127.0.0.1]) by iadpaimrmta01.imrmtpd1.prodappiadaev1.oraclevcn.com (8.16.1.2/8.16.1.2) with SMTP id 25PG6haw013894 for ; Sat, 25 Jun 2022 16:27:06 GMT Original-Received: from nam12-bn8-obe.outbound.protection.outlook.com (mail-bn8nam12lp2174.outbound.protection.outlook.com [104.47.55.174]) by iadpaimrmta01.imrmtpd1.prodappiadaev1.oraclevcn.com with ESMTP id 3gwrt69knc-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Sat, 25 Jun 2022 16:27:06 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=NAXfzbuiv/cLoubL/rrUpMh6iAyz+MwH4wLVYAvaV9aReR/aVJ8TQ+7zh4AR32ttgwQp7vavY5ux/sUQgjSLzm8981pha4ogeqQBfic417g5Ud8FJor8H53d2wiBciRPDp9HfJvX3isipI13o7I3A0BAqv+iJDyhOEU4Yd+4vaVFUqOqS03DrxVIjm0WmbMPkE3eq+n/HALR2pzv+ExVTXuoa5g/Wzc1S7Qfa6fuvgxnV5IAbHs8moAVtDLlAdgdpjaBHa9VRd4oFyglG/zVuBuWt38P1gLyzNVFMuCxT6kIrruTSllQcRf39CRmlptSVfIzYU1FFU9SJJuW6ww3LA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=ibY8Blz4bkEeZSNV9VhXUlj9eW6o9s2nmXSdGCLDfdQ=; b=hO9/tjY2ap0GmZGbdWxJxNoZg3jj47QbuvA9Hzii0n6SO270KeoS0zm3NXp6efI+psT9VlXOScnwIKjHrX4z2tRCrBp2aw9ZMin3Hd/cy1mSWKl4/rFFoUzlcws0yBuOl4+Tpmoq8Jp4e+L31U6t8owQdwHqtK+fwi9pHLpNYAP/6dZbhZUnP9xdAHEBusixI6hLIgUt16vcJB1g9PpNGsu0A5FGDx9Kf3HhYKTmsGgIJoTFfGeUI/e2RPVdhe0j5GdHFGaPHLV1AUdsZAs/iJDw1My79t5rqRuNYBer410BZM2uQeLffKIUH7W1dn67kazT6L/RxTfK0tzsFxJkJw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=oracle.com; dmarc=pass action=none header.from=oracle.com; dkim=pass header.d=oracle.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.onmicrosoft.com; s=selector2-oracle-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=ibY8Blz4bkEeZSNV9VhXUlj9eW6o9s2nmXSdGCLDfdQ=; b=vsZU83mFH0NTESm8Vf+Gv7wpng+9+KImS6yZjrzfNrSazL0d5Kun7tR9UWSS1Sg5R8Y0o+mQ9snnrRgzeDJ2ccOKA9ZKyyigWKRE89V2L721o8S0PZYpHV4LiBMxx7iTp1jb6bdRivpyGTSP8sui+FfxmzJkqDkXRSQl7s0CUsg= Original-Received: from SJ0PR10MB5488.namprd10.prod.outlook.com (2603:10b6:a03:37e::19) by MN2PR10MB3614.namprd10.prod.outlook.com (2603:10b6:208:111::16) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5353.18; Sat, 25 Jun 2022 16:27:04 +0000 Original-Received: from SJ0PR10MB5488.namprd10.prod.outlook.com ([fe80::581b:ae2f:16b9:80fb]) by SJ0PR10MB5488.namprd10.prod.outlook.com ([fe80::581b:ae2f:16b9:80fb%6]) with mapi id 15.20.5373.018; Sat, 25 Jun 2022 16:27:04 +0000 Thread-Topic: 26.3; Elisp manual: Document keyword parameters to a function (lambda list) Thread-Index: AdiIsGY3KmWCojTaTJa0Ac4ZhJ5jrA== Accept-Language: en-US Content-Language: en-US x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: b72b9ad0-4ad9-4ca9-4925-08da56c78a5a x-ms-traffictypediagnostic: MN2PR10MB3614:EE_ x-ms-exchange-senderadcheck: 1 x-ms-exchange-antispam-relay: 0 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: DTXokanIIiJCgLlPZ8x0zhoVjmcl6hkHNIBHmcOMoG3gR4dNobUHRF+KTlGDmaILbzj9NRGJfyMftFWu/CzD6ublx5PREJH/2LNTCVJmBmrKx0QwCK0Bjsw0PypeH6QDYMz27Wje3bKXYRtxeCgsIiABxbuboi6R9D4oLjJ0BSGvPY3WLjX+Gf+aqk33YI4CdWHOaCrVOCLMqwbYvTCcQCHA3riNdd3HzYpME9q/oqGW7s9Nu9sNYUpg2p/OuXW+USMYXDwlFWhsIc5GacNBukKIZ9aD/yj5nnaSWll5QznEHnOC/dHCbibxgyRf8Y0Vq9RznYz0E9Ae5DhoNn9K5/IPwW8X2dWyEiukEAKHlXkjnhbWa+BzQYapKsWI+qS0sKFOTcaAVw/t3Egx2TB1A7xLDpsrZUfvPwYALMQT45HtQaRSjO4ujgeUyVoyMkarfPYD21RKlEE5ZILyY5TVhdOZ1k7LOmU0kOHOCtYEMv5U1tfwyNE2oieA6PzIpdr8z2I0PZnMxcRBQnTO//l9WEVmN3iQUwJgTkdPeYCxloZmPD3TrySGbRm5i0PB1ksj0nmDZAXHOOX/8dg9x5HQl+0tVQZbXN9RPnrgBUar6cCdQ567kItO0fJYRR8QhJT+dYHIe12d/Y6ePjtVMNnvFqTmVEYxsEmNU+aswnGYk6fyh6gL95mDwZyKoRmdCGnIJIsSfSfx0Jq2dXX77wrLvrWPm0YFDu/YwAjq7QIHE3T1dW1qV0x3NuC8/GCHB 2gNilm0gibZGtHCc9CBI09yEFPuOOvy43Jv1CpZy2A9MTs= x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:SJ0PR10MB5488.namprd10.prod.outlook.com; PTR:; CAT:NONE; SFS:(13230016)(136003)(39860400002)(376002)(396003)(346002)(366004)(8936002)(66476007)(9686003)(41300700001)(45080400002)(2906002)(5660300002)(26005)(122000001)(66946007)(38070700005)(86362001)(64756008)(52536014)(186003)(83380400001)(66556008)(44832011)(38100700002)(76116006)(316002)(7696005)(8676002)(71200400001)(478600001)(66446008)(55016003)(6916009)(6506007)(33656002); DIR:OUT; SFP:1101; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: 4BvXxS8ikil5+JD5hmvJbKq1w3L848MQhi516OasBXJqy+SZd+AZaQwd6RWI3isSK9cXF/qmYMUZOC2yl+PpKaN7+XMJXQajrYTusdk5WFdhdsipoUnpaOS44F0kABYKONUJcgvkyd44ytDDT/q3JjNGyyzR1Qpb8E5nRsTPuyNPLHt1xtbzx4n0d+gS9AxOvEqkk3o151FgG9U+b6Q4bzTIWrmgY+NFL3B4R3pYVzDtQr58RhAGj3g9G4XIoV0cAZBdgPEobHGOFvzpPeWuEx5c2LK46ioBYAa77ZuSaRp8VWaTc9qhHotlJns1xg+JLVtwYF1/rofbhT+NPye58suqSOpTIKYZPFYp8hbzyNrOWDedQpBk1LJANjMpwsGey656mNMU0nOX+YjT7xnDOXJ17chNA3lVerjXe92/cneJ2JPNr0bCByhopbeeDSj+mH+aDxLpZIi06/R/qglbI2mViQRwq/9y7sdcZeYulIX1P5GY44CW+TkaYU1XcKBhQOvpi+AL14bA67+iIYxZuGDVecT/J64OQM+o9v0icUU1KrsCc/3MBOCBgJ7gMZjakyd9hZ5yKsyJ53Hda4FWzCkdRIlVwu/yveWGS3C9O5JyaYFTlqlmd0X7sTU1Jc7JPiO/xXMKNi6/VK59E1L1oTDA+8GE5L8/MP37OrIDqTFB17O6mjIda03XTfbLHRHEyIST1bA+Q8OQJsskWndBr8V5OTEVPrLguPOr/WM/yl6L/r9mV+objpO+ZK NQ4BdMsQ6Lexsm2hpgVgIQp3FN5ioA9ie9tZBIdALkOjRgmHOcJpp2pOBYor01ctHMN/Ja6It8lvCBY5Ul4OyU1YVzq1hdxm+I X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: SJ0PR10MB5488.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: b72b9ad0-4ad9-4ca9-4925-08da56c78a5a X-MS-Exchange-CrossTenant-originalarrivaltime: 25 Jun 2022 16:27:04.5531 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: Y5yiKZkcpV3gn6dMVMQQ/keaFDTqsOxbenBPj/JJET/NwH4vWpixrl9Mnsl/kRLBlZnbLTY0nJmkuA1ZiDoXKw== X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN2PR10MB3614 X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:6.0.517, 18.0.883 definitions=2022-06-25_05:2022-06-24, 2022-06-25 signatures=0 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 spamscore=0 bulkscore=0 mlxlogscore=999 suspectscore=0 adultscore=0 phishscore=0 malwarescore=0 mlxscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2204290000 definitions=main-2206250069 X-Proofpoint-ORIG-GUID: 88FlYaFFS_v8TARLpeQMVCx36hAnz2ZA X-Proofpoint-GUID: 88FlYaFFS_v8TARLpeQMVCx36hAnz2ZA Received-SPF: pass client-ip=205.220.165.32; envelope-from=drew.adams@oracle.com; helo=mx0a-00069f02.pphosted.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:235279 Archived-At: Searching the Index of the Elisp manual for "keyword", I don't see any entries that help you get to doc about keyword parameters in a lambda list. (I mean the use of a keyword such as :keymap with `define-minor-mode', not a description of things like `&rest'.) Please add some index entries for this. What's more, I don't even find any presentation in the manual about keyword parameters, except for the mention more or less in passing of some specific keyword parameters in node `Defining Minor Modes'. Please add a description. Users should get info about how actual arguments are processed - e.g., in what order, when for example, optional and keyword args are both accepted by a function. (It's possible that there _is_ some such specification/explanation of what keyword parameters are, and how they're processed - e.g., in what order, but I didn't find any.) Keyword args are particular, in that to pass one you pass _two_ Lisp values: first the keyword symbol and then the value for that keyword. That isn't the case for other arguments. In addition there's the question of whether supplied keyword args are included in those accumulated for the &rest arg. See Common Lisp for how it handles this: Next, any keyword parameters are processed. For this purpose the same arguments are processed that would be made into a list for a rest parameter. (Indeed, it is permitted to specify both &rest and &key. In this case the remaining arguments are used for both purposes; that is, all remaining arguments are made into a list for the &rest parameter and are also processed for the &key parameters. This is the only situation in which an argument is used in the processing of more than one parameter specifier.) -- Common Lisp The Language (2), section 5.2.2, Lambda-Expressions Whatever the Elisp way of handling keyword parameters might be, it should be clearly specified somewhere in the manual. So far, all I've found it a bit of hand-waving. In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32) of 2019-08-29 Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd Windowing system distributor `Microsoft Corp.', version 10.0.19044 Configured using: `configure --without-dbus --host=3Dx86_64-w64-mingw32 --without-compress-install 'CFLAGS=3D-O2 -static -g3''