From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.bugs Subject: bug#25461: [Patch]: Missing doc strings for "," and ",@". Date: Thu, 19 Jan 2017 17:37:28 +0000 Message-ID: <20170119173728.GA3397@acm.fritz.box> References: <20170116212257.GA4747@acm.fritz.box> <20170118194320.GB4108@acm.fritz.box> <87r33zx5st.fsf@users.sourceforge.net> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: blaine.gmane.org 1484848391 2981 195.159.176.226 (19 Jan 2017 17:53:11 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 19 Jan 2017 17:53:11 +0000 (UTC) User-Agent: Mutt/1.5.24 (2015-08-30) Cc: 25461@debbugs.gnu.org To: npostavs@users.sourceforge.net Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Jan 19 18:53:07 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 1cUGtO-0008Cm-MJ for geb-bug-gnu-emacs@m.gmane.org; Thu, 19 Jan 2017 18:52:58 +0100 Original-Received: from localhost ([::1]:50080 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cUGtT-0007sL-Ch for geb-bug-gnu-emacs@m.gmane.org; Thu, 19 Jan 2017 12:53:03 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45673) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cUGf0-0003Aa-Pj for bug-gnu-emacs@gnu.org; Thu, 19 Jan 2017 12:38:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cUGew-0005jd-Kc for bug-gnu-emacs@gnu.org; Thu, 19 Jan 2017 12:38:06 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:37535) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cUGew-0005jX-IA for bug-gnu-emacs@gnu.org; Thu, 19 Jan 2017 12:38:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1cUGew-0000IH-9X for bug-gnu-emacs@gnu.org; Thu, 19 Jan 2017 12:38:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 19 Jan 2017 17:38: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.14848474691107 (code B ref 25461); Thu, 19 Jan 2017 17:38:02 +0000 Original-Received: (at 25461) by debbugs.gnu.org; 19 Jan 2017 17:37:49 +0000 Original-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 Original-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 Original-Received: (qmail 20396 invoked by uid 3782); 19 Jan 2017 17:37:43 -0000 Original-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 Original-Received: (qmail 3442 invoked by uid 1000); 19 Jan 2017 17:37:28 -0000 Content-Disposition: inline In-Reply-To: <87r33zx5st.fsf@users.sourceforge.net> X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de 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:128244 Archived-At: 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).