Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, John.

On Sun, Sep 24, 2017 at 21:23:48 -0700, John Wiegley wrote:
> >>>>> "PE" == Paul Eggert <address@hidden> writes:

[ .... ]

> PE> 1. Whether the manual should recommend routinely let-binding
> PE> text-quoting-style, a style that Alan favors. I think it should recommend 
> the
> PE> (message "%s" ...)
> PE> style that the Emacs source code itself uses, as this style is more 
> flexible
> PE> and reliable. (I can give examples of why, if you care.)

To be precise, the wording I used for this bit began "One way to ....",
which could be construed as a recommendation, but need not necessarily
be so.

> I think (message "%s") is both simpler and more future proof, since we may end
> up with other features that this could apply to.

Let's compare the two approaches.  As a simple example, which worked
fine before the curly quotes:

    (message "'%s" form)         (0)

, which outputs a lisp form after the quote character.  Clearly this
character must remain the ASCII apostrophe.  How can we best amend this
for the current situation?  The form I favour is:

    (let ((text-quoting-style 'grave))    (1)
      (message "'%s" form))

.  What Paul favours is something like

    (message "%s" (format "'%s" form))    (2)

.  To me, (1) is a clearer form that (2), partly because it separates
the two distinct things at work, namely performing the message action,
and avoiding the spurious translation of the apostrophe into a curly
quote.  (1) performs a single "format"-like operation, (2) performs two.

(2) is more difficult to read, it being somewhat puzzling (why the two
"format" operations?), and simply mentally juggling the arguments to
`message' and `format' is more difficult than the straight `message'
invocation in (1).

I agree with Paul that these considerations are fairly minor.  Also,
there will be forms where the (1)-style formulation is not simpler than
the (2)-style.

At the moment, there is a single known example in the Emacs lisp code of
taking action to avoid an unwanted conversion of a quote.  It uses the
(2)-style.  This is in c-replay-parse-state-state in cc-engine.el.

How about suggesting both methods in the documentation, and leaving it
up to the programmer which way she considers best?

> PE> 2. Alan wants the description of every affected function to have a big
> PE> paragraph about text quoting, whereas I prefer to replace those big
> PE> paragraphs with short blurbs that reference a single (new) section that
> PE> covers the issue in more detail than the big paragraphs would.

> References to a single elaborated paragraph will make for much easier
> maintenance of the documentation, so let's do that.

OK, but I will be unhappy if the text around the cross references
doesn't state that the translation of quotes can be inhibited.  Without
that, the documentation of each function would be incomplete and
fragmented.  "To influence or inhibit this translation of the quote
characters, see xxxxxx." would do.

I suggest I spruce up the documentation along the lines we've discussed,
based on and using Paul's suggestions from the last day or two.

How about merging this change into emacs-26 anyway, now?  It might be
holding up the first pre-test being released, and documentation changes
are (if I understand correctly) acceptable during the pre-test phase.

> -- 
> John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
> http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

-- 
Alan Mackenzie (Nuremberg, Germany).