Re: Emacs 26.1 release branch created

[Alan Mackenzie <acm@muc.de>]

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