From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Noam Postavsky Newsgroups: gmane.emacs.bugs Subject: bug#25461: [Patch]: Missing doc strings for "," and ",@". Date: Thu, 19 Jan 2017 13:10:24 -0500 Message-ID: References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87r33zx5st.fsf@users.sourceforge.net> <20170119173728.GA3397@acm.fritz.box> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 X-Trace: blaine.gmane.org 1484849478 16288 195.159.176.226 (19 Jan 2017 18:11:18 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 19 Jan 2017 18:11:18 +0000 (UTC) Cc: 25461@debbugs.gnu.org To: Alan Mackenzie Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Jan 19 19:11:13 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 1cUHB0-0003fY-Ij for geb-bug-gnu-emacs@m.gmane.org; Thu, 19 Jan 2017 19:11:10 +0100 Original-Received: from localhost ([::1]:50240 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cUHB5-0005VQ-Fi for geb-bug-gnu-emacs@m.gmane.org; Thu, 19 Jan 2017 13:11:15 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54757) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cUHAv-0005So-8B for bug-gnu-emacs@gnu.org; Thu, 19 Jan 2017 13:11:06 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cUHAs-0007lY-IO for bug-gnu-emacs@gnu.org; Thu, 19 Jan 2017 13:11:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:37543) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cUHAs-0007lQ-Dt for bug-gnu-emacs@gnu.org; Thu, 19 Jan 2017 13:11:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1cUHAs-00016t-6G for bug-gnu-emacs@gnu.org; Thu, 19 Jan 2017 13:11:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Noam Postavsky Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 19 Jan 2017 18:11:02 +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.14848494334224 (code B ref 25461); Thu, 19 Jan 2017 18:11:02 +0000 Original-Received: (at 25461) by debbugs.gnu.org; 19 Jan 2017 18:10:33 +0000 Original-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 Original-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 Original-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) Original-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> X-Google-Sender-Auth: hckrFRoyRZ5ciePJCO9Y49SDUE0 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:128247 Archived-At: 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.