From unknown Tue Jun 17 20:14:39 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#25461 <25461@debbugs.gnu.org> To: bug#25461 <25461@debbugs.gnu.org> Subject: Status: Missing doc strings for "," and ",@". Reply-To: bug#25461 <25461@debbugs.gnu.org> Date: Wed, 18 Jun 2025 03:14:39 +0000 retitle 25461 Missing doc strings for "," and ",@". reassign 25461 emacs submitter 25461 Alan Mackenzie severity 25461 wishlist thanks From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 16 16:23:29 2017 Received: (at submit) by debbugs.gnu.org; 16 Jan 2017 21:23:29 +0000 Received: from localhost ([127.0.0.1]:55946 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTEkS-0005uA-Tj for submit@debbugs.gnu.org; Mon, 16 Jan 2017 16:23:29 -0500 Received: from eggs.gnu.org ([208.118.235.92]:33705) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTEkQ-0005tx-RC for submit@debbugs.gnu.org; Mon, 16 Jan 2017 16:23:27 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cTEkK-00051z-Tm for submit@debbugs.gnu.org; Mon, 16 Jan 2017 16:23:21 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50 autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:36235) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cTEkK-00051v-QT for submit@debbugs.gnu.org; Mon, 16 Jan 2017 16:23:20 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:52906) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cTEkJ-0005tk-Oh for bug-gnu-emacs@gnu.org; Mon, 16 Jan 2017 16:23:20 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cTEkE-00050Z-Q3 for bug-gnu-emacs@gnu.org; Mon, 16 Jan 2017 16:23:19 -0500 Received: from ocolin.muc.de ([193.149.48.4]:52926 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1cTEkE-000509-FE for bug-gnu-emacs@gnu.org; Mon, 16 Jan 2017 16:23:14 -0500 Received: (qmail 57680 invoked by uid 3782); 16 Jan 2017 21:23:12 -0000 Received: from acm.muc.de (p548C6E70.dip0.t-ipconnect.de [84.140.110.112]) by colin.muc.de (tmda-ofmipd) with ESMTP; Mon, 16 Jan 2017 22:23:11 +0100 Received: (qmail 4801 invoked by uid 1000); 16 Jan 2017 21:22:57 -0000 Date: Mon, 16 Jan 2017 21:22:57 +0000 To: bug-gnu-emacs@gnu.org Subject: Missing doc strings for "," and ",@". Message-ID: <20170116212257.GA4747@acm.fritz.box> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.5.24 (2015-08-30) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.4 (----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.4 (----) Hello, Emacs. With any existing Emacs, when I do C-h f , or C-h f ,@ , I get the response [No match] . This is bad. From a user's point of view, these key sequences should bring up doc strings for "," and ",@", especially seeing how important these symbols are, and how difficult they are to use for a lisper with limited experience. -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 17 14:34:28 2017 Received: (at 25461) by debbugs.gnu.org; 17 Jan 2017 19:34:28 +0000 Received: from localhost ([127.0.0.1]:56705 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTZWW-0007LN-Gn for submit@debbugs.gnu.org; Tue, 17 Jan 2017 14:34:28 -0500 Received: from eggs.gnu.org ([208.118.235.92]:50649) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTZWV-0007LB-2m for 25461@debbugs.gnu.org; Tue, 17 Jan 2017 14:34:27 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cTZWP-0005Id-5d for 25461@debbugs.gnu.org; Tue, 17 Jan 2017 14:34:21 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-3.7 required=5.0 tests=BAYES_05,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:42174) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cTZWL-0005G5-Ew; Tue, 17 Jan 2017 14:34:17 -0500 Received: from rgm by fencepost.gnu.org with local (Exim 4.82) (envelope-from ) id 1cTZWK-0006d0-Um; Tue, 17 Jan 2017 14:34:16 -0500 From: Glenn Morris To: Alan Mackenzie Subject: Re: bug#25461: Missing doc strings for "," and ",@". References: <20170116212257.GA4747@acm.fritz.box> X-Spook: New World Order bluebird Abu Sayyaf Tsunami Warning X-Ran: y}q;sScC4M5$ X-Hue: white X-Attribution: GM Date: Tue, 17 Jan 2017 14:34:16 -0500 In-Reply-To: <20170116212257.GA4747@acm.fritz.box> (Alan Mackenzie's message of "Mon, 16 Jan 2017 21:22:57 +0000") Message-ID: <3w1sw11nwn.fsf@fencepost.gnu.org> User-Agent: Gnus (www.gnus.org), GNU Emacs (www.gnu.org/software/emacs/) MIME-Version: 1.0 Content-Type: text/plain X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -8.2 (--------) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -8.2 (--------) Alan Mackenzie wrote: > With any existing Emacs, when I do > > C-h f , > > or > > C-h f ,@ > > , I get the response > > [No match] But they aren't functions, so I don't see why you want describe-function to report on them, or indeed how that would work. With this and 25462, it seems to me that what you want is a (context-sensitive?) type of help that does not exist yet, which would report on special syntax used within macros and such. (Both , and ,@ are indexed in the elisp manual, BTW.) From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 17 14:56:45 2017 Received: (at 25461) by debbugs.gnu.org; 17 Jan 2017 19:56:45 +0000 Received: from localhost ([127.0.0.1]:56726 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTZs5-0007uZ-1A for submit@debbugs.gnu.org; Tue, 17 Jan 2017 14:56:45 -0500 Received: from ocolin.muc.de ([193.149.48.4]:53205 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1cTZs3-0007uR-LQ for 25461@debbugs.gnu.org; Tue, 17 Jan 2017 14:56:44 -0500 Received: (qmail 96652 invoked by uid 3782); 17 Jan 2017 19:56:41 -0000 Received: from acm.muc.de (p548C72E2.dip0.t-ipconnect.de [84.140.114.226]) by colin.muc.de (tmda-ofmipd) with ESMTP; Tue, 17 Jan 2017 20:56:41 +0100 Received: (qmail 4680 invoked by uid 1000); 17 Jan 2017 19:56:27 -0000 Date: Tue, 17 Jan 2017 19:56:27 +0000 To: Glenn Morris Subject: Re: bug#25461: Missing doc strings for "," and ",@". Message-ID: <20170117195627.GA4169@acm.fritz.box> References: <20170116212257.GA4747@acm.fritz.box> <3w1sw11nwn.fsf@fencepost.gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <3w1sw11nwn.fsf@fencepost.gnu.org> User-Agent: Mutt/1.5.24 (2015-08-30) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -3.2 (---) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.2 (---) Hello, Glenn. On Tue, Jan 17, 2017 at 02:34:16PM -0500, Glenn Morris wrote: > Alan Mackenzie wrote: > > With any existing Emacs, when I do > > C-h f , > > or > > C-h f ,@ > > , I get the response > > [No match] > But they aren't functions, so I don't see why you want describe-function > to report on them, or indeed how that would work. I think I want some means of displaying "their doc strings". They're much more like functions than variables, so for lack of any third option, C-h f seems the best way of doing this display. I've hacked out a solution for this, involving defining defuns to hold the doc strings. I hope to post this patch on bug-gnu-emacs later on this evening (European time). > With this and 25462, it seems to me that what you want is a > (context-sensitive?) type of help that does not exist yet, which would > report on special syntax used within macros and such. No, nothing so general. pcase has introduced a lot of confusion (for me, at any rate, so probably also for a lot of hackers who aren't Emacs contributors), so I would like the doc strings to reduce this confusion as far is as reasonable. > (Both , and ,@ are indexed in the elisp manual, BTW.) That's as it should be. -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 17 15:36:23 2017 Received: (at 25461) by debbugs.gnu.org; 17 Jan 2017 20:36:23 +0000 Received: from localhost ([127.0.0.1]:34092 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTaUQ-0000vt-Rv for submit@debbugs.gnu.org; Tue, 17 Jan 2017 15:36:23 -0500 Received: from mail-out.m-online.net ([212.18.0.10]:60702) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTaUO-0000vl-P9 for 25461@debbugs.gnu.org; Tue, 17 Jan 2017 15:36:21 -0500 Received: from frontend01.mail.m-online.net (unknown [192.168.8.182]) by mail-out.m-online.net (Postfix) with ESMTP id 3v321v3B21z3hp4l; Tue, 17 Jan 2017 21:36:19 +0100 (CET) Received: from localhost (dynscan1.mnet-online.de [192.168.6.68]) by mail.m-online.net (Postfix) with ESMTP id 3v321v1HLhzvkbj; Tue, 17 Jan 2017 21:36:19 +0100 (CET) X-Virus-Scanned: amavisd-new at mnet-online.de Received: from mail.mnet-online.de ([192.168.8.182]) by localhost (dynscan1.mail.m-online.net [192.168.6.68]) (amavisd-new, port 10024) with ESMTP id b-r6-MRUg3wO; Tue, 17 Jan 2017 21:36:15 +0100 (CET) X-Auth-Info: HKfMJN7XlYV43ThgthuG9UBOqhXZV1aWFyopncwWOWo65vO0dO1L3hp0BcuGROjt Received: from igel.home (ppp-88-217-6-86.dynamic.mnet-online.de [88.217.6.86]) (using TLSv1 with cipher DHE-RSA-CAMELLIA256-SHA (256/256 bits)) (No client certificate requested) by mail.mnet-online.de (Postfix) with ESMTPSA; Tue, 17 Jan 2017 21:36:15 +0100 (CET) Received: by igel.home (Postfix, from userid 1000) id F3BAC2C4255; Tue, 17 Jan 2017 21:36:14 +0100 (CET) From: Andreas Schwab To: Alan Mackenzie Subject: Re: bug#25461: Missing doc strings for "," and ",@". References: <20170116212257.GA4747@acm.fritz.box> <3w1sw11nwn.fsf@fencepost.gnu.org> <20170117195627.GA4169@acm.fritz.box> X-Yow: .. hubub, hubub, HUBUB, hubub, hubub, hubub, HUBUB, hubub, hubub, hubub. Date: Tue, 17 Jan 2017 21:36:14 +0100 In-Reply-To: <20170117195627.GA4169@acm.fritz.box> (Alan Mackenzie's message of "Tue, 17 Jan 2017 19:56:27 +0000") Message-ID: <87k29t5sqp.fsf@linux-m68k.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.91 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 25461 Cc: Glenn Morris , 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) On Jan 17 2017, Alan Mackenzie wrote: > I think I want some means of displaying "their doc strings". They're much > more like functions than variables, They are neither, just syntactic elements. Andreas. -- Andreas Schwab, schwab@linux-m68k.org GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different." From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 17 15:41:37 2017 Received: (at 25461) by debbugs.gnu.org; 17 Jan 2017 20:41:37 +0000 Received: from localhost ([127.0.0.1]:34096 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTaZV-00013Y-H3 for submit@debbugs.gnu.org; Tue, 17 Jan 2017 15:41:37 -0500 Received: from ocolin.muc.de ([193.149.48.4]:43704 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1cTaZT-00013P-Ih for 25461@debbugs.gnu.org; Tue, 17 Jan 2017 15:41:36 -0500 Received: (qmail 9759 invoked by uid 3782); 17 Jan 2017 20:41:33 -0000 Received: from acm.muc.de (p548C72E2.dip0.t-ipconnect.de [84.140.114.226]) by colin.muc.de (tmda-ofmipd) with ESMTP; Tue, 17 Jan 2017 21:41:33 +0100 Received: (qmail 4927 invoked by uid 1000); 17 Jan 2017 20:41:19 -0000 Date: Tue, 17 Jan 2017 20:41:19 +0000 To: Andreas Schwab Subject: Re: bug#25461: Missing doc strings for "," and ",@". Message-ID: <20170117204119.GC4169@acm.fritz.box> References: <20170116212257.GA4747@acm.fritz.box> <3w1sw11nwn.fsf@fencepost.gnu.org> <20170117195627.GA4169@acm.fritz.box> <87k29t5sqp.fsf@linux-m68k.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <87k29t5sqp.fsf@linux-m68k.org> User-Agent: Mutt/1.5.24 (2015-08-30) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -3.2 (---) X-Debbugs-Envelope-To: 25461 Cc: Glenn Morris , 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.2 (---) Hello, Andreas. On Tue, Jan 17, 2017 at 09:36:14PM +0100, Andreas Schwab wrote: > On Jan 17 2017, Alan Mackenzie wrote: > > I think I want some means of displaying "their doc strings". They're much > > more like functions than variables, > They are neither, just syntactic elements. I don't expect the typical novice Elisp hacker cares about such nice distinctions. She can get a doc string for `, so why not one for , or ,@? Anyway, I'm going to be providing a patch to do this. We'll see whether people like it or not. > Andreas. > -- > Andreas Schwab, schwab@linux-m68k.org > GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 > "And now for something completely different." -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 17 15:53:39 2017 Received: (at 25461) by debbugs.gnu.org; 17 Jan 2017 20:53:39 +0000 Received: from localhost ([127.0.0.1]:34101 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTal9-0001Ko-Jx for submit@debbugs.gnu.org; Tue, 17 Jan 2017 15:53:39 -0500 Received: from mail-out.m-online.net ([212.18.0.10]:51625) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTal7-0001Kg-JT for 25461@debbugs.gnu.org; Tue, 17 Jan 2017 15:53:37 -0500 Received: from frontend01.mail.m-online.net (unknown [192.168.8.182]) by mail-out.m-online.net (Postfix) with ESMTP id 3v32Pr5tRKz3hpGq; Tue, 17 Jan 2017 21:53:36 +0100 (CET) Received: from localhost (dynscan1.mnet-online.de [192.168.6.68]) by mail.m-online.net (Postfix) with ESMTP id 3v32Pr49zNzvkcP; Tue, 17 Jan 2017 21:53:36 +0100 (CET) X-Virus-Scanned: amavisd-new at mnet-online.de Received: from mail.mnet-online.de ([192.168.8.182]) by localhost (dynscan1.mail.m-online.net [192.168.6.68]) (amavisd-new, port 10024) with ESMTP id RvdXb7JjpLnX; Tue, 17 Jan 2017 21:53:34 +0100 (CET) X-Auth-Info: aLGsKYMoa17/BQ1EFPyp0i33gWzp0/JZ7jPmsQmgtOGBpaKt+tV5BGPMvgwpVBWk Received: from igel.home (ppp-88-217-6-86.dynamic.mnet-online.de [88.217.6.86]) (using TLSv1 with cipher DHE-RSA-CAMELLIA256-SHA (256/256 bits)) (No client certificate requested) by mail.mnet-online.de (Postfix) with ESMTPSA; Tue, 17 Jan 2017 21:53:34 +0100 (CET) Received: by igel.home (Postfix, from userid 1000) id 29A452C4282; Tue, 17 Jan 2017 21:53:34 +0100 (CET) From: Andreas Schwab To: Alan Mackenzie Subject: Re: bug#25461: Missing doc strings for "," and ",@". References: <20170116212257.GA4747@acm.fritz.box> <3w1sw11nwn.fsf@fencepost.gnu.org> <20170117195627.GA4169@acm.fritz.box> <87k29t5sqp.fsf@linux-m68k.org> <20170117204119.GC4169@acm.fritz.box> X-Yow: Hello... IRON CURTAIN? Send over a SAUSAGE PIZZA! World War III? No thanks! Date: Tue, 17 Jan 2017 21:53:34 +0100 In-Reply-To: <20170117204119.GC4169@acm.fritz.box> (Alan Mackenzie's message of "Tue, 17 Jan 2017 20:41:19 +0000") Message-ID: <87fukh5rxt.fsf@linux-m68k.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.91 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) On Jan 17 2017, Alan Mackenzie wrote: > I don't expect the typical novice Elisp hacker cares about such nice > distinctions. A doc string is not for introduction of basics, a novice is expected to read the manual for that. > She can get a doc string for `, so why not one for , or ,@? The paren doesn't have a doc string either. Andreas. -- Andreas Schwab, schwab@linux-m68k.org GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different." From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 17 20:44:41 2017 Received: (at 25461) by debbugs.gnu.org; 18 Jan 2017 01:44:41 +0000 Received: from localhost ([127.0.0.1]:34183 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTfIn-0008Ae-2H for submit@debbugs.gnu.org; Tue, 17 Jan 2017 20:44:41 -0500 Received: from mout.web.de ([212.227.17.12]:51991) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTfIk-0008AP-2U for 25461@debbugs.gnu.org; Tue, 17 Jan 2017 20:44:39 -0500 Received: from drachen.dragon ([92.74.161.233]) by smtp.web.de (mrweb101 [213.165.67.124]) with ESMTPSA (Nemesis) id 0MF3nL-1cE2MQ0txL-00GInT; Wed, 18 Jan 2017 02:44:29 +0100 From: Michael Heerdegen To: Alan Mackenzie Subject: Re: bug#25461: Missing doc strings for "," and ",@". References: <20170116212257.GA4747@acm.fritz.box> <3w1sw11nwn.fsf@fencepost.gnu.org> <20170117195627.GA4169@acm.fritz.box> <87k29t5sqp.fsf@linux-m68k.org> <20170117204119.GC4169@acm.fritz.box> Date: Wed, 18 Jan 2017 02:44:28 +0100 In-Reply-To: <20170117204119.GC4169@acm.fritz.box> (Alan Mackenzie's message of "Tue, 17 Jan 2017 20:41:19 +0000") Message-ID: <87h94xdtvn.fsf@web.de> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.91 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Provags-ID: V03:K0:W8GCKurzd1grPw04LcoafxlOdSxxGC5itm5L6fDpVz4ZGJxAvXv ihGqcs2RnAxz7lekgDTM5oEWvHsFMbDS8zE0JDd+DUyOWYT4t6NigV3PsNhyRRhpRf5gMyF zzQki2IhAkEIBRrF5d2CnIWOD3ZRwfcrGhicY0P6pYhsQMFRX+ek3YxQ3YwZN2BxPBRhIa4 DzK82bpeG2h31/tHC1C8g== X-UI-Out-Filterresults: notjunk:1;V01:K0:XwzW8dHcRx4=:kO5cp31eCkjk3x2eI4mjYz sexgoA8eDP+6QBdVbp5JaasUhGbJ//btgz2+swvdPeWkI90tK1eBfG16LSDqIMMXhTVw8cKA3 8L4fVSLal7a5w71tZMKHd6054z6Ypdcr1jRmmAb+aS25FItNOjjZ35T/QX3kF0F0EcEs9UA1Z rGisRGb2fS+fpZvpAMETalZGIF4kvvzWqkuQffyiQGR9VUqFzc5LbLTMb5DnPwgUIWbt5H2nB l0TRVPNrjsKT+931jI+4VcjNign/Tk/I8KYabXnka2hwVeE51ZfK4Wq5ynYToHwd8r6yozvSR wENE9JfgAgSqIBgCSvxWcTJoZoUUd85C+AkQamUWzu13Ax3j7JOTJPON4Bd/ZUDU1dFkiHUdU v16IOrPL1Xh8mRWmKeyp9Suo2orwlVWO1tROUfI3z3jX49vvgSjlCXhpo7sy2xnLXp5fEbIae ziLHs689RA6fk6kGA7zkAbfYXqSkk7KBk8p3hRoivnmXRHZe7chK96tkRUkhX8YxGxgIguYQC Mf9cTMmBBEYiCiIU1IZrTqFsh9GTh42SZh7DHDCz1iOOEuKkJSSSFFti567vtmo65vY6kN5XG w4TJ/OyZlUQm5eZHgb4KWMS25FPkQhJAJdRdox4EddDo1D4YzZzyMLT7VZLpXExW56GMMlCn4 NiPjt5XnXuQKfp18ozxV74nQ1/p7YwfuiVovDxEIgIRttift3LNaL1Skm4tc+Ffdnx0DG50Wm oX0/NprO0m1lPH/+8lTHHQ6c0zTZzt+iLgrVpP7tYzDakqmFfof5Fh7IKozFDTxZZ0C2jCLzJ t+tPYet X-Spam-Score: -3.9 (---) X-Debbugs-Envelope-To: 25461 Cc: Andreas Schwab , 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.9 (---) Alan Mackenzie writes: > I don't expect the typical novice Elisp hacker cares about such nice > distinctions. She can get a doc string for `, so why not one for , or > ,@? ' and #' also "don't have a docstring". That ` "has a docstring" is just coincidence - because the reader transforms `expr to (` expr) and the symbol ` has an associated symbol-function. FWIW when I first saw `, , and ,@, it looked strange enough to me to open the manual, because the syntax seemed so unusual that I believed that I missed an essential part of knowledge about Elisp. At least this is what I think happened... But I agree that some people might try C-h f on any of these, and we would not all die if we would show something useful in this case. We could just say that C-f explains symbol functions and "reader macros" and the thing would still be consistent. OTOH, I think that saying anything about `pcase' there would be a bad idea. Michael. From debbugs-submit-bounces@debbugs.gnu.org Wed Jan 18 14:29:10 2017 Received: (at 25461) by debbugs.gnu.org; 18 Jan 2017 19:29:10 +0000 Received: from localhost ([127.0.0.1]:35005 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTvuv-0003nF-Dt for submit@debbugs.gnu.org; Wed, 18 Jan 2017 14:29:10 -0500 Received: from ocolin.muc.de ([193.149.48.4]:53325 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1cTvus-0003n5-Jg for 25461@debbugs.gnu.org; Wed, 18 Jan 2017 14:29:07 -0500 Received: (qmail 86176 invoked by uid 3782); 18 Jan 2017 19:29:03 -0000 Received: from acm.muc.de (p548C6FB5.dip0.t-ipconnect.de [84.140.111.181]) by colin.muc.de (tmda-ofmipd) with ESMTP; Wed, 18 Jan 2017 20:29:03 +0100 Received: (qmail 5346 invoked by uid 1000); 18 Jan 2017 19:28:48 -0000 Date: Wed, 18 Jan 2017 19:28:48 +0000 To: Michael Heerdegen Subject: Re: bug#25461: Missing doc strings for "," and ",@". Message-ID: <20170118192848.GA4108@acm.fritz.box> References: <20170116212257.GA4747@acm.fritz.box> <3w1sw11nwn.fsf@fencepost.gnu.org> <20170117195627.GA4169@acm.fritz.box> <87k29t5sqp.fsf@linux-m68k.org> <20170117204119.GC4169@acm.fritz.box> <87h94xdtvn.fsf@web.de> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <87h94xdtvn.fsf@web.de> User-Agent: Mutt/1.5.24 (2015-08-30) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -3.2 (---) X-Debbugs-Envelope-To: 25461 Cc: Andreas Schwab , 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.2 (---) Hello, Michael. On Wed, Jan 18, 2017 at 02:44:28AM +0100, Michael Heerdegen wrote: > Alan Mackenzie writes: > > I don't expect the typical novice Elisp hacker cares about such nice > > distinctions. She can get a doc string for `, so why not one for , or > > ,@? > ' and #' also "don't have a docstring". That ` "has a docstring" is > just coincidence - because the reader transforms > `expr > to > (` expr) > and the symbol ` has an associated symbol-function. I'm sure that's true. But ' is not really difficult enough to need a doc string (IMAO). Well, it didn't used to be, before it became (ab)used by pcase. #' could certainly do with one, I think. But in my patch (which I expect to post within a few minutes of this post), I have created a mechanism by which other reader macros can have doc strings added. > FWIW when I first saw `, , and ,@, it looked strange enough to me to > open the manual, because the syntax seemed so unusual that I believed > that I missed an essential part of knowledge about Elisp. At least this > is what I think happened... Yes, but unless you're a genius, you probably had to look at the manual several times before you internalised the meaning of , and ,@, with a fair bit of practice in between. During that practice, you might well have found opening the manual to have been a hassle which you could have avoided, had there been doc strings at the time. > But I agree that some people might try C-h f on any of these, and we > would not all die if we would show something useful in this case. We > could just say that C-f explains symbol functions and "reader macros" > and the thing would still be consistent. Or, not say anything at all - just do it. C-h f after all does explain named functions. That it also explains a couple of reader macros as a bonus hardly needs going on about. > OTOH, I think that saying anything about `pcase' there would be a bad > idea. I disagree. I was confused fairly badly for a long time when pcase appeared (without announcement, IIRC) and purloined the reader macros which, up till then, had had single definite functionalities. I assume other people were and will be confused by pcase usages, so it will do no harm to draw people's attention towards them. Anyhow, I've included a sentence about pcase at the end of the proposed doc string for ,. I don't think pcase uses ,@, or at least I haven't seen any such use of it. > Michael. -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Wed Jan 18 14:43:37 2017 Received: (at 25461) by debbugs.gnu.org; 18 Jan 2017 19:43:37 +0000 Received: from localhost ([127.0.0.1]:35010 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cTw8u-00049h-RB for submit@debbugs.gnu.org; Wed, 18 Jan 2017 14:43:37 -0500 Received: from ocolin.muc.de ([193.149.48.4]:25642 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1cTw8u-00049a-01 for 25461@debbugs.gnu.org; Wed, 18 Jan 2017 14:43:36 -0500 Received: (qmail 90428 invoked by uid 3782); 18 Jan 2017 19:43:34 -0000 Received: from acm.muc.de (p548C6FB5.dip0.t-ipconnect.de [84.140.111.181]) by colin.muc.de (tmda-ofmipd) with ESMTP; Wed, 18 Jan 2017 20:43:34 +0100 Received: (qmail 5400 invoked by uid 1000); 18 Jan 2017 19:43:20 -0000 Date: Wed, 18 Jan 2017 19:43:20 +0000 To: 25461@debbugs.gnu.org Subject: Re: bug#25461: [Patch]: Missing doc strings for "," and ",@". Message-ID: <20170118194320.GB4108@acm.fritz.box> References: <20170116212257.GA4747@acm.fritz.box> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.24 (2015-08-30) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -3.2 (---) X-Debbugs-Envelope-To: 25461 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.2 (---) Hello, Emacs. On Mon, Jan 16, 2017 at 09:24:02PM +0000, GNU bug Tracking System wrote: > Thank you for filing a new bug report with debbugs.gnu.org. [ .... ] Thanks for the comments, so far. Here is a patch which gives , and ,@ doc strings. It also creates a mechanism by which other reader macros (such as ' and #') can be given doc strings later. I'll just point out one thing I'm proposing changing. That is, to use princ rather than prin1 to print the name of the function. This causes, for example, backtick to be printed as ` rather than the \` we get at the moment. This might cause problems for function names which include backslashes or unprintable characters such as \n. Are there objections to me installing the patch in master? diff --git a/lisp/emacs-lisp/backquote.el b/lisp/emacs-lisp/backquote.el index 94c561c..86ca010 100644 --- a/lisp/emacs-lisp/backquote.el +++ b/lisp/emacs-lisp/backquote.el @@ -247,4 +247,33 @@ backquote-listify tail)) (t (cons 'list heads))))) + +;; Give `,' and `,@' documentation strings which can be examined by C-h f. +(put '\, 'function-documentation + "`,' signals that the next form should be evaluated and inserted. +It can occur only in `\\=`' constructs. + +For example: + +b => (ba bb bc) ; assume b has this value +\\=`(a ,b c) => (a (ba bb bc) c) ; insert the value of b + +See also `\\=`' and `,@'. + +Note that `,' is also used by the macro `pcase' and the like, +with radically different semantics.") +(put '\, 'reader-macro t) + +(put '\,@ 'function-documentation + ",@ signals that the next form should be evaluated and spliced in. +It can occur only in `\\=`' constructs. + +For example: + +b => (ba bb bc) ; assume b has this value +\\=`(a ,@b c) => (a ba bb bc c) ; splice in the value of b + +See also `\\=`' and `,'.") +(put '\,@ 'reader-macro t) + ;;; backquote.el ends here diff --git a/lisp/help-fns.el b/lisp/help-fns.el index fa16fa0..069dc3c 100644 --- a/lisp/help-fns.el +++ b/lisp/help-fns.el @@ -115,13 +115,15 @@ describe-function (if fn (format "Describe function (default %s): " fn) "Describe function: ") - #'help--symbol-completion-table #'fboundp t nil nil + #'help--symbol-completion-table + (lambda (f) (or (fboundp f) (get f 'function-documentation))) + t nil nil (and fn (symbol-name fn))))) (unless (equal val "") (setq fn (intern val))) (unless (and fn (symbolp fn)) (user-error "You didn't specify a function symbol")) - (unless (fboundp fn) + (unless (or (fboundp fn) (get fn 'function-documentation)) (user-error "Symbol's function definition is void: %s" fn)) (list fn))) @@ -144,7 +146,7 @@ describe-function (save-excursion (with-help-window (help-buffer) - (prin1 function) + (princ function) ;; Use " is " instead of a colon so that ;; it is easier to get out the function name using forward-sexp. (princ " is ") @@ -469,7 +471,8 @@ help-fns--signature (let ((fill-begin (point)) (high-usage (car high)) (high-doc (cdr high))) - (insert high-usage "\n") + (unless (get function 'reader-macro) + (insert high-usage "\n")) (fill-region fill-begin (point)) high-doc))))) @@ -565,18 +568,23 @@ describe-function-1 (or (and advised (advice--cd*r (advice--symbol-function function))) function)) - ;; Get the real definition. - (def (if (symbolp real-function) - (or (symbol-function real-function) - (signal 'void-function (list real-function))) - real-function)) - (aliased (or (symbolp def) - ;; Advised & aliased function. - (and advised (symbolp real-function) - (not (eq 'autoload (car-safe def)))) - (and (subrp def) - (not (string= (subr-name def) - (symbol-name function)))))) + ;; Get the real definition, if any. + (def (cond ((and (symbolp real-function) + (symbol-function real-function))) + ((and (symbolp real-function) + (get real-function 'function-documentation)) + nil) + ((symbolp real-function) + (signal 'void-function (list real-function))) + (t real-function))) + (aliased (and def + (or (symbolp def) + ;; Advised & aliased function. + (and advised (symbolp real-function) + (not (eq 'autoload (car-safe def)))) + (and (subrp def) + (not (string= (subr-name def) + (symbol-name function))))))) (real-def (cond ((and aliased (not (subrp def))) (let ((f real-function)) @@ -605,6 +613,8 @@ describe-function-1 ;; Print what kind of function-like object FUNCTION is. (princ (cond ((or (stringp def) (vectorp def)) "a keyboard macro") + ((get function 'reader-macro) + "a reader macro") ;; Aliases are Lisp functions, so we need to check ;; aliases before functions. (aliased -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Wed Jan 18 19:15:36 2017 Received: (at 25461) by debbugs.gnu.org; 19 Jan 2017 00:15:37 +0000 Received: from localhost ([127.0.0.1]:35076 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cU0O8-0002Ap-Nq for submit@debbugs.gnu.org; Wed, 18 Jan 2017 19:15:36 -0500 Received: from mail-io0-f181.google.com ([209.85.223.181]:35320) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cU0O5-0002Ac-QR for 25461@debbugs.gnu.org; Wed, 18 Jan 2017 19:15:35 -0500 Received: by mail-io0-f181.google.com with SMTP id j18so25679741ioe.2 for <25461@debbugs.gnu.org>; Wed, 18 Jan 2017 16:15:33 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=OKT13sf6aEaMZZ2C50IlDHUp/6S3EiHz9u45Ql/qPVo=; b=DUytC9QgoSQG3P6XglqrxaZZJQNkHKeFfOzzvYWC31udQwZDshfvb2R3Trs+5RIMe8 AjrLr2bziKzVSeQRrU4voxyC9nk63pgvCLK+U4wq/tH8P0gpR8n6VAFfNfnZ0EbnWBNr ZkPkVjrXuXlulEp+O9IbIGvN8vj6waOkT2LqAZcvP1t/GES+vBs3xdWQrSa3aP+vwHwp R6SlLXNeTbVdJr+u0sxF5YFNgwiIk6jsbqCbe9vzQDjhNlqf1F9nG+/ZHuElmndekHEL sb/TNDiJzol07nRy9g1+FXLq0YRO5d4cnpC9gpNalJ32p6Ur/js2IeYUR5xxk9KAYsO/ 5W7A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:references:date :in-reply-to:message-id:user-agent:mime-version; bh=OKT13sf6aEaMZZ2C50IlDHUp/6S3EiHz9u45Ql/qPVo=; b=hg/Nh0C/5uOSQuLJ08FLR/ruGwM5fPDvvhfPSjIKKEJBXB3WFzHd92wjNy0H9hDAB2 pyvRLp8mlcyRboKZgZRbtTrU90exxDWrK3N9S5xVFD/CPveN+SFfSm848ppMiNNaAoQr x/Sz+fQQ16NjYjotsxZOCx6jiTPw7R2ycuThbwgxChnl6Ex2fVGfmz+LIHzqRlk2/UDC x90KycWAeQWsrXHVNuOm+6R3WQAj1FqIrTqpbzj59N9anRo6+Sj88U2aMhuvjbpYVlJW hlBFvOmeiLRnIUuAGoOt96gO6pGbG8EfDXZIZ2fqqnqkSKd/gC2ds3TAH1HYQ8Etbhzh W6UQ== X-Gm-Message-State: AIkVDXJNnVnD/X1aMeYTJi1lbRww4e/FxsbAcqHT/4lqKuc4W/tNdToKCQXrR/7GPg/SiA== X-Received: by 10.107.46.160 with SMTP id u32mr6218974iou.72.1484784928083; Wed, 18 Jan 2017 16:15:28 -0800 (PST) Received: from zony ([45.2.7.65]) by smtp.googlemail.com with ESMTPSA id c9sm1909367ioc.2.2017.01.18.16.15.26 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Wed, 18 Jan 2017 16:15:27 -0800 (PST) From: npostavs@users.sourceforge.net To: Alan Mackenzie Subject: Re: bug#25461: [Patch]: Missing doc strings for "," and ",@". References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> Date: Wed, 18 Jan 2017 19:16:34 -0500 In-Reply-To: <20170118194320.GB4108@acm.fritz.box> (Alan Mackenzie's message of "Wed, 18 Jan 2017 19:43:20 +0000") Message-ID: <87r33zx5st.fsf@users.sourceforge.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.6 (/) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.6 (/) Alan Mackenzie writes: > > I'll just point out one thing I'm proposing changing. That is, to use > princ rather than prin1 to print the name of the function. This causes, > for example, backtick to be printed as > > ` > > rather than the > > \` > > we get at the moment. This might cause problems for function names > which include backslashes or unprintable characters such as \n. Perhaps only do this for symbols which have `reader-macro' set in their plist? > +;; Give `,' and `,@' documentation strings which can be examined by C-h f. > +(put '\, 'function-documentation > + "`,' signals that the next form should be evaluated and inserted. This conflates the reader macro with its particular use by the backquote macro. I think it's better to explain only the reader macro here, and link to ` and pcase for more details. > +It can occur only in `\\=`' constructs. This isn't true. From debbugs-submit-bounces@debbugs.gnu.org Wed Jan 18 21:23:42 2017 Received: (at 25461) by debbugs.gnu.org; 19 Jan 2017 02:23:42 +0000 Received: from localhost ([127.0.0.1]:35113 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cU2O6-0006tP-86 for submit@debbugs.gnu.org; Wed, 18 Jan 2017 21:23:42 -0500 Received: from mout.web.de ([212.227.15.4]:62118) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cU2O4-0006tB-Sr for 25461@debbugs.gnu.org; Wed, 18 Jan 2017 21:23:41 -0500 Received: from drachen.dragon ([92.74.161.233]) by smtp.web.de (mrweb002 [213.165.67.108]) with ESMTPSA (Nemesis) id 0Lc8n7-1c57YG29ZN-00jdgA; Thu, 19 Jan 2017 03:23:33 +0100 From: Michael Heerdegen To: Alan Mackenzie Subject: Re: bug#25461: [Patch]: Missing doc strings for "," and ",@". References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> Date: Thu, 19 Jan 2017 03:23:32 +0100 In-Reply-To: <20170118194320.GB4108@acm.fritz.box> (Alan Mackenzie's message of "Wed, 18 Jan 2017 19:43:20 +0000") Message-ID: <87lgu7dbyz.fsf@web.de> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.91 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Provags-ID: V03:K0:cVQlN6/NFdLBK3uag2JU2Gpwg112h2fl64iozuL0rjy4CeUc114 hhZR2ol4oF3M+0We1bZNKggi48wA8DCTkLQv0umQPh9SB83AJti0BcbQCqjzfpeyIvp88Zp 7fD7LY3CkKZArUWWz9gNgVrqQeukEVGjAxPQouaibi/z5q2FGaRlda6hU/1MXY5rqlq+DDW Wo+4NJJOHhZY9AcS/x2Qg== X-UI-Out-Filterresults: notjunk:1;V01:K0:x182sbDZa00=:ZrK6Nz2iHkPG3bBJYagcDi Mk2eKhPlcz0sMKepMqfYpdmmR2SE8jHb1m1aBmfXOe8vu5rgJj2zFFTe7OtkfsR7iWsUUFGoN Mytsp2DbFwcAjM6803sWbxpeJJpAftz4IdwQ9qjWx/iBloSuWfkijAUOi5/JOGc+qUu8ikx4K tUMaaXhmZdQc40gWZtprVYfKLYFo9+DlX509371HAqAJlmEmzUFl8E+0MJKOi0XyvIly217rC 00VRM8+pYNSneACMIHqnMckeakIenp2SqHCpQoQR8hol5/kKZDcBy+hkZh0PI1z6MxrDvdwvZ 2cyuaGrQ3I8LakvrNabf+yCZCebdoQHISr/SpUfKRSFrc2M5GTpDSbvx36R3eYhYoxT2YSQHb h2/VWxjLaPYeJ8FWu4mTrp7dGPefLd3w79Facfa1bv8IXJp7R47Z5mg0g3lHkaAG4OJrnvsdc 6EcI7kxvspiSyNe9MLBrgMoOJxYObqrdDAY5UpAX41N2HsC2z22VCRFjWun4D+pwhbExP4O78 CgG5Jm1pmJhv0P20xStF/FX+YpN+HgDa5S+YimmpgNhS8i7xlmQmaQv4wtDAst/wXHSV1nazh 3GCMiiaSGQTy7twkfu4tN6otHCgTv5SeTpprw2WFHC9be1QYSV2PZKTj/lhwat8NN3afHTStl d2Yc9sg24KYENgUdSPAR/HDc+U3xoMGc7SeL67mE1f/0702JRjkQho7prPWTs5pvaLenZ3Buu M/kskMuUWVgzTH7kR958pTrCJJaTCoGuij99F3vgM4po8I2l5q9ilbCwrc4lfhhU6SwIxWlF2 U1NRpKm X-Spam-Score: -3.9 (---) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.9 (---) Hi Alan, > diff --git a/lisp/emacs-lisp/backquote.el b/lisp/emacs-lisp/backquote.el > index 94c561c..86ca010 100644 > --- a/lisp/emacs-lisp/backquote.el > +++ b/lisp/emacs-lisp/backquote.el > @@ -247,4 +247,33 @@ backquote-listify > tail)) > (t (cons 'list heads))))) > > + > +;; Give `,' and `,@' documentation strings which can be examined by C-h f. > +(put '\, 'function-documentation > + "`,' signals that the next form should be evaluated and inserted. > +It can occur only in `\\=`' constructs. > + > +For example: > + > +b => (ba bb bc) ; assume b has this value > +\\=`(a ,b c) => (a (ba bb bc) c) ; insert the value of b > + > +See also `\\=`' and `,@'. I don't think this makes it easier for people to understand things. This suggests that "," has some kind of meaning per se, that it is a macro-like thing, etc, and that pcase somehow redefines it. Of course there is a logic behind pcase's usage of ` and ,. The usage of these suggests a mental model for their "meaning". But we should not describe our mental models in docstrings. That's only useful for people sharing the same model. The bindings of variables depend on context. The semantics of functions are fluent (advice, local functions). And also the "meaning" of the sexps created by ` and , depend on the context - in Lisp, the "meaning" of all sexps depends on context. (foo bar) can be a function call or a part of a let variable binding or a list or a pcase pattern. It's not different for sexps involving `. So I think we maximally should describe what the reader does with ` etc., so that people know what to search for in the manual or remember what they already had learned. + ((get function 'reader-macro) + "a reader macro") We don't have reader macros in Emacs. If we had them, we could implement ', ` etc. as reader macros. But using this term in H-f is confusing, because it is not used in the manual. Regards, Michael From debbugs-submit-bounces@debbugs.gnu.org Thu Jan 19 12:37:48 2017 Received: (at 25461) by debbugs.gnu.org; 19 Jan 2017 17:37:49 +0000 Received: from localhost ([127.0.0.1]:35734 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cUGei-0000Hn-L9 for submit@debbugs.gnu.org; Thu, 19 Jan 2017 12:37:48 -0500 Received: from ocolin.muc.de ([193.149.48.4]:24800 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1cUGeg-0000He-78 for 25461@debbugs.gnu.org; Thu, 19 Jan 2017 12:37:46 -0500 Received: (qmail 20396 invoked by uid 3782); 19 Jan 2017 17:37:43 -0000 Received: from acm.muc.de (p548C6E05.dip0.t-ipconnect.de [84.140.110.5]) by colin.muc.de (tmda-ofmipd) with ESMTP; Thu, 19 Jan 2017 18:37:43 +0100 Received: (qmail 3442 invoked by uid 1000); 19 Jan 2017 17:37:28 -0000 Date: Thu, 19 Jan 2017 17:37:28 +0000 To: npostavs@users.sourceforge.net Subject: Re: bug#25461: [Patch]: Missing doc strings for "," and ",@". Message-ID: <20170119173728.GA3397@acm.fritz.box> References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87r33zx5st.fsf@users.sourceforge.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <87r33zx5st.fsf@users.sourceforge.net> User-Agent: Mutt/1.5.24 (2015-08-30) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -3.2 (---) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.2 (---) Hello, Noam. On Wed, Jan 18, 2017 at 07:16:34PM -0500, npostavs@users.sourceforge.net wrote: > Alan Mackenzie writes: > > I'll just point out one thing I'm proposing changing. That is, to use > > princ rather than prin1 to print the name of the function. This causes, > > for example, backtick to be printed as > > ` > > rather than the > > \` > > we get at the moment. This might cause problems for function names > > which include backslashes or unprintable characters such as \n. > Perhaps only do this for symbols which have `reader-macro' set in their > plist? That sounds like a good idea. > > +;; Give `,' and `,@' documentation strings which can be examined by C-h f. > > +(put '\, 'function-documentation > > + "`,' signals that the next form should be evaluated and inserted. > This conflates the reader macro with its particular use by the backquote > macro. The use by backquote isn't "a particular" use, as though there were several equally valid uses. This use is the prime one, and up until fairly recently the only one. Other uses are subsidiary (and I make reference to the other one lower down). > I think it's better to explain only the reader macro here, and > link to ` and pcase for more details. In other words, omit the semantics from the doc string. I don't think that's a good idea: "This macro transforms `foo' into ....., but you'll have to look up ..... to see what it actually does.". We don't do that for macros like `when' and `unless', or any others I can think of, so why do it for ,? > > +It can occur only in `\\=`' constructs. > This isn't true. In what sense is it not true? I've never seen a comma used otherwise in a lisp program. What misunderstanding could it cause in a (relatively new) Lisp hacker reading it? I realise that it is possible to write (defun \, (...) ...), but that is surely of interest only to people testing Emacs. -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Thu Jan 19 12:58:20 2017 Received: (at 25461) by debbugs.gnu.org; 19 Jan 2017 17:58:20 +0000 Received: from localhost ([127.0.0.1]:35738 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cUGya-0000li-FA for submit@debbugs.gnu.org; Thu, 19 Jan 2017 12:58:20 -0500 Received: from ocolin.muc.de ([193.149.48.4]:21307 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1cUGyY-0000lY-1g for 25461@debbugs.gnu.org; Thu, 19 Jan 2017 12:58:18 -0500 Received: (qmail 24627 invoked by uid 3782); 19 Jan 2017 17:58:17 -0000 Received: from acm.muc.de (p548C6E05.dip0.t-ipconnect.de [84.140.110.5]) by colin.muc.de (tmda-ofmipd) with ESMTP; Thu, 19 Jan 2017 18:58:16 +0100 Received: (qmail 3488 invoked by uid 1000); 19 Jan 2017 17:58:01 -0000 Date: Thu, 19 Jan 2017 17:58:01 +0000 To: Michael Heerdegen Subject: Re: bug#25461: [Patch]: Missing doc strings for "," and ",@". Message-ID: <20170119175801.GB3397@acm.fritz.box> References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87lgu7dbyz.fsf@web.de> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <87lgu7dbyz.fsf@web.de> User-Agent: Mutt/1.5.24 (2015-08-30) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -3.2 (---) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.2 (---) Hello, Michael. On Thu, Jan 19, 2017 at 03:23:32AM +0100, Michael Heerdegen wrote: > Hi Alan, > > diff --git a/lisp/emacs-lisp/backquote.el b/lisp/emacs-lisp/backquote.el > > index 94c561c..86ca010 100644 > > --- a/lisp/emacs-lisp/backquote.el > > +++ b/lisp/emacs-lisp/backquote.el > > @@ -247,4 +247,33 @@ backquote-listify > > tail)) > > (t (cons 'list heads))))) > > + > > +;; Give `,' and `,@' documentation strings which can be examined by C-h f. > > +(put '\, 'function-documentation > > + "`,' signals that the next form should be evaluated and inserted. > > +It can occur only in `\\=`' constructs. > > + > > +For example: > > + > > +b => (ba bb bc) ; assume b has this value > > +\\=`(a ,b c) => (a (ba bb bc) c) ; insert the value of b > > + > > +See also `\\=`' and `,@'. > I don't think this makes it easier for people to understand things. > This suggests that "," has some kind of meaning per se, that it is a > macro-like thing, etc, and that pcase somehow redefines it. Yes. All these things are true, aren't they? > Of course there is a logic behind pcase's usage of ` and ,. The > usage of these suggests a mental model for their "meaning". But we > should not describe our mental models in docstrings. That's only useful > for people sharing the same model. I'm not sure I'm following you here. A high level description of a function necessarily involves a mental model. > The bindings of variables depend on context. The semantics of functions > are fluent (advice, local functions). And also the "meaning" of the > sexps created by ` and , depend on the context - in Lisp, the "meaning" > of all sexps depends on context. (foo bar) can be a function call or a > part of a let variable binding or a list or a pcase pattern. It's not > different for sexps involving `. ` has a specific meaning, and has had a high quality doc string for ever. , likewise has a specific meaning, but doesn't yet have a doc string. In Emacs Lisp, functions generally have well defined context-free semantics, though there are exceptions. > So I think we maximally should describe what the reader does with ` > etc., so that people know what to search for in the manual or remember > what they already had learned. We don't do that for other functions. A function's doc string should be a crisp summary of what a function _does_. A doc string which directs people to a manual, or is so confusing or unspecific that the reader is forced to open a manual, is a failed doc string. , has a definite precise function (disregarding its use in pcase for now). Have you any specific suggestions on how to improve my wording of its doc string? > + ((get function 'reader-macro) > + "a reader macro") > We don't have reader macros in Emacs. The reader performs macro-like actions. What is the correct alternative term for what the reader does with ', `, ,, #', etc.? > If we had them, we could implement ', ` etc. as reader macros. But > using this term in H-f is confusing, because it is not used in the > manual. What would be a less confusing alternative? > Regards, > Michael -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Thu Jan 19 13:10:33 2017 Received: (at 25461) by debbugs.gnu.org; 19 Jan 2017 18:10:33 +0000 Received: from localhost ([127.0.0.1]:35742 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cUHAO-000164-LP for submit@debbugs.gnu.org; Thu, 19 Jan 2017 13:10:33 -0500 Received: from mail-oi0-f66.google.com ([209.85.218.66]:35658) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cUHAM-00015n-QS for 25461@debbugs.gnu.org; Thu, 19 Jan 2017 13:10:31 -0500 Received: by mail-oi0-f66.google.com with SMTP id x84so3809456oix.2 for <25461@debbugs.gnu.org>; Thu, 19 Jan 2017 10:10:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:sender:in-reply-to:references:from:date:message-id :subject:to:cc; bh=HX0lwUuH3H7D7jD5y6C9xlVi+h0gyGPMP+e/Ab3mBIA=; b=NyY55aoTdDwXShV7Yr6NdDw1Jq01plxlXK4lTtY5dsGnHOYtuLa+wajMXMW6+Ft7KD R8SQFkvvrqNmqaCswbpSom3WIJwyPopV5EDykDflP67Ax6Rf8Wh+FC/O04bWbai3ikMi BNqllmDcTdieauPb26ln6yld01eQhs84iOxp9P8ZYg2EAFVbyTuvIOcy3XBmM7sxpog8 l09P3q6b+gZUL1lXJTi5paICS1VwB6GxSSDjx5wAUgKPOUB0n8f8bAi2ekqzqJx96g9w j1tSXsmiQNYZxMVqCiQ6tzwFOUf+FtlxTRJP7z/3g3kR3T+3RWC9inH4HYUp8pfPpPBJ R0ug== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:sender:in-reply-to:references:from :date:message-id:subject:to:cc; bh=HX0lwUuH3H7D7jD5y6C9xlVi+h0gyGPMP+e/Ab3mBIA=; b=AYnJuZs13YpHmM96EhjYG0SRoE42wG4KT2vrlHJaeffUWYk6kCmnLc1z8WhY6RAA0R TNsf0Vt0gFPYAZ78gKRIb17Bmk1w8FlZFayPrJh+7ib+jXwC/YRNDpGoR0LFTY8RTism kByxWroObfew3ubD5ZseuOQvWo8mzywXTHfwrDQbNeyXN2akxE1L14jrfi5E9tZRKz25 iQU5yJ6YcSyJ9fVRnpstxVQ4byj4v+uihtB5MxaDL9ZuxkOHQNzkBbsDzIySpDEPLho+ mQwn/hfJ4EUR7W2jlf7Cdw9OifPREPJZigAx6BiaHxNSoHU/QtYxqZSCBtC4hxg2HCAd 8/4g== X-Gm-Message-State: AIkVDXJaoZA3qwno8/VIVTEA1j5CelJFOHb5vhT+q3seTqidwscQUvjsQ0TCbzcpKOOjF/X30wHsivkWEXYxLA== X-Received: by 10.202.4.84 with SMTP id 81mr4667408oie.127.1484849425091; Thu, 19 Jan 2017 10:10:25 -0800 (PST) MIME-Version: 1.0 Received: by 10.157.21.117 with HTTP; Thu, 19 Jan 2017 10:10:24 -0800 (PST) In-Reply-To: <20170119173728.GA3397@acm.fritz.box> References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87r33zx5st.fsf@users.sourceforge.net> <20170119173728.GA3397@acm.fritz.box> From: Noam Postavsky Date: Thu, 19 Jan 2017 13:10:24 -0500 X-Google-Sender-Auth: hckrFRoyRZ5ciePJCO9Y49SDUE0 Message-ID: Subject: Re: bug#25461: [Patch]: Missing doc strings for "," and ",@". To: Alan Mackenzie Content-Type: text/plain; charset=UTF-8 X-Spam-Score: 0.5 (/) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.5 (/) On Thu, Jan 19, 2017 at 12:37 PM, Alan Mackenzie wrote: > >> > +;; Give `,' and `,@' documentation strings which can be examined by C-h f. >> > +(put '\, 'function-documentation >> > + "`,' signals that the next form should be evaluated and inserted. > >> This conflates the reader macro with its particular use by the backquote >> macro. > > The use by backquote isn't "a particular" use, as though there were > several equally valid uses. This use is the prime one, and up until > fairly recently the only one. Other uses are subsidiary (and I make > reference to the other one lower down). I agree backquote is the primary use, it's reasonable to emphasize that. > >> I think it's better to explain only the reader macro here, and >> link to ` and pcase for more details. > > In other words, omit the semantics from the doc string. I don't think > that's a good idea: "This macro transforms `foo' into ....., but you'll > have to look up ..... to see what it actually does.". We don't do that > for macros like `when' and `unless', or any others I can think of, so > why do it for ,? Because "," isn't a macro, it doesn't have any semantics. It's misleading to suggest that it does. > >> > +It can occur only in `\\=`' constructs. > >> This isn't true. > > In what sense is it not true? I've never seen a comma used otherwise in > a lisp program. What misunderstanding could it cause in a (relatively > new) Lisp hacker reading it? In the sense that it's possible to write a macro that could treat the "," differently. I don't know of any that currently do*, but that's just convention and should be documented as such. * `use-package' once handled unmatched "," as signifying eager evaluation, but it no longer does that. From debbugs-submit-bounces@debbugs.gnu.org Thu Jan 19 13:36:58 2017 Received: (at 25461) by debbugs.gnu.org; 19 Jan 2017 18:36:58 +0000 Received: from localhost ([127.0.0.1]:35748 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cUHZy-0001jT-2J for submit@debbugs.gnu.org; Thu, 19 Jan 2017 13:36:58 -0500 Received: from ocolin.muc.de ([193.149.48.4]:20204 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1cUHZv-0001jK-QX for 25461@debbugs.gnu.org; Thu, 19 Jan 2017 13:36:56 -0500 Received: (qmail 33273 invoked by uid 3782); 19 Jan 2017 18:36:54 -0000 Received: from acm.muc.de (p548C6E05.dip0.t-ipconnect.de [84.140.110.5]) by colin.muc.de (tmda-ofmipd) with ESMTP; Thu, 19 Jan 2017 19:36:54 +0100 Received: (qmail 3619 invoked by uid 1000); 19 Jan 2017 18:36:39 -0000 Date: Thu, 19 Jan 2017 18:36:39 +0000 To: Noam Postavsky Subject: Re: bug#25461: [Patch]: Missing doc strings for "," and ",@". Message-ID: <20170119183639.GC3397@acm.fritz.box> References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87r33zx5st.fsf@users.sourceforge.net> <20170119173728.GA3397@acm.fritz.box> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.24 (2015-08-30) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -3.2 (---) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.2 (---) Hello, Noam. On Thu, Jan 19, 2017 at 01:10:24PM -0500, Noam Postavsky wrote: > On Thu, Jan 19, 2017 at 12:37 PM, Alan Mackenzie wrote: > >> > +;; Give `,' and `,@' documentation strings which can be examined by C-h f. > >> > +(put '\, 'function-documentation > >> > + "`,' signals that the next form should be evaluated and inserted. [ .... ] > I agree backquote is the primary use, it's reasonable to emphasize that. > Because "," isn't a macro, it doesn't have any semantics. It's ^^^^ > misleading to suggest that it does. We could degenerate into a long silly discussion about what "have" means. , evaluates the form it precedes, and inserts it into the containing list. That's semantics enough for me. > >> > +It can occur only in `\\=`' constructs. > >> This isn't true. > > In what sense is it not true? I've never seen a comma used otherwise in > > a lisp program. What misunderstanding could it cause in a (relatively > > new) Lisp hacker reading it? > In the sense that it's possible to write a macro that could treat the > "," differently. I don't know of any that currently do*, but that's > just convention and should be documented as such. OK, I've toned down that part of the doc string. (See below.) > * `use-package' once handled unmatched "," as signifying eager > evaluation, but it no longer does that. How about this, then: "`,' signals that the next form should be evaluated and inserted. It occurs in `\\=`' constructs. For example: b => (ba bb bc) ; assume b has this value \\=`(a ,b c) => (a (ba bb bc) c) ; insert the value of b See also `\\=`' and `,@'. (Note that ``' constructs (including `,'s) sometimes have different semantics. This occurs, for example, with the macro `pcase' and other macros with similar names.) ? -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Thu Jan 19 19:12:30 2017 Received: (at 25461) by debbugs.gnu.org; 20 Jan 2017 00:12:30 +0000 Received: from localhost ([127.0.0.1]:35864 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cUMog-00089S-FW for submit@debbugs.gnu.org; Thu, 19 Jan 2017 19:12:30 -0500 Received: from mout.web.de ([217.72.192.78]:54839) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cUMod-00089D-L0 for 25461@debbugs.gnu.org; Thu, 19 Jan 2017 19:12:28 -0500 Received: from drachen.dragon ([92.74.161.233]) by smtp.web.de (mrweb103 [213.165.67.124]) with ESMTPSA (Nemesis) id 0LaCbS-1c7zoo1BR0-00m5Fl; Fri, 20 Jan 2017 01:12:20 +0100 From: Michael Heerdegen To: Alan Mackenzie Subject: Re: bug#25461: [Patch]: Missing doc strings for "," and ",@". References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87lgu7dbyz.fsf@web.de> <20170119175801.GB3397@acm.fritz.box> Date: Fri, 20 Jan 2017 01:12:18 +0100 In-Reply-To: <20170119175801.GB3397@acm.fritz.box> (Alan Mackenzie's message of "Thu, 19 Jan 2017 17:58:01 +0000") Message-ID: <877f5qbndp.fsf@web.de> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.91 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Provags-ID: V03:K0:9+qTlQpZ5vujK7A729Luodi4YO4jfNlWrx8NbMEc4y18OKsO4lj 5N3Vg9AH2tR5ph5YZ84ire70qjVTNLJlzJgtgsbZN06qjT/k9AivrAxXZrfShErOhqpemo5 A+Syb0F1VJ+LYRst36M+/yqItoKd68qq/JsZSrC/NuuxWkzsO2V1eUPxY/PE650kNdKFZmU f6lYbH/8Ll059S7GqV2xQ== X-UI-Out-Filterresults: notjunk:1;V01:K0:6NQJ2fd2XWU=:H1N1Cd5o4nA7UPcKjwLGly lq6muNa3Lopcv7lQwBFYTRrUc1v0Sh7dKoaCNNSFpORYd3Yp5VpE+MjX6v9doErA2vvhQQV72 TvgSYxs4nL0DZhZ+2LVYHKeEF++w8De/3X6EVGtEevwVMqeDscRm+KIeVlcON1pFFfXe/P3NK pXVLRo+yNg8zsSUl3ZkNDDvoJHa0GjCsqPOMx5A0CDVLs4+i/qlMeW4W0v4cCcgLzcgOZTtbl hXn32E2wp2MT4cbUyzYgmR2MbUsOTmqmis8B6W7HGEUwj+7Im1ZUQ/Dc5rlklFyWZm7/eo4Rg 9yJnWAzFBNv2auQee8NWWg2zEk0YNTRpZTcCS4JqWEByQvBC5m04Tgb/f7w+MeRjw0btOIrsV RSHNJHnek7r3vW22cB/4PcmISZK45W7RA2lIFMjm1fSVOyt5uIHUUd4R4+GL4nggdIYzTPvqS aTxI0ebk3rQyCejIRvzBjowNHmawxVvYrSe2W7wehdPgoPdkfh3PGwparoJIU4YykEIA9dqPu 2Y7wlAgdfygjAlnd7upGwvZFyyi+CSfy4OK5Br6+n40XJ/htgWyQl9UqxRFI4hvO1MQkbEHlL vq1i0z9Ir/oMgqXOosUgn1ikphRZTgggyT+TE2oTU2WDqh0ZnnxdRgbQTArmHn+7aPoRSlna1 8k6CMWRlpN+oU4Q2Zd1e5M4//1ZZnzLLNW0WqTELlnR8YZGOg7n7ejCKrlluSxBL47mptKk9M bKjOGgU/YdUr1c9Peeu7dXiqCPsbopdnohP8hxgbDssr28b+w6du7Z2zQS+n0KGmu/fxYsNb0 ZNbYVnC X-Spam-Score: -5.1 (-----) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.1 (-----) Alan Mackenzie writes: > > > +;; Give `,' and `,@' documentation strings which can be examined by C-h f. > > > +(put '\, 'function-documentation > > > + "`,' signals that the next form should be evaluated and inserted. > > > +It can occur only in `\\=`' constructs. > > > + > > > +For example: > > > + > > > +b => (ba bb bc) ; assume b has this value > > > +\\=`(a ,b c) => (a (ba bb bc) c) ; insert the value of b > > > + > > > +See also `\\=`' and `,@'. > > > I don't think this makes it easier for people to understand things. > > This suggests that "," has some kind of meaning per se, that it is a > > macro-like thing, etc, and that pcase somehow redefines it. > > Yes. All these things are true, aren't they? That `,' "signals" something is too vague to be true or false. As an explanation of things, I don't find it good, and in the generality that this sentence is speaking, I would say it's wrong. That "," can only appear inside "`" is simply wrong. That there are currently no counterexamples in our sources doesn't make a wrong sentence right. And I don't think I'm exaggerating here. Elisp is a Lisp, and Lisp is a programmable programming language. We want users to extend Emacs, and we want developers to extend (E)Lisp, because that is a big strength of the language. Formulating rules that are not true but restrict our usage of the language is bad. It is also not the case that `pcase' redefines "`". And yes, I've seen uses of "," outside of "`" in Lisp. And it's perfectly fine to use "," for anything anyone wants - like any other symbol. You doesn't seem to be confused by the fact that `rx' "(re-)uses" `and', `or' etc. What makes "`" different? The fact that it is a "reader macro"? > > Of course there is a logic behind pcase's usage of ` and ,. The > > usage of these suggests a mental model for their "meaning". But we > > should not describe our mental models in docstrings. That's only > > useful for people sharing the same model. > > I'm not sure I'm following you here. A high level description of a > function necessarily involves a mental model. Maybe. But you are describing properties of your mental model instead of properties of the language. Your mental model led you to confusion and wrong conclusions. It's not optimal to describe these things. It will confuse others. > ` has a specific meaning, and has had a high quality doc string for > ever. Because it has a `symbol-function'. > , likewise has a specific meaning, That's one part that led you to confusion. > but doesn't yet have a doc string. ... because it is undefined. > > So I think we maximally should describe what the reader does with ` > > etc., so that people know what to search for in the manual or remember > > what they already had learned. > > We don't do that for other functions. A function's doc string should be > a crisp summary of what a function _does_. A doc string which directs > people to a manual, or is so confusing or unspecific that the reader is > forced to open a manual, is a failed doc string. But that's exactly the point: "," is not a function or a macro. So how it is used is arbitrary. It's traditionally used by "`", but it's not restricted to that. There may be even more use cases in future Elisp. And that is good. > , has a definite precise function (disregarding its use in pcase for > now). Have you any specific suggestions on how to improve my wording of > its doc string? > > > + ((get function 'reader-macro) > > + "a reader macro") > > > We don't have reader macros in Emacs. > > The reader performs macro-like actions. What is the correct alternative > term for what the reader does with ', `, ,, #', etc.? The manual seems to prefer the term "reader syntax". I think we could use this term. You can say that the reader expands `X to (` X), and that "`" is a defined macro. You can say that the reader expands ,X to (\, X), and that a frequent usage is in backquote forms. We should not say that "," "does" something, because this makes no sense and leads a person reading this to false assumptions. Regards, Michael. From debbugs-submit-bounces@debbugs.gnu.org Thu Jan 19 19:25:03 2017 Received: (at 25461) by debbugs.gnu.org; 20 Jan 2017 00:25:03 +0000 Received: from localhost ([127.0.0.1]:35889 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cUN0o-0008SZ-P9 for submit@debbugs.gnu.org; Thu, 19 Jan 2017 19:25:02 -0500 Received: from mout.web.de ([212.227.15.3]:55402) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cUN0n-0008Rz-3g for 25461@debbugs.gnu.org; Thu, 19 Jan 2017 19:25:01 -0500 Received: from drachen.dragon ([92.74.161.233]) by smtp.web.de (mrweb002 [213.165.67.108]) with ESMTPSA (Nemesis) id 0Lw189-1cT4qw0nPh-017k2T; Fri, 20 Jan 2017 01:24:39 +0100 From: Michael Heerdegen To: Alan Mackenzie Subject: Re: bug#25461: [Patch]: Missing doc strings for "," and ",@". References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87r33zx5st.fsf@users.sourceforge.net> <20170119173728.GA3397@acm.fritz.box> <20170119183639.GC3397@acm.fritz.box> Date: Fri, 20 Jan 2017 01:24:37 +0100 In-Reply-To: <20170119183639.GC3397@acm.fritz.box> (Alan Mackenzie's message of "Thu, 19 Jan 2017 18:36:39 +0000") Message-ID: <8737gebmt6.fsf@web.de> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.91 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Provags-ID: V03:K0:Rk7Qvj1XiJDVaVqIubvVyiH/t99On0uu2Zri3toD8PEE4NH4NXV 2f4rMEn2B7Zjtr2Xd9uTYXyCqGjPTXh+ux/LQ1aWIMcHrcBEq9rb2oWk/9m1ghtyGawFCBc 7PyaYNIKIUOvqKgnc9S/MuB3S5gRCWnix4U76ibCxBWRyQ007auHidJ3p6mPs5QN+y0bsJc RaOrNkyjPdG5N3osjCUMQ== X-UI-Out-Filterresults: notjunk:1;V01:K0:fhsH97LY9Sc=:Qkjzkx/4wwRonJWqUFXEyA nJtykIvX8UcKYw59w5KbIZMc3Jg15rIV3UY7Qpymp+5CJpbw8hgxEuQile/18nmD4YlEC4mQt h9SoPL77e5WrO7HxUGR+dVLZ8xhdk0J6BtnfGl+rTCgP/jVwEqE2OjpqWWaSUj9Uyw5Y9uJZa Aye/LHVYlLrBw9VbyuJjbvFjNLmR26+xt7G9as+eQUvnyySc00k4Yj4PIkedfuL0Q2l15mm/w jFXkW9RYCzAxg5EUqO2Z8zMVFaAEvnGYQnoo9tyLt/dCdW6rAslGSiSzJ2x7fPtDp4KQXyWR6 vaWhlCqqTZH1dx/4bdCPtWlslljOJ7cfdcnefXCMldC9+NQ+T8nA3K+lj4ErZvQCLIVBIXl/a r4WixmP3/VCsIWPVpwQhLd3fiOojhC4pUL2ELjucESlXtoWvNnsB/nX2dUHVHLH3LzZsVPzht iD8+6zKRW03/dGkVtIwkUlyDXpSCIAlNdVhJsxY75hHyXaY6JwrBNLigBT29aso+FSf+RD4AR pH4mqPmN11nwlpDBwEnwrcoRy6FywGlHReoJPaqcbvoNPZyeZXkxivPrsQWZ9ye8ckzkz08yF 7rUwh02RcBygYUl/QCX91/SR2P7zT4cvZRUBbpGS8FjO5K3VqFUpQx/+FgEPBra3DoisXFZiL lPUXON0eF5Q04BB+oVLt558keoyH3B/8o9/DrRkdL7RLb2dKIqdp3Bf2tLc/Y5ZcUmjpZHSa1 k27K5JLJsvSYoyCB/cwTsw8ZhTAE8ORV9mGTE+D+KRM/bo9mXt9lOOVZkfXAjlfs3hFDvEWBo oq/hH0L X-Spam-Score: -3.9 (---) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org, Noam Postavsky X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.9 (---) Alan Mackenzie writes: > > I agree backquote is the primary use, it's reasonable to emphasize > > that. > > > Because "," isn't a macro, it doesn't have any semantics. It's > ^^^^ > > misleading to suggest that it does. > > We could degenerate into a long silly discussion about what "have" means. > , evaluates the form it precedes, and inserts it into the containing > list. That's semantics enough for me. It has a semantics - in the context of backquote. It's the backquote macro whose (expanded) code "inserts" something. "," may have any arbitrary semantics in another context, and per se, without context, it has no fixed semantics. > "`,' signals that the next form should be evaluated and inserted. > It occurs in `\\=`' constructs. I still find that wording misleading. Regards, Michael. From debbugs-submit-bounces@debbugs.gnu.org Fri Jan 20 11:59:15 2017 Received: (at 25461) by debbugs.gnu.org; 20 Jan 2017 16:59:16 +0000 Received: from localhost ([127.0.0.1]:36584 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cUcWx-00038o-IX for submit@debbugs.gnu.org; Fri, 20 Jan 2017 11:59:15 -0500 Received: from ocolin.muc.de ([193.149.48.4]:49856 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1cUcWu-00038f-SA for 25461@debbugs.gnu.org; Fri, 20 Jan 2017 11:59:13 -0500 Received: (qmail 68114 invoked by uid 3782); 20 Jan 2017 16:59:11 -0000 Received: from acm.muc.de (p548C7036.dip0.t-ipconnect.de [84.140.112.54]) by colin.muc.de (tmda-ofmipd) with ESMTP; Fri, 20 Jan 2017 17:59:11 +0100 Received: (qmail 3502 invoked by uid 1000); 20 Jan 2017 16:58:56 -0000 Date: Fri, 20 Jan 2017 16:58:56 +0000 To: Michael Heerdegen Subject: Re: bug#25461: [Patch]: Missing doc strings for "," and ",@". Message-ID: <20170120165856.GA3384@acm.fritz.box> References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87lgu7dbyz.fsf@web.de> <20170119175801.GB3397@acm.fritz.box> <877f5qbndp.fsf@web.de> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <877f5qbndp.fsf@web.de> User-Agent: Mutt/1.5.24 (2015-08-30) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -3.2 (---) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.2 (---) Hello, Michael. On Fri, Jan 20, 2017 at 00:12:18 UTC, Michael Heerdegen wrote: > Alan Mackenzie writes: > > > > +;; Give `,' and `,@' documentation strings which can be examined by C-h f. > > > > +(put '\, 'function-documentation > > > > + "`,' signals that the next form should be evaluated and inserted. > > > > +It can occur only in `\\=`' constructs. > > > > + > > > > +For example: > > > > + > > > > +b => (ba bb bc) ; assume b has this value > > > > +\\=`(a ,b c) => (a (ba bb bc) c) ; insert the value of b > > > > + > > > > +See also `\\=`' and `,@'. > > > I don't think this makes it easier for people to understand things. > > > This suggests that "," has some kind of meaning per se, that it is a > > > macro-like thing, etc, and that pcase somehow redefines it. > > Yes. All these things are true, aren't they? > That `,' "signals" something is too vague to be true or false. As an > explanation of things, I don't find it good, and in the generality that > this sentence is speaking, I would say it's wrong. OK, I'll accept that. I can't see where it's wrong, though. I've changed it to say "causes" rather than "signal". (See below.) > That "," can only appear inside "`" is simply wrong. That's poor wording on my part. What I really meant was that for , to have the effect described, it must be in a ` construct. I've amended this bit too (see below). [ .... ] > It is also not the case that `pcase' redefines "`". pcase causes ` to be expanded by the macro \`--pcase-macroexpander in place of the macro \`. What is that if it is not pcase redefining `? > And yes, I've seen uses of "," outside of "`" in Lisp. And it's > perfectly fine to use "," for anything anyone wants - like any other > symbol. I disagree with you, here. Using standard Elisp symbols to mean something different is a recipe for confusion. I don't think it is in any way fine to use `if', `and', `car', .... for non standard purposes. I also don't think it's OK to do the same with ` or ,. > You don't seem to be confused by the fact that `rx' "(re-)uses" `and', > `or' etc. What makes "`" different? The fact that it is a "reader > macro"? I wasn't aware of rx. I don't think it was good to reuse `and' the way it does, but (subjectively) I don't think it will have caused all that much confusion. > > > Of course there is a logic behind pcase's usage of ` and ,. The > > > usage of these suggests a mental model for their "meaning". But we > > > should not describe our mental models in docstrings. That's only > > > useful for people sharing the same model. > > I'm not sure I'm following you here. A high level description of a > > function necessarily involves a mental model. > Maybe. But you are describing properties of your mental model instead > of properties of the language. Your mental model led you to confusion > and wrong conclusions. I disagree with you, here. I'm describing the simple straighforward normal effect of ,. I don't understand why you're making such a big deal out of it. > It's not optimal to describe these things. It will confuse others. I disagree with you here, too. , and ,@ have a simply stated meaning in the typical case, far simpler than you're making it out to be. > > ` has a specific meaning, and has had a high quality doc string for > > ever. > Because it has a `symbol-function'. > > , likewise has a specific meaning, > That's one part that led you to confusion. > > but doesn't yet have a doc string. > ... because it is undefined. It is defined. I intend that definition to be in a doc string. > > > So I think we maximally should describe what the reader does with ` > > > etc., so that people know what to search for in the manual or remember > > > what they already had learned. > > We don't do that for other functions. A function's doc string should be > > a crisp summary of what a function _does_. A doc string which directs > > people to a manual, or is so confusing or unspecific that the reader is > > forced to open a manual, is a failed doc string. > But that's exactly the point: "," is not a function or a macro. No, but it needs a doc string. > So how it is used is arbitrary. If that were the case, Emacs wouldn't even build. ,'s use is no more arbitrary than any other symbol in Lisp. > It's traditionally used by "`", but it's not restricted to that. > There may be even more use cases in future Elisp. And that is good. I disagree with that last sentiment. > > , has a definite precise function (disregarding its use in pcase for > > now). Have you any specific suggestions on how to improve my wording of > > its doc string? > > > + ((get function 'reader-macro) > > > + "a reader macro") > > > We don't have reader macros in Emacs. > > The reader performs macro-like actions. What is the correct alternative > > term for what the reader does with ', `, ,, #', etc.? > The manual seems to prefer the term "reader syntax". I think we could > use this term. No, that won't do. , has semantics as well as syntax. > You can say that the reader expands `X to (` X), and that "`" is a > defined macro. You can say that the reader expands ,X to (\, X), and > that a frequent usage is in backquote forms. That is describing the internal mechanism of , rather than the result. It would be utterly useless and confusing for the people who need to consult the meaning of , and ,@, namely new Elisp hackers. > We should not say that "," "does" something, because this makes no > sense and leads a person reading this to false assumptions. It will enable them to understand code they are reading, and to start writing ` constructs themselves. Here is the latest proposed version of the doc string for ,, incorporating some of the comments you've made. "`,' causes the next form to be evaluated and inserted. It occurs in `\\=`' constructs. For example: b => (ba bb bc) ; assume b has this value \\=`(a ,b c) => (a (ba bb bc) c) ; insert the value of b See also `\\=`' and `,@'. (Note that ``' constructs (including `,'s) sometimes have different semantics. This occurs, for example, with the macro `pcase' and other macros with similar names.") > Regards, > Michael. -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Fri Jan 20 21:26:18 2017 Received: (at 25461) by debbugs.gnu.org; 21 Jan 2017 02:26:18 +0000 Received: from localhost ([127.0.0.1]:36781 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cUlNh-0004Vr-VW for submit@debbugs.gnu.org; Fri, 20 Jan 2017 21:26:18 -0500 Received: from mout.web.de ([212.227.15.14]:59112) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cUlNg-0004Vd-5E for 25461@debbugs.gnu.org; Fri, 20 Jan 2017 21:26:16 -0500 Received: from drachen.dragon ([92.74.161.233]) by smtp.web.de (mrweb001 [213.165.67.108]) with ESMTPSA (Nemesis) id 0MMnD5-1ccCxM0SqN-008X4d; Sat, 21 Jan 2017 03:26:07 +0100 From: Michael Heerdegen To: Alan Mackenzie Subject: Re: bug#25461: [Patch]: Missing doc strings for "," and ",@". References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87lgu7dbyz.fsf@web.de> <20170119175801.GB3397@acm.fritz.box> <877f5qbndp.fsf@web.de> <20170120165856.GA3384@acm.fritz.box> Date: Sat, 21 Jan 2017 03:26:06 +0100 In-Reply-To: <20170120165856.GA3384@acm.fritz.box> (Alan Mackenzie's message of "Fri, 20 Jan 2017 16:58:56 +0000") Message-ID: <87y3y5cfnl.fsf@web.de> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.91 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Provags-ID: V03:K0:oCSs5opsClECWbivuzWgoRcYVjmWBJqLQBkpBbGI0CyTmkPIRXK TuILUinpkN1yZzySqYP7VQXZmQmg9Fc6uwhzYMTvzm1EFzpaFl+NbeCXjOCskKcw0pWLUJ9 Ou+k3vY+jELahMXgnQOF7vAXUxyus/Lc9MXZOmIb95mVjqqAbmIXPbabdqeegopImkEdSiL I836LagQT5hPV+jZm2hqQ== X-UI-Out-Filterresults: notjunk:1;V01:K0:ZRp0qZRHsZ8=:rzlcPn8RQWGwP+BNV/c9MJ X2KVATPYiS2V6b37oT5xHYtWAJG9fesjE7gg4shXzbYCiZV8Gz4NRO9i8NlWfXpd1vAdZaZYt xOG6T3y3+devM0vuOh5pUudEGp1VkX3k24xZWfIS9/dO94LidRgc/g+4zJ/eJbgbT82BehuuH M9oLoB8JQ5vhiD8F3FZxFSQj3yzqd96/2Rb6kE+SJWh+4Xsq3szNd10poasmQF7c/9UkfhvK4 ZEV+l8FCV8CP6BFyZfYRGMflUzc33HJ2v6p1Y0OrxmzQ8u4srGD2dUDqdJaiTZVLAThdQheoC dO+GQK2ES4o0sEQpOX20u4Jj8WZtnPUAR1Jge8l88QIYg/Ex7ynRJ3bWJ5z5InwdQhU+ca1YL XXW50R/ofSkbSzaNXNmhpW6jDkIPwRW5ULlX0huYilK8vSQD+41NPWqxYxxpExRv9Dzm8/mPj s9s/afbS38C8JaWMSp87Ymn+QsKRnQ6ArLwXN4LwuwMEo0xV0t0h4TBJFXTjl6f3eghfCSWHl a6WzUZ9M+FM0buxrzqe9DfRIB5NVC3z9gn/5nq6NFmZJKVa4oyVWeKYq+DGVi0ebfOaoZyQm8 1SyV+8ASfecgEc+E0bE/+RMmeEv1zOGomtiDg2+4+DSRMTFion3alWy/Qges5XkQUO+PQXcbF MJAKmDvZ9zsneVo31/D8mKqZObxKVuYOL6ZxZtX/h6z58ql12Ecy9slpEamzKwBUTwk8/arZz 6y7Crb9BiEHMXKT0sS8oYtl9XeS3hFonZC6+q0K2hfBWemi5xYyRO2FwiSs2wLnU4JFZTpnwl LZwh8tH X-Spam-Score: -5.1 (-----) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.1 (-----) Hello Alan, > pcase causes ` to be expanded by the macro \`--pcase-macroexpander in > place of the macro \`. What is that if it is not pcase redefining `? pcase patterns are not evaluated normally. When ` is used in patterns, the definition of ` is not consulted. Just like in (let ((l '(\` 1 2))) (when (eq (car l) '\`) (apply #'+ (cdr l)))) ==> 3 Is that code redefining "`"? You mean something different with the term "definition": a complete summarisation of the semantics of something in any context. Something like that doesn't exist in a programmable extensible language like Lisp. > I disagree with you, here. I'm describing the simple straighforward > normal effect of ,. I don't understand why you're making such a big > deal out of it. I don't want that we change the docs to the worse. > > ... because it is undefined. > > It is defined. I intend that definition to be in a doc string. It is implicitly given a meaning by the implementation of "`". That's why it's documented in the documentation of "`". For the same reason that there is no separate documentation for :group just because it has a meaning in defcustom, or there is no mentioning in the docstring that the symbol `error' has a different meaning as car of a list that is an error handler in condition-case, or that car has a different meaning in (setf (car something) ...) or... All these examples appear in symbolic expressions (i.e. lists) that are not evaluated normally. Like in the tiny example above. If we try to mention what a symbol potentially could mean in any sexp that is not evaluated normally in this symbol's docstring, our documentation would become very messy, because lists that are not evaluated normally are very common in Lisp. That's why we normally collect this information in the documentation of the functions/macros that implement this meaning. This is not a problem because it's easy to look at the context and consult the documentation of the surrounding form. > > So how it is used is arbitrary. > > If that were the case, Emacs wouldn't even build. The introduction of pcase didn't cause Emacs not to build. Simply because it didn't change the definition of `. > > We should not say that "," "does" something, because this makes no > > sense and leads a person reading this to false assumptions. > > It will enable them to understand code they are reading, and to start > writing ` constructs themselves. But it won't really enable them to understand how it works. > Here is the latest proposed version of the doc string for ,, > incorporating some of the comments you've made. > > > "`,' causes the next form to be evaluated and inserted. > It occurs in `\\=`' constructs. > > For example: > > b => (ba bb bc) ; assume b has this value > \\=`(a ,b c) => (a (ba bb bc) c) ; insert the value of b > > See also `\\=`' and `,@'. > > (Note that ``' constructs (including `,'s) sometimes have different > semantics. This occurs, for example, with the macro `pcase' and other > macros with similar names.") I still think it's an error to describe a global semantics that as such isn't existent. I would rather prefer a wording (sorry if it's poor, my English is not so super...) like ", before a symbolic expression X forms a read syntax that the Lisp reader expands like ,X -> (, X). Such symbolic expressions have a special meaning in backquote forms (see ``') and in `pcase' patterns - see there." I think it would be ok to append your backquote example above. Regards, Michael. From debbugs-submit-bounces@debbugs.gnu.org Sat Jan 21 10:57:10 2017 Received: (at 25461) by debbugs.gnu.org; 21 Jan 2017 15:57:10 +0000 Received: from localhost ([127.0.0.1]:37646 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cUy2Q-0003TO-8D for submit@debbugs.gnu.org; Sat, 21 Jan 2017 10:57:10 -0500 Received: from ocolin.muc.de ([193.149.48.4]:34875 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1cUy2M-0003TC-Oj for 25461@debbugs.gnu.org; Sat, 21 Jan 2017 10:57:07 -0500 Received: (qmail 14755 invoked by uid 3782); 21 Jan 2017 15:57:05 -0000 Received: from acm.muc.de (p548C61DB.dip0.t-ipconnect.de [84.140.97.219]) by colin.muc.de (tmda-ofmipd) with ESMTP; Sat, 21 Jan 2017 16:57:05 +0100 Received: (qmail 16713 invoked by uid 1000); 21 Jan 2017 15:56:51 -0000 Date: Sat, 21 Jan 2017 15:56:51 +0000 To: Michael Heerdegen Subject: Re: bug#25461: [Patch]: Missing doc strings for "," and ",@". Message-ID: <20170121155651.GB5394@acm> References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87lgu7dbyz.fsf@web.de> <20170119175801.GB3397@acm.fritz.box> <877f5qbndp.fsf@web.de> <20170120165856.GA3384@acm.fritz.box> <87y3y5cfnl.fsf@web.de> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <87y3y5cfnl.fsf@web.de> User-Agent: Mutt/1.7.2 (2016-11-26) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -3.2 (---) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.2 (---) Hello, Michael. On Sat, Jan 21, 2017 at 03:26:06 +0100, Michael Heerdegen wrote: > Hello Alan, [ .... ] > I don't want that we change the docs to the worse. I somehow don't think you'll be happy with any modifications I make to the proposed doc strings which leaves their basic structure unchanged. How about starting on a different tack. Would you accept , and ,@ having doc strings, with the entirety of these being: [for ,]: See ``' (and also `pcase') for the details of `,'. [for ,@]: See ``' for the details of `,@'. ? [ .... ] > It [ , ] is implicitly given a meaning by the implementation of "`". > That's why it's documented in the documentation of "`". For the same > reason that there is no separate documentation for :group just because > it has a meaning in defcustom, or there is no mentioning in the > docstring that the symbol `error' has a different meaning as car of a > list that is an error handler in condition-case, or that car has a > different meaning in (setf (car something) ...) or... > All these examples appear in symbolic expressions (i.e. lists) that are > not evaluated normally. Like in the tiny example above. If we try to > mention what a symbol potentially could mean in any sexp that is not > evaluated normally in this symbol's docstring, our documentation would > become very messy, because lists that are not evaluated normally are > very common in Lisp. That's why we normally collect this information in > the documentation of the functions/macros that implement this meaning. > This is not a problem because it's easy to look at the context and > consult the documentation of the surrounding form. , and ,@ are different: it is not obvious to the unexperienced what "sexp" they belong to in something like `(if ,cond (progn ,@body)) . How is a beginner supposed to connect up the ,@ in that example with the ` which doesn't directly enclose or otherwise connect with it? [ .... ] (I'll address your points that I've snipped if they become relevant again.) > Regards, > Michael. -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Sat Jan 21 15:47:09 2017 Received: (at 25461) by debbugs.gnu.org; 21 Jan 2017 20:47:09 +0000 Received: from localhost ([127.0.0.1]:37765 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cV2Z2-0001p9-PA for submit@debbugs.gnu.org; Sat, 21 Jan 2017 15:47:08 -0500 Received: from ocolin.muc.de ([193.149.48.4]:37066 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1cV2Z1-0001oz-9O for 25461@debbugs.gnu.org; Sat, 21 Jan 2017 15:47:07 -0500 Received: (qmail 84719 invoked by uid 3782); 21 Jan 2017 20:47:04 -0000 Received: from acm.muc.de (p548C61DB.dip0.t-ipconnect.de [84.140.97.219]) by colin.muc.de (tmda-ofmipd) with ESMTP; Sat, 21 Jan 2017 21:47:04 +0100 Received: (qmail 28110 invoked by uid 1000); 21 Jan 2017 20:46:48 -0000 Date: Sat, 21 Jan 2017 20:46:48 +0000 To: Michael Heerdegen Subject: Re: bug#25461: [Patch #2]: Missing doc strings for "," and ",@". Message-ID: <20170121204648.GA21091@acm> References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87lgu7dbyz.fsf@web.de> <20170119175801.GB3397@acm.fritz.box> <877f5qbndp.fsf@web.de> <20170120165856.GA3384@acm.fritz.box> <87y3y5cfnl.fsf@web.de> <20170121155651.GB5394@acm> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <20170121155651.GB5394@acm> User-Agent: Mutt/1.7.2 (2016-11-26) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -3.2 (---) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.2 (---) Hello again, Michael. On Sat, Jan 21, 2017 at 15:56:51 +0000, Alan Mackenzie wrote: > Hello, Michael. > On Sat, Jan 21, 2017 at 03:26:06 +0100, Michael Heerdegen wrote: [ .... ] > How about starting on a different tack. Would you accept , and ,@ > having doc strings, with the entirety of these being: > [for ,]: > See ``' (and also `pcase') for the details of `,'. > [for ,@]: > See ``' for the details of `,@'. > ? I've hacked all this together. What used to be called a "reader macro" is now a "reader construct". I've made the ``' a clickable link, too. Is there anything else you think needs changing? diff --git a/lisp/emacs-lisp/backquote.el b/lisp/emacs-lisp/backquote.el index 94c561c..acc3fa4 100644 --- a/lisp/emacs-lisp/backquote.el +++ b/lisp/emacs-lisp/backquote.el @@ -247,4 +247,14 @@ backquote-listify tail)) (t (cons 'list heads))))) + +;; Give `,' and `,@' documentation strings which can be examined by C-h f. +(put '\, 'function-documentation + "See `\\=`' (also `pcase') for the details of `,'.") +(put '\, 'reader-construct t) + +(put '\,@ 'function-documentation + "See `\\=`' or `,' for the details of `,@'.") +(put '\,@ 'reader-construct t) + ;;; backquote.el ends here diff --git a/lisp/help-fns.el b/lisp/help-fns.el index fa16fa0..edbcd90 100644 --- a/lisp/help-fns.el +++ b/lisp/help-fns.el @@ -115,13 +115,15 @@ describe-function (if fn (format "Describe function (default %s): " fn) "Describe function: ") - #'help--symbol-completion-table #'fboundp t nil nil + #'help--symbol-completion-table + (lambda (f) (or (fboundp f) (get f 'function-documentation))) + t nil nil (and fn (symbol-name fn))))) (unless (equal val "") (setq fn (intern val))) (unless (and fn (symbolp fn)) (user-error "You didn't specify a function symbol")) - (unless (fboundp fn) + (unless (or (fboundp fn) (get fn 'function-documentation)) (user-error "Symbol's function definition is void: %s" fn)) (list fn))) @@ -144,7 +146,9 @@ describe-function (save-excursion (with-help-window (help-buffer) - (prin1 function) + (if (get function 'reader-construct) + (princ function) + (prin1 function)) ;; Use " is " instead of a colon so that ;; it is easier to get out the function name using forward-sexp. (princ " is ") @@ -469,7 +473,8 @@ help-fns--signature (let ((fill-begin (point)) (high-usage (car high)) (high-doc (cdr high))) - (insert high-usage "\n") + (unless (get function 'reader-construct) + (insert high-usage "\n")) (fill-region fill-begin (point)) high-doc))))) @@ -565,18 +570,21 @@ describe-function-1 (or (and advised (advice--cd*r (advice--symbol-function function))) function)) - ;; Get the real definition. + ;; Get the real definition, if any. (def (if (symbolp real-function) - (or (symbol-function real-function) - (signal 'void-function (list real-function))) + (cond ((symbol-function real-function)) + ((get real-function 'function-documentation) + nil) + (t (signal 'void-function (list real-function)))) real-function)) - (aliased (or (symbolp def) - ;; Advised & aliased function. - (and advised (symbolp real-function) - (not (eq 'autoload (car-safe def)))) - (and (subrp def) - (not (string= (subr-name def) - (symbol-name function)))))) + (aliased (and def + (or (symbolp def) + ;; Advised & aliased function. + (and advised (symbolp real-function) + (not (eq 'autoload (car-safe def)))) + (and (subrp def) + (not (string= (subr-name def) + (symbol-name function))))))) (real-def (cond ((and aliased (not (subrp def))) (let ((f real-function)) @@ -605,6 +613,8 @@ describe-function-1 ;; Print what kind of function-like object FUNCTION is. (princ (cond ((or (stringp def) (vectorp def)) "a keyboard macro") + ((get function 'reader-construct) + "a reader construct") ;; Aliases are Lisp functions, so we need to check ;; aliases before functions. (aliased diff --git a/lisp/help-mode.el b/lisp/help-mode.el index a8d7294..3fb793e 100644 --- a/lisp/help-mode.el +++ b/lisp/help-mode.el @@ -328,7 +328,7 @@ help-xref-symbol-regexp "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)" "[ \t\n]+\\)?" ;; Note starting with word-syntax character: - "['`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\)['’]")) + "['`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\|`\\)['’]")) "Regexp matching doc string references to symbols. The words preceding the quoted symbol can be used in doc strings to -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 23 14:09:47 2017 Received: (at 25461-done) by debbugs.gnu.org; 23 Jan 2017 19:09:47 +0000 Received: from localhost ([127.0.0.1]:39403 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cVjzv-0006My-2d for submit@debbugs.gnu.org; Mon, 23 Jan 2017 14:09:47 -0500 Received: from ocolin.muc.de ([193.149.48.4]:60447 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1cVjzt-0006Mp-A5 for 25461-done@debbugs.gnu.org; Mon, 23 Jan 2017 14:09:45 -0500 Received: (qmail 360 invoked by uid 3782); 23 Jan 2017 19:09:43 -0000 Received: from acm.muc.de (p548C72B0.dip0.t-ipconnect.de [84.140.114.176]) by colin.muc.de (tmda-ofmipd) with ESMTP; Mon, 23 Jan 2017 20:09:42 +0100 Received: (qmail 4432 invoked by uid 1000); 23 Jan 2017 19:09:27 -0000 Date: Mon, 23 Jan 2017 19:09:27 +0000 To: 25461-done@debbugs.gnu.org Subject: Re: bug#25461: [Patch]: Missing doc strings for "," and ",@". Message-ID: <20170123190927.GA4397@acm> References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87lgu7dbyz.fsf@web.de> <20170119175801.GB3397@acm.fritz.box> <877f5qbndp.fsf@web.de> <20170120165856.GA3384@acm.fritz.box> <87y3y5cfnl.fsf@web.de> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <87y3y5cfnl.fsf@web.de> User-Agent: Mutt/1.7.2 (2016-11-26) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -3.2 (---) X-Debbugs-Envelope-To: 25461-done Cc: Michael Heerdegen X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.2 (---) Bug fixed. -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 23 20:59:07 2017 Received: (at 25461) by debbugs.gnu.org; 24 Jan 2017 01:59:07 +0000 Received: from localhost ([127.0.0.1]:39585 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cVqO2-0005mu-Rp for submit@debbugs.gnu.org; Mon, 23 Jan 2017 20:59:07 -0500 Received: from mout.web.de ([212.227.17.11]:62529) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cVqO0-0005mP-BF for 25461@debbugs.gnu.org; Mon, 23 Jan 2017 20:59:04 -0500 Received: from drachen.dragon ([88.67.99.137]) by smtp.web.de (mrweb102 [213.165.67.124]) with ESMTPSA (Nemesis) id 0LwqFo-1cTX1D3hxQ-016QZy; Tue, 24 Jan 2017 02:58:56 +0100 From: Michael Heerdegen To: Alan Mackenzie Subject: Re: bug#25461: [Patch #2]: Missing doc strings for "," and ",@". References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87lgu7dbyz.fsf@web.de> <20170119175801.GB3397@acm.fritz.box> <877f5qbndp.fsf@web.de> <20170120165856.GA3384@acm.fritz.box> <87y3y5cfnl.fsf@web.de> <20170121155651.GB5394@acm> <20170121204648.GA21091@acm> Date: Tue, 24 Jan 2017 02:58:54 +0100 In-Reply-To: <20170121204648.GA21091@acm> (Alan Mackenzie's message of "Sat, 21 Jan 2017 20:46:48 +0000") Message-ID: <874m0pqkv5.fsf@web.de> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Provags-ID: V03:K0:OBkbWtGBQGz6h4ncI+xHLIffMS3P1Z95Ta7n1C3kvokOPK7cnAs BrzR24iK/s9AJrzZY4Fefv4GkvYdnlNZV+taQqtSOSA7dN+wtX5H5eU26DJPUMLiom38DnJ pvTF1e+QSWTJ0PbqFF/15iyeM9O8R0VD0pddssO4/f23LEro4yX0g+RSyjHTTUnCa8fw+e5 wECSJs+Don1rpFUQDZd7A== X-UI-Out-Filterresults: notjunk:1;V01:K0:iTvjQk0Rqh4=:yjVvQlLVyue8XHwYGtJiyr 8nR46t7zS9XKg1v8IM459PM4zx8vj4DV4uJ7yUfgk5Pk3Pvu7NOVySx3JGkkXFdYKhj6XknFa cf7VZnsBjBCgb8YDczVaefa9BJErDmHtVypYsm85/83DZ6qXLhYq/rbng53FCbijSJP6FM6bK BynsBGpMPJbodgmRdoQjL5ICI1Y4oW3i58lvKEqBNMj6bbn5KjqScfL4yQpIWMt6IApreFJK1 KXayQ6QhjmBHbR5lKqGuiVcjzRIixZIBG1AGHXsZtPUMaIJR3In1/m8P22p3QAEbiWf+moT7c 7WST7vdgrGh7up5OPWusWgw17VyT2XIBx+pVTqmu79Cr8FfEomTaifn4xPipc2nldrIEcW70/ ItNFnPdNewVBIIflnzrmF13dj1BsxqwaqulVdztDzK9ZTlvLFtKB9z1LHghAsS0sBym3O8s1Q amhilkCoSXcHKM3dkvP+d4oiZoHdaemPcevOw1vQYOCFJpgtqwfrTUmEqYJSsBeJIEM/TgZYs fvShmTzCnYukRgZZd7bex6PNlXRJMLZ6a9ifbsg0zEU/9jrAI7U4jYdDDWypR18eYT3VNcnwZ Xf8T0VGjgR+wPRZf+z1cM5C3hStr8/7f9uc28ogruJ5Ulst1QDGOpBJ46gXrQMkfKOkGzg5jz 8no6dc5rxP14fGfUgguYUuL+oDJLhKUpIk8fVveLevsimgs5dJgEjnw/VVnylwS8xWPrrl7Cj q7U3eg2xRVqXl5CKaPYvgmZoJL0mqagQFC61ZZSppQ4HC8bmjd+ijNMhSN6NRX/KzmrJnsX+v D/YQ4ep X-Spam-Score: -3.9 (---) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.9 (---) Alan Mackenzie writes: > I've hacked all this together. What used to be called a "reader > macro" is now a "reader construct". Well, I liked my suggested wording more, but that's not a big surprise I guess. I wonder what others think? > diff --git a/lisp/emacs-lisp/backquote.el b/lisp/emacs-lisp/backquote.el > [...] I see that you already installed you suggested patch. After a short test it seems to work as intended (FWIW, it doesn't work with Helm, I guess because Helm doesn't consult a completion table but reimplements the whole C-h f thing by itself). Regards, Michael. From debbugs-submit-bounces@debbugs.gnu.org Mon Jan 23 23:00:38 2017 Received: (at 25461) by debbugs.gnu.org; 24 Jan 2017 04:00:38 +0000 Received: from localhost ([127.0.0.1]:39622 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cVsHd-00009o-Pa for submit@debbugs.gnu.org; Mon, 23 Jan 2017 23:00:37 -0500 Received: from mail-it0-f51.google.com ([209.85.214.51]:38477) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cVsHb-00009a-2x for 25461@debbugs.gnu.org; Mon, 23 Jan 2017 23:00:36 -0500 Received: by mail-it0-f51.google.com with SMTP id c7so81546210itd.1 for <25461@debbugs.gnu.org>; Mon, 23 Jan 2017 20:00:34 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=t4E5EK/KRI4s2xryLfw0uFvLPQRoLwgoOoeHmioEY7g=; b=VKe+zV7nndNtCuxrOld0HwBLFck3Gw03tUQaY2iGj5J1FGYRssFzmoyX/kX1RzUn/8 Tfo8SjA/3E8wepV586NMPR2HSuMpV57X/TifW7EexeCftPXCJ0Gdmvfz7sok4gS5JXpq q41rIjqggd3XmzdfD9aFj2tfTppZK39q3coooxI3Fd5f8WJclrxr8mE3BqzGPZg7ULbk 1nEmvhDBMMayJnxaEQ3lwDK6SQZEmj0r3OBV/M2z0DANDYDJbA0VRLq6jgSIAZ+GCBe5 2JcpiuyyKkeZn4ADGMTkYybLb/nmLv5TGt8OiAiHPaMJ4Q+t4UyQlXjZ4nHXn09+Z5sD Gnzg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:references:date :in-reply-to:message-id:user-agent:mime-version; bh=t4E5EK/KRI4s2xryLfw0uFvLPQRoLwgoOoeHmioEY7g=; b=toYqBZNSG2yg6M49CMPCpbBXz9Uk+lQ0NphI02x3AK06miqSf25kHkSMC2E9hEbH45 qPgqgX8u+hPO3zE5zq2uVNYObmWvdKnANJFM0+FKADg2a3VWknZV+C7S4Sv3CKdxFDrV oN/MfpwPFLJLCSa2rALDqIDUupncjN3LAfbu+Utdhri1/G4bx77MGn3Cwq9mVjVp8bEb MtCttKpcy7U5daj99VoroQ1LSkPfOHTDVaB+5US7JFGkYgCzuleNkRRxgN+eJtE+3dgF WB7b2JXynm9uu1dPmOBvC16MdAOVgq9TtjtqqHWG5lPRQnrjOOHaBzoMS+3P98sIcV5U 4EeQ== X-Gm-Message-State: AIkVDXJhfStjzNLb+Ve6d7gQsK1hXUuPp5vnvQcgSRXiWnPDrMgeXNTqNAK3s/G6qGyv4Q== X-Received: by 10.36.64.70 with SMTP id n67mr9557502ita.21.1485230429575; Mon, 23 Jan 2017 20:00:29 -0800 (PST) Received: from zony ([45.2.7.65]) by smtp.googlemail.com with ESMTPSA id p20sm10594473itc.2.2017.01.23.20.00.28 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Mon, 23 Jan 2017 20:00:29 -0800 (PST) From: npostavs@users.sourceforge.net To: Alan Mackenzie Subject: Re: bug#25461: [Patch #2]: Missing doc strings for "," and ",@". References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87lgu7dbyz.fsf@web.de> <20170119175801.GB3397@acm.fritz.box> <877f5qbndp.fsf@web.de> <20170120165856.GA3384@acm.fritz.box> <87y3y5cfnl.fsf@web.de> <20170121155651.GB5394@acm> <20170121204648.GA21091@acm> Date: Mon, 23 Jan 2017 23:01:36 -0500 In-Reply-To: <20170121204648.GA21091@acm> (Alan Mackenzie's message of "Sat, 21 Jan 2017 20:46:48 +0000") Message-ID: <871svtumvz.fsf@users.sourceforge.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -0.2 (/) X-Debbugs-Envelope-To: 25461 Cc: Michael Heerdegen , 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.2 (/) Alan Mackenzie writes: > > I've hacked all this together. What used to be called a "reader macro" > is now a "reader construct". I think "read syntax" is better just because the manual already uses that term. > +;; Give `,' and `,@' documentation strings which can be examined by C-h f. > +(put '\, 'function-documentation > + "See `\\=`' (also `pcase') for the details of `,'.") > +(put '\, 'reader-construct t) > + > +(put '\,@ 'function-documentation > + "See `\\=`' or `,' for the details of `,@'.") Linking from ",@" to "," seems a bit unhelpful, since "," hardly says anything and just links to "`". From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 24 14:39:39 2017 Received: (at 25461) by debbugs.gnu.org; 24 Jan 2017 19:39:39 +0000 Received: from localhost ([127.0.0.1]:40706 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cW6wM-0006vH-Tm for submit@debbugs.gnu.org; Tue, 24 Jan 2017 14:39:39 -0500 Received: from ocolin.muc.de ([193.149.48.4]:38859 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1cW6wL-0006v8-Eg for 25461@debbugs.gnu.org; Tue, 24 Jan 2017 14:39:38 -0500 Received: (qmail 62289 invoked by uid 3782); 24 Jan 2017 19:39:34 -0000 Received: from acm.muc.de (p548C7CD0.dip0.t-ipconnect.de [84.140.124.208]) by colin.muc.de (tmda-ofmipd) with ESMTP; Tue, 24 Jan 2017 20:39:33 +0100 Received: (qmail 7433 invoked by uid 1000); 24 Jan 2017 19:39:18 -0000 Date: Tue, 24 Jan 2017 19:39:18 +0000 To: npostavs@users.sourceforge.net Subject: Re: bug#25461: [Patch #2]: Missing doc strings for "," and ",@". Message-ID: <20170124193917.GA7358@acm> References: <20170118194320.GB4108@acm.fritz.box> <87lgu7dbyz.fsf@web.de> <20170119175801.GB3397@acm.fritz.box> <877f5qbndp.fsf@web.de> <20170120165856.GA3384@acm.fritz.box> <87y3y5cfnl.fsf@web.de> <20170121155651.GB5394@acm> <20170121204648.GA21091@acm> <871svtumvz.fsf@users.sourceforge.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <871svtumvz.fsf@users.sourceforge.net> User-Agent: Mutt/1.7.2 (2016-11-26) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -3.2 (---) X-Debbugs-Envelope-To: 25461 Cc: Michael Heerdegen , 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.2 (---) Hello, Noam. On Mon, Jan 23, 2017 at 23:01:36 -0500, npostavs@users.sourceforge.net wrote: > Alan Mackenzie writes: > > I've hacked all this together. What used to be called a "reader macro" > > is now a "reader construct". > I think "read syntax" is better just because the manual already uses > that term. I think this is a very fine point. "Read syntax" tends to distract attention from the semantics, I think. > > +;; Give `,' and `,@' documentation strings which can be examined by C-h f. > > +(put '\, 'function-documentation > > + "See `\\=`' (also `pcase') for the details of `,'.") > > +(put '\, 'reader-construct t) > > + > > +(put '\,@ 'function-documentation > > + "See `\\=`' or `,' for the details of `,@'.") > Linking from ",@" to "," seems a bit unhelpful, since "," hardly says > anything and just links to "`". Thanks, I actually spotted that and removed it before committing a patch yesterday. -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 24 14:43:41 2017 Received: (at 25461) by debbugs.gnu.org; 24 Jan 2017 19:43:42 +0000 Received: from localhost ([127.0.0.1]:40714 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cW70H-00071C-O1 for submit@debbugs.gnu.org; Tue, 24 Jan 2017 14:43:41 -0500 Received: from ocolin.muc.de ([193.149.48.4]:38949 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1cW70F-000714-PK for 25461@debbugs.gnu.org; Tue, 24 Jan 2017 14:43:40 -0500 Received: (qmail 63578 invoked by uid 3782); 24 Jan 2017 19:43:39 -0000 Received: from acm.muc.de (p548C7CD0.dip0.t-ipconnect.de [84.140.124.208]) by colin.muc.de (tmda-ofmipd) with ESMTP; Tue, 24 Jan 2017 20:43:38 +0100 Received: (qmail 7474 invoked by uid 1000); 24 Jan 2017 19:43:23 -0000 Date: Tue, 24 Jan 2017 19:43:23 +0000 To: Michael Heerdegen Subject: Re: bug#25461: [Patch #2]: Missing doc strings for "," and ",@". Message-ID: <20170124194323.GB7358@acm> References: <20170118194320.GB4108@acm.fritz.box> <87lgu7dbyz.fsf@web.de> <20170119175801.GB3397@acm.fritz.box> <877f5qbndp.fsf@web.de> <20170120165856.GA3384@acm.fritz.box> <87y3y5cfnl.fsf@web.de> <20170121155651.GB5394@acm> <20170121204648.GA21091@acm> <874m0pqkv5.fsf@web.de> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <874m0pqkv5.fsf@web.de> User-Agent: Mutt/1.7.2 (2016-11-26) X-Delivery-Agent: TMDA/1.1.12 (Macallan) From: Alan Mackenzie X-Primary-Address: acm@muc.de X-Spam-Score: -3.2 (---) X-Debbugs-Envelope-To: 25461 Cc: 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.2 (---) Hello, Michael. On Tue, Jan 24, 2017 at 02:58:54 +0100, Michael Heerdegen wrote: > Alan Mackenzie writes: > > I've hacked all this together. What used to be called a "reader > > macro" is now a "reader construct". > Well, I liked my suggested wording more, but that's not a big surprise I > guess. I wonder what others think? As I said to Noam, I don't thing "read syntax" is quite right. > > diff --git a/lisp/emacs-lisp/backquote.el b/lisp/emacs-lisp/backquote.el > > [...] > I see that you already installed you suggested patch. After a short > test it seems to work as intended (FWIW, it doesn't work with Helm, I > guess because Helm doesn't consult a completion table but reimplements > the whole C-h f thing by itself). That sounds bad! I wasn't actually aware of Helm, but at the moment I don't see why it would need its own C-h f facility. > Regards, > Michael. -- Alan Mackenzie (Nuremberg, Germany). From debbugs-submit-bounces@debbugs.gnu.org Tue Jan 24 15:00:45 2017 Received: (at 25461) by debbugs.gnu.org; 24 Jan 2017 20:00:45 +0000 Received: from localhost ([127.0.0.1]:40741 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cW7Gm-000860-2Z for submit@debbugs.gnu.org; Tue, 24 Jan 2017 15:00:44 -0500 Received: from mail-ot0-f170.google.com ([74.125.82.170]:33892) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cW7Gl-000801-A2 for 25461@debbugs.gnu.org; Tue, 24 Jan 2017 15:00:43 -0500 Received: by mail-ot0-f170.google.com with SMTP id f9so135852597otd.1 for <25461@debbugs.gnu.org>; Tue, 24 Jan 2017 12:00:43 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:sender:in-reply-to:references:from:date:message-id :subject:to:cc; bh=cxkvze5PL19PuElWsAHtAelh4/n78R7C60sxGcYXMkw=; b=jemrFkgrMGpfBH59id5Sagc+dLQnxrTXMYriVSuf8VZk9fuVNQTo7UNqZvXPg7OxRU B+51epnwhCaD3q0jffN2x1YMVfD/VvEiA1QvQGFMSHDcmjbEbp1sP4CJy+k/Wa5+HphD xVAniKBap3hgcq1bLEX/9VNthDgP6oH8DqPygBRGzOU+tva7sf6TI2TzG1r1LQ+Nk86a p0AC1Z0V1FE/yeGqVMssSCBa+SQRlMA5EvQ2tMF0dn9Up/ycwVyUcF2ZD7xyWCv3UZGl upp1OrFg405DYtvTtRNGIsLC7udwddgkKi14oEkoYwDWwe8HYVe2HF4fNPMcc6O/zcaL /rjg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:sender:in-reply-to:references:from :date:message-id:subject:to:cc; bh=cxkvze5PL19PuElWsAHtAelh4/n78R7C60sxGcYXMkw=; b=Ah1nDCJT6ePrfM7rfCUbYeOzq8Ja6rtpf07fh4zio6z8Emhc/DopxzXtYupFXzGO1q 6Igdgw3WUdoQzBFEXXS8dZLg3W5gEEyIV96etlWbt+syHiAenZd0tdMp4Yu4aiec3st1 Iukkn0+owpdLz0mGdTuVP5p6zua0CoxTDfHJj3UdOz30HhX2iw7DjIswHyxTcbea6ExG diZDKmnwvnBNzebLgyz7JWJwhOFiOqhD/c1fVpqVFqvTVCEaKlTWh5+ODjMV3oQTiD9g H2Ny3oSKAOmSmiTo81uNwjwxMGwMxSoU0gvnq0u1ggxqJyAA2uIjQOrcxdsWRtO1nqi0 8d4Q== X-Gm-Message-State: AIkVDXLC0kdp5DXY5SvPez64SNstE1zS8eIu2kX/7RoD1v6h/Uj+IL379YlcnsCjozUx1yK70BFhvHrTeoSdug== X-Received: by 10.157.40.72 with SMTP id h8mr19835625otd.79.1485288037505; Tue, 24 Jan 2017 12:00:37 -0800 (PST) MIME-Version: 1.0 Received: by 10.157.21.117 with HTTP; Tue, 24 Jan 2017 12:00:37 -0800 (PST) In-Reply-To: <20170124193917.GA7358@acm> References: <20170118194320.GB4108@acm.fritz.box> <87lgu7dbyz.fsf@web.de> <20170119175801.GB3397@acm.fritz.box> <877f5qbndp.fsf@web.de> <20170120165856.GA3384@acm.fritz.box> <87y3y5cfnl.fsf@web.de> <20170121155651.GB5394@acm> <20170121204648.GA21091@acm> <871svtumvz.fsf@users.sourceforge.net> <20170124193917.GA7358@acm> From: Noam Postavsky Date: Tue, 24 Jan 2017 15:00:37 -0500 X-Google-Sender-Auth: LNkpRxFuMe6AfmT44CvPdFpB1x8 Message-ID: Subject: Re: bug#25461: [Patch #2]: Missing doc strings for "," and ",@". To: Alan Mackenzie Content-Type: text/plain; charset=UTF-8 X-Spam-Score: 0.5 (/) X-Debbugs-Envelope-To: 25461 Cc: Michael Heerdegen , 25461@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.5 (/) On Tue, Jan 24, 2017 at 2:39 PM, Alan Mackenzie wrote: > "Read syntax" tends to distract attention from the semantics, I think. I don't quite agree about that, but I think what you've committed is perfectly fine, and there's not much to be gained by arguing the point any further. From unknown Tue Jun 17 20:14:39 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Wed, 22 Feb 2017 12:24:06 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator