From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: Emacs 26.1 release branch created Date: Sun, 24 Sep 2017 14:33:41 +0000 Message-ID: <20170924143341.GB5725@ACM> References: <83377mls4d.fsf@gnu.org> <20170919173511.GA19168@ACM> <20170921205447.GA8240@ACM> <20170922180440.GA7229@ACM> <5de6367f-49a0-b991-e084-c673d8443fde@cs.ucla.edu> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: blaine.gmane.org 1506264116 28413 195.159.176.226 (24 Sep 2017 14:41:56 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 24 Sep 2017 14:41:56 +0000 (UTC) User-Agent: Mutt/1.7.2 (2016-11-26) Cc: Eli Zaretskii , Richard Stallman , emacs-devel@gnu.org To: Paul Eggert Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Sep 24 16:41:51 2017 Return-path: Envelope-to: ged-emacs-devel@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 1dw86P-0006v3-GA for ged-emacs-devel@m.gmane.org; Sun, 24 Sep 2017 16:41:49 +0200 Original-Received: from localhost ([::1]:38394 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dw86V-0000Ge-4B for ged-emacs-devel@m.gmane.org; Sun, 24 Sep 2017 10:41:55 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54791) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dw85t-0000GY-2H for emacs-devel@gnu.org; Sun, 24 Sep 2017 10:41:18 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dw85p-0006hF-Ve for emacs-devel@gnu.org; Sun, 24 Sep 2017 10:41:17 -0400 Original-Received: from ocolin.muc.de ([193.149.48.4]:31721 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1dw85p-0006cl-LJ for emacs-devel@gnu.org; Sun, 24 Sep 2017 10:41:13 -0400 Original-Received: (qmail 13456 invoked by uid 3782); 24 Sep 2017 14:41:08 -0000 Original-Received: from acm.muc.de (p548C6746.dip0.t-ipconnect.de [84.140.103.70]) by colin.muc.de (tmda-ofmipd) with ESMTP; Sun, 24 Sep 2017 16:41:02 +0200 Original-Received: (qmail 7032 invoked by uid 1000); 24 Sep 2017 14:33:41 -0000 Content-Disposition: inline In-Reply-To: <5de6367f-49a0-b991-e084-c673d8443fde@cs.ucla.edu> X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x [fuzzy] X-Received-From: 193.149.48.4 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:218743 Archived-At: Hello, Paul. On Fri, Sep 22, 2017 at 13:42:17 -0700, Paul Eggert wrote: > On 09/22/2017 11:04 AM, Alan Mackenzie wrote: > > the main point here is to remind the reader that quotes can be > > output as is by binding text-quoting-style > But that's not how Elisp code typically outputs quotes as is. I see no > instances of such a thing in the emacs-26 branch. Instead, code > typically uses backslash escapes (in doc strings) or %s applied to the > output of 'format' (in message formats). Yes. That doesn't mean it's any good. Putting a single output operation through two `format'-like operations is bizarre and extravagant. It's not something we should encourage. By contrast, binding a controlling variable around an operation is the standard Emacs way of doing such things. > It's better for the Elisp manual to suggest the techniques that are > typically used. Not really. Better to encourage the standard technique, and to replace the extravagant and bizarre double `format'ting in the code. How many such instances are there in the code anyway? I know there's one in cc-engine.el, but what else is there? > > Perhaps you could suggest an improved wording > Sure, a suggested patch is attached. This patch attempts to address only > this issue; it doesn't affect whether text-quoting-style is > customizable, as that is orthogonal. Since there were three or four > copies of boilerplate language that was getting longer, this patch > creates a new node Text Quoting Style that contains the detailed > discussion of text-quoting-style and how to get around it, and adjusts > the other parts of the manual to mention the issue briefly and > cross-reference to the new section. I don't think this would be a good change. Even were it updated to take into account the updates in text-quoting-style, it fragments the descriptions of `message', etc., too much. You've put in a bare @xref to text-quoting-style without saying why somebody would want to follow the link. This would need fleshing out with something like "To inhibit or influence this translation of ASCII quotes, see text-quoting-style". The "boilerplate" you want to replace is short and to the point, and essential to the functions whose descriptions it is present in. It occurs just three times. I think it should stay. A further general point about this bit of doc is its rather strange use of the verb "generate". The style is about 0x27 and 0x60 "generating" quote marks. This is confusing, since they _are_ quotes. It would help a little, though not very much, to say instead that they can generate OTHER quotes. But the main thing is that these characters are not agents; they don't do things, they are passive objects. So it would be better to say they can be _substituted_ by or _translated_ into other quotes. It isn't as bad to say that `message' or `error' "generate" quote marks, but it is still confusing, since the quote marks are already present to begin with. "Translated" or even "transformed" is what's wanted here. [ .... ] -- Alan Mackenzie (Nuremberg, Germany).