From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.org!.POSTED!not-for-mail
From: Alan Mackenzie <acm@muc.de>
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>
	<m2377hi5o4.fsf@newartisans.com> <20170921205447.GA8240@ACM>
	<d3e19fb3-e273-28d4-2446-1071a84be301@cs.ucla.edu>
	<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 <eliz@gnu.org>, Richard Stallman <rms@gnu.org>,
	emacs-devel@gnu.org
To: Paul Eggert <eggert@cs.ucla.edu>
Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Sep 24 16:41:51 2017
Return-path: <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>
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 <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>)
	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 <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>)
	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 <acm@muc.de>)
	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 <acm@muc.de>) 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 <acm@muc.de>)
	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." <emacs-devel.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/emacs-devel>,
	<mailto:emacs-devel-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/emacs-devel/>
List-Post: <mailto:emacs-devel@gnu.org>
List-Help: <mailto:emacs-devel-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/emacs-devel>,
	<mailto:emacs-devel-request@gnu.org?subject=subscribe>
Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org
Original-Sender: "Emacs-devel" <emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org>
Xref: news.gmane.org gmane.emacs.devel:218743
Archived-At: <http://permalink.gmane.org/gmane.emacs.devel/218743>

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).