From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Michael Heerdegen Newsgroups: gmane.emacs.bugs Subject: bug#25461: [Patch]: Missing doc strings for "," and ",@". Date: Sat, 21 Jan 2017 03:26:06 +0100 Message-ID: <87y3y5cfnl.fsf@web.de> 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> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1484965634 27303 195.159.176.226 (21 Jan 2017 02:27:14 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 21 Jan 2017 02:27:14 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.91 (gnu/linux) Cc: 25461@debbugs.gnu.org To: Alan Mackenzie Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Jan 21 03:27:10 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cUlOV-0006Qq-5J for geb-bug-gnu-emacs@m.gmane.org; Sat, 21 Jan 2017 03:27:07 +0100 Original-Received: from localhost ([::1]:58182 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cUlOZ-0008O7-RP for geb-bug-gnu-emacs@m.gmane.org; Fri, 20 Jan 2017 21:27:11 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:33119) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cUlOU-0008Nz-E2 for bug-gnu-emacs@gnu.org; Fri, 20 Jan 2017 21:27:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cUlOQ-0007yd-Ep for bug-gnu-emacs@gnu.org; Fri, 20 Jan 2017 21:27:06 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:38582) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cUlOQ-0007yS-Bv for bug-gnu-emacs@gnu.org; Fri, 20 Jan 2017 21:27:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1cUlOP-0004Wp-Vj for bug-gnu-emacs@gnu.org; Fri, 20 Jan 2017 21:27:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Michael Heerdegen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 21 Jan 2017 02:27:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 25461 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 25461-submit@debbugs.gnu.org id=B25461.148496557817355 (code B ref 25461); Sat, 21 Jan 2017 02:27:01 +0000 Original-Received: (at 25461) by debbugs.gnu.org; 21 Jan 2017 02:26:18 +0000 Original-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 Original-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 Original-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 In-Reply-To: <20170120165856.GA3384@acm.fritz.box> (Alan Mackenzie's message of "Fri, 20 Jan 2017 16:58:56 +0000") 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+q0K2hfBWemi5xYyRO2FwiSs2wLnU4JFZTpnw X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:128284 Archived-At: 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.