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: Fri, 20 Jan 2017 01:12:18 +0100 Message-ID: <877f5qbndp.fsf@web.de> References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87lgu7dbyz.fsf@web.de> <20170119175801.GB3397@acm.fritz.box> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1484871208 2761 195.159.176.226 (20 Jan 2017 00:13:28 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 20 Jan 2017 00:13:28 +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 Fri Jan 20 01:13:24 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 1cUMpK-0007e4-Pk for geb-bug-gnu-emacs@m.gmane.org; Fri, 20 Jan 2017 01:13:11 +0100 Original-Received: from localhost ([::1]:51608 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cUMpP-0007iB-Bk for geb-bug-gnu-emacs@m.gmane.org; Thu, 19 Jan 2017 19:13:15 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:57643) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cUMpH-0007hr-Qu for bug-gnu-emacs@gnu.org; Thu, 19 Jan 2017 19:13:09 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cUMpC-0006ss-R9 for bug-gnu-emacs@gnu.org; Thu, 19 Jan 2017 19:13:07 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:37666) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cUMpC-0006sg-OA for bug-gnu-emacs@gnu.org; Thu, 19 Jan 2017 19:13:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1cUMpB-0008AD-Po for bug-gnu-emacs@gnu.org; Thu, 19 Jan 2017 19:13:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Michael Heerdegen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 20 Jan 2017 00:13: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.148487115031342 (code B ref 25461); Fri, 20 Jan 2017 00:13:01 +0000 Original-Received: (at 25461) by debbugs.gnu.org; 20 Jan 2017 00:12:30 +0000 Original-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 Original-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 Original-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 In-Reply-To: <20170119175801.GB3397@acm.fritz.box> (Alan Mackenzie's message of "Thu, 19 Jan 2017 17:58:01 +0000") 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/fxYsNb 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:128256 Archived-At: 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.