Emacs 26.1 release branch created

Emacs 26.1 release branch created

[Eli Zaretskii]

I've created a new emacs-26 branch which will be used to release Emacs
26.x, starting with Emacs 26.1.  This branch should be used for fixing
bugs; new development should continue on master.  (If there are
features that are already on the branch, and their developers want to
put a few finishing touches or additions to those features, please ask
here before pushing further changes that are not bugfixes.)

Alan, you will probably want to cherry-pick your latest commit from
master master to this branch.

Nicolas, please produce the first pretest in, say, a week's time.
Let's optimistically call that pretest 26.0.90.

Thanks.

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> Date: Sat, 16 Sep 2017 15:56:02 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: Alan Mackenzie <acm@muc.de>
> 
> I've created a new emacs-26 branch which will be used to release Emacs
> 26.x, starting with Emacs 26.1.  This branch should be used for fixing
> bugs; new development should continue on master.  (If there are
> features that are already on the branch, and their developers want to
> put a few finishing touches or additions to those features, please ask
> here before pushing further changes that are not bugfixes.)

Oh, one more thing: please from now on fix all bugs relevant to the
emacs-26 branch on that branch, not on master.  (As we always do while
a release branch is active.)

TIA

Re: Emacs 26.1 release branch created

[Mark Oteiza]

Eli Zaretskii <eliz@gnu.org> writes:

> I've created a new emacs-26 branch which will be used to release Emacs
> 26.x, starting with Emacs 26.1.  This branch should be used for fixing
> bugs; new development should continue on master.  (If there are
> features that are already on the branch, and their developers want to
> put a few finishing touches or additions to those features, please ask
> here before pushing further changes that are not bugfixes.)

I'm working on more utilities and tests for lcms.c, where should I
commit those?

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> From: Mark Oteiza <mvoteiza@udel.edu>
> Cc: emacs-devel@gnu.org
> Date: Sat, 16 Sep 2017 09:09:00 -0400
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I've created a new emacs-26 branch which will be used to release Emacs
> > 26.x, starting with Emacs 26.1.  This branch should be used for fixing
> > bugs; new development should continue on master.  (If there are
> > features that are already on the branch, and their developers want to
> > put a few finishing touches or additions to those features, please ask
> > here before pushing further changes that are not bugfixes.)
> 
> I'm working on more utilities and tests for lcms.c, where should I
> commit those?

On emacs-26, I guess.  How many more utilities do you envision?
(Tests are okay to add to emacs-26 regardless.)

Re: Emacs 26.1 release branch created

[Mark Oteiza]

On 16/09/17 at 04:39pm, Eli Zaretskii wrote:
> > From: Mark Oteiza <mvoteiza@udel.edu>
> > Cc: emacs-devel@gnu.org
> > Date: Sat, 16 Sep 2017 09:09:00 -0400
> > 
> > Eli Zaretskii <eliz@gnu.org> writes:
> > 
> > > I've created a new emacs-26 branch which will be used to release Emacs
> > > 26.x, starting with Emacs 26.1.  This branch should be used for fixing
> > > bugs; new development should continue on master.  (If there are
> > > features that are already on the branch, and their developers want to
> > > put a few finishing touches or additions to those features, please ask
> > > here before pushing further changes that are not bugfixes.)
> > 
> > I'm working on more utilities and tests for lcms.c, where should I
> > commit those?
> 
> On emacs-26, I guess.  How many more utilities do you envision?
> (Tests are okay to add to emacs-26 regardless.)

Dividing the internals of lcms-cam02-ucs into C functions, and from that
making the Lisp functions:

lcms-xyz->jch
lcms-jch->jab
lcms-jab->jch
lcms-jch->xyz

and adding a Lisp variable `lcms-d65-xyz' as the default whitepoint for
all the functions in lcms.c that need one.  That should be two commits
if I can get all the Windows build stuff correct.

I plan to add more, but I can wait for an emacs-26 -> master merge and
continue to work on master.

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> Date: Sat, 16 Sep 2017 10:51:12 -0400
> From: Mark Oteiza <mvoteiza@udel.edu>
> Cc: emacs-devel@gnu.org
> 
> > > I'm working on more utilities and tests for lcms.c, where should I
> > > commit those?
> > 
> > On emacs-26, I guess.  How many more utilities do you envision?
> > (Tests are okay to add to emacs-26 regardless.)
> 
> Dividing the internals of lcms-cam02-ucs into C functions, and from that
> making the Lisp functions:
> 
> lcms-xyz->jch
> lcms-jch->jab
> lcms-jab->jch
> lcms-jch->xyz
> 
> and adding a Lisp variable `lcms-d65-xyz' as the default whitepoint for
> all the functions in lcms.c that need one.  That should be two commits
> if I can get all the Windows build stuff correct.

That can certainly go to emacs-26.

> I plan to add more, but I can wait for an emacs-26 -> master merge and
> continue to work on master.

If you consider the feature fairly complete for a first release, then
that's fine.  Otherwise we could consider adding more of your code to
emacs-26, unless you think the development will take a considerable
time.  In general, once the first pretest is out (which will be
probably a week or 2 from now), no new features should be added.

Re: Emacs 26.1 release branch created

[Mark Oteiza]

On 16/09/17 at 02:58pm, Eli Zaretskii wrote:
> > Date: Sat, 16 Sep 2017 10:51:12 -0400
> > From: Mark Oteiza <mvoteiza@udel.edu>
> > Cc: emacs-devel@gnu.org
> > 
> > making the Lisp functions:
> > 
> > lcms-xyz->jch
> > lcms-jch->jab
> > lcms-jab->jch
> > lcms-jch->xyz
> > 
> > and adding a Lisp variable `lcms-d65-xyz' as the default whitepoint for
> > all the functions in lcms.c that need one.  That should be two commits
> > if I can get all the Windows build stuff correct.
> 
> That can certainly go to emacs-26.
> 
> > I plan to add more, but I can wait for an emacs-26 -> master merge and
> > continue to work on master.
> 
> If you consider the feature fairly complete for a first release, then
> that's fine.  Otherwise we could consider adding more of your code to
> emacs-26, unless you think the development will take a considerable
> time.  In general, once the first pretest is out (which will be
> probably a week or 2 from now), no new features should be added.

I ended up going back on what I said in d24ec5854 after thinking about what
I wanted to add, how the API should look, and going through some iterations
adding those functions.  I think I'll leave it at those three functions for
emacs-26.

In the interest of reducing the amount of (duplicated) code, especially as more
Lisp functions are added, I propose the following.  I followed from your code
and from how it's done in xml.c, not sure if you have a particular reason for
doing it one way or the other.

 src/lcms.c | 75 ++++++++++++++++++++++----------------------------------------
 1 file changed, 26 insertions(+), 49 deletions(-)

diff --git a/src/lcms.c b/src/lcms.c
index a5e527911e..950ffb5f51 100644
--- a/src/lcms.c
+++ b/src/lcms.c
@@ -76,6 +76,26 @@ init_lcms_functions (void)
 
 #endif	/* WINDOWSNT */
 
+static bool
+lcms2_available_p (void)
+{
+#ifdef WINDOWSNT
+  Lisp_Object found = Fassq (Qlcms2, Vlibrary_cache);
+  if (CONSP (found))
+    return NILP (XCDR (found)) ? false : true;
+  else
+    {
+      Lisp_Object status;
+      lcms_initialized = init_lcms_functions ();
+      status = lcms_initialized;
+      Vlibrary_cache = Fcons (Fcons (Qlcms2, status), Vlibrary_cache);
+      return status;
+    }
+#else  /* !WINDOWSNT */
+  return true;
+#endif
+}
+
 static bool
 parse_lab_list (Lisp_Object lab_list, cmsCIELab *color)
 {
@@ -109,15 +129,8 @@ chroma, and hue, respectively. The parameters each default to 1.  */)
   cmsCIELab Lab1, Lab2;
   cmsFloat64Number Kl, Kc, Kh;
 
-#ifdef WINDOWSNT
-  if (!lcms_initialized)
-    lcms_initialized = init_lcms_functions ();
-  if (!lcms_initialized)
-    {
-      message1 ("lcms2 library not found");
-      return Qnil;
-    }
-#endif
+  if (!(init_lcms_functions ()))
+    return Qnil;
 
   if (!(CONSP (color1) && parse_lab_list (color1, &Lab1)))
     signal_error ("Invalid color", color1);
@@ -244,15 +257,8 @@ The default viewing conditions are (20 100 1 1).  */)
   double Jp1, ap1, bp1, Jp2, ap2, bp2;
   double Mp1, Mp2, FL, k, k4;
 
-#ifdef WINDOWSNT
-  if (!lcms_initialized)
-    lcms_initialized = init_lcms_functions ();
-  if (!lcms_initialized)
-    {
-      message1 ("lcms2 library not found");
-      return Qnil;
-    }
-#endif
+  if (!(init_lcms_functions ()))
+    return Qnil;
 
   if (!(CONSP (color1) && parse_xyz_list (color1, &xyz1)))
     signal_error ("Invalid color", color1);
@@ -313,15 +319,8 @@ Valid range of TEMPERATURE is from 4000K to 25000K.  */)
   cmsCIExyY whitepoint;
   cmsCIEXYZ wp;
 
-#ifdef WINDOWSNT
-  if (!lcms_initialized)
-    lcms_initialized = init_lcms_functions ();
-  if (!lcms_initialized)
-    {
-      message1 ("lcms2 library not found");
-      return Qnil;
-    }
-#endif
+  if (!(init_lcms_functions ()))
+    return Qnil;
 
   CHECK_NUMBER_OR_FLOAT (temperature);
 
@@ -332,27 +331,6 @@ Valid range of TEMPERATURE is from 4000K to 25000K.  */)
   return list3 (make_float (wp.X), make_float (wp.Y), make_float (wp.Z));
 }
 
-DEFUN ("lcms2-available-p", Flcms2_available_p, Slcms2_available_p, 0, 0, 0,
-       doc: /* Return t if lcms2 color calculations are available in this instance of Emacs.  */)
-     (void)
-{
-#ifdef WINDOWSNT
-  Lisp_Object found = Fassq (Qlcms2, Vlibrary_cache);
-  if (CONSP (found))
-    return XCDR (found);
-  else
-    {
-      Lisp_Object status;
-      lcms_initialized = init_lcms_functions ();
-      status = lcms_initialized ? Qt : Qnil;
-      Vlibrary_cache = Fcons (Fcons (Qlcms2, status), Vlibrary_cache);
-      return status;
-    }
-#else  /* !WINDOWSNT */
-  return Qt;
-#endif
-}
-
 \f
 /* Initialization */
 void
@@ -360,7 +338,6 @@ syms_of_lcms2 (void)
 {
   defsubr (&Slcms_cie_de2000);
   defsubr (&Slcms_cam02_ucs);
-  defsubr (&Slcms2_available_p);
   defsubr (&Slcms_temp_to_white_point);
 
   Fprovide (intern_c_string ("lcms2"), Qnil);

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> Date: Fri, 22 Sep 2017 12:59:41 -0400
> From: Mark Oteiza <mvoteiza@udel.edu>
> Cc: emacs-devel@gnu.org
> 
> I ended up going back on what I said in d24ec5854 after thinking about what
> I wanted to add, how the API should look, and going through some iterations
> adding those functions.  I think I'll leave it at those three functions for
> emacs-26.
> 
> In the interest of reducing the amount of (duplicated) code, especially as more
> Lisp functions are added, I propose the following.  I followed from your code
> and from how it's done in xml.c, not sure if you have a particular reason for
> doing it one way or the other.

Hmm... I'm probably missing something, because I don't understand the
rationale and the intent of your changes.  You introduce a static
function lcms2_available_p that is not used anywhere else in the file?
And you removed lcms2-available-p without which Lisp code cannot know
at run time whether lcms2 support is available or not?  Where does
this lead?

Re: Emacs 26.1 release branch created

[Mark Oteiza]

On 22/09/17 at 07:59pm, Eli Zaretskii wrote:
> > Date: Fri, 22 Sep 2017 12:59:41 -0400
> > From: Mark Oteiza <mvoteiza@udel.edu>
> > Cc: emacs-devel@gnu.org
> > 
> > I ended up going back on what I said in d24ec5854 after thinking about what
> > I wanted to add, how the API should look, and going through some iterations
> > adding those functions.  I think I'll leave it at those three functions for
> > emacs-26.
> > 
> > In the interest of reducing the amount of (duplicated) code, especially as more
> > Lisp functions are added, I propose the following.  I followed from your code
> > and from how it's done in xml.c, not sure if you have a particular reason for
> > doing it one way or the other.
> 
> Hmm... I'm probably missing something, because I don't understand the
> rationale and the intent of your changes.  You introduce a static
> function lcms2_available_p that is not used anywhere else in the file?

Oops, all the instances of replacing #ifdef'd code with
init_lcms_functions were meant to instead be calling lcms_available_p.
Hopefully that makes the intent clear.

> And you removed lcms2-available-p without which Lisp code cannot know
> at run time whether lcms2 support is available or not?  Where does
> this lead?

I don't think having it in Lisp is necessary--isn't it essentially the
same as (featurep 'lcms2)?

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> Date: Fri, 22 Sep 2017 16:05:03 -0400
> From: Mark Oteiza <mvoteiza@udel.edu>
> Cc: emacs-devel@gnu.org
> 
> > Hmm... I'm probably missing something, because I don't understand the
> > rationale and the intent of your changes.  You introduce a static
> > function lcms2_available_p that is not used anywhere else in the file?
> 
> Oops, all the instances of replacing #ifdef'd code with
> init_lcms_functions were meant to instead be calling lcms_available_p.
> Hopefully that makes the intent clear.

Yes, clear.

> > And you removed lcms2-available-p without which Lisp code cannot know
> > at run time whether lcms2 support is available or not?  Where does
> > this lead?
> 
> I don't think having it in Lisp is necessary--isn't it essentially the
> same as (featurep 'lcms2)?

No, not on MS-Windows.  An Emacs binary compiled with lcms2 support,
then moved to a system where lcms2 libraries are not installed will
return t from featurep, but the lcms2 functions will signal an error.

Re: Emacs 26.1 release branch created

[Mark Oteiza]

On 22/09/17 at 08:11pm, Eli Zaretskii wrote:
> > Date: Fri, 22 Sep 2017 16:05:03 -0400
> > From: Mark Oteiza <mvoteiza@udel.edu>
> > Cc: emacs-devel@gnu.org
> > 
> > > Hmm... I'm probably missing something, because I don't understand the
> > > rationale and the intent of your changes.  You introduce a static
> > > function lcms2_available_p that is not used anywhere else in the file?
> > 
> > Oops, all the instances of replacing #ifdef'd code with
> > init_lcms_functions were meant to instead be calling lcms_available_p.
> > Hopefully that makes the intent clear.
> 
> Yes, clear.
> 
> > > And you removed lcms2-available-p without which Lisp code cannot know
> > > at run time whether lcms2 support is available or not?  Where does
> > > this lead?
> > 
> > I don't think having it in Lisp is necessary--isn't it essentially the
> > same as (featurep 'lcms2)?
> 
> No, not on MS-Windows.  An Emacs binary compiled with lcms2 support,
> then moved to a system where lcms2 libraries are not installed will
> return t from featurep, but the lcms2 functions will signal an error.

Ah, ok.  Thanks for the correction.

[PATCH] lcms2 (was Re: Emacs 26.1 release branch created)

[Mark Oteiza]

On 16/09/17 at 05:58pm, Eli Zaretskii wrote:
> > Date: Sat, 16 Sep 2017 10:51:12 -0400
> > From: Mark Oteiza <mvoteiza@udel.edu>
> > Cc: emacs-devel@gnu.org
> > 
> > > > I'm working on more utilities and tests for lcms.c, where should I
> > > > commit those?
> > > 
> > > On emacs-26, I guess.  How many more utilities do you envision?
> > > (Tests are okay to add to emacs-26 regardless.)
> > 
> > Dividing the internals of lcms-cam02-ucs into C functions, and from that
> > making the Lisp functions:
> > 
> > lcms-xyz->jch
> > lcms-jch->jab
> > lcms-jab->jch
> > lcms-jch->xyz
> > 
> > and adding a Lisp variable `lcms-d65-xyz' as the default whitepoint for
> > all the functions in lcms.c that need one.  That should be two commits
> > if I can get all the Windows build stuff correct.
> 
> That can certainly go to emacs-26.
> 
> > I plan to add more, but I can wait for an emacs-26 -> master merge and
> > continue to work on master.
> 
> If you consider the feature fairly complete for a first release, then
> that's fine.  Otherwise we could consider adding more of your code to
> emacs-26, unless you think the development will take a considerable
> time.  In general, once the first pretest is out (which will be
> probably a week or 2 from now), no new features should be added.

Here is the patch I thought I would not get done.

From 98a0ff92120f7c23f716dc98b381660004b37a8c Mon Sep 17 00:00:00 2001
From: Mark Oteiza <mvoteiza@udel.edu>
Date: Tue, 26 Sep 2017 17:13:36 -0400
Subject: [PATCH] Add CAM02 JCh and CAM02-UCS J'a'b' conversions

* src/lcms.h: New file.
* src/lcms.c (rad2deg, parse_jch_list, parse_jab_list, xyz_to_jch):
(jch_to_xyz, jch_to_jab, jab_to_jch): New functions.
(lcms-jch->xyz, lcms-jch->xyz, lcms-jch->jab, lcms-jab->jch): New Lisp
functions.
(lcms-cam02-ucs): Refactor.
(syms_of_lcms2): Declare new functions.
* test/src/lcms-tests.el (lcms-roundtrip, lcms-ciecam02-gold):
(lcms-jmh->cam02-ucs-silver): New tests.
---
 src/lcms.c             | 291 +++++++++++++++++++++++++++++++++++++++++++------
 src/lcms.h             |  30 +++++
 test/src/lcms-tests.el |  44 ++++++++
 3 files changed, 332 insertions(+), 33 deletions(-)
 create mode 100644 src/lcms.h

diff --git a/src/lcms.c b/src/lcms.c
index a5e527911e..24b4f22ed1 100644
--- a/src/lcms.c
+++ b/src/lcms.c
@@ -24,6 +24,7 @@ along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
 #include <math.h>
 
 #include "lisp.h"
+#include "lcms.h"
 
 #ifdef WINDOWSNT
 # include <windows.h>
@@ -145,6 +146,12 @@ deg2rad (double degrees)
   return M_PI * degrees / 180.0;
 }
 
+static double
+rad2deg (double radians)
+{
+  return 180.0 * radians / M_PI;
+}
+
 static cmsCIEXYZ illuminant_d65 = { .X = 95.0455, .Y = 100.0, .Z = 108.8753 };
 
 static void
@@ -180,6 +187,46 @@ parse_xyz_list (Lisp_Object xyz_list, cmsCIEXYZ *color)
   return true;
 }
 
+static bool
+parse_jch_list (Lisp_Object jch_list, cmsJCh *color)
+{
+#define PARSE_JCH_LIST_FIELD(field)					\
+  if (CONSP (jch_list) && NUMBERP (XCAR (jch_list)))			\
+    {									\
+      color->field = XFLOATINT (XCAR (jch_list));			\
+      jch_list = XCDR (jch_list);					\
+    }									\
+  else									\
+    return false;
+
+  PARSE_JCH_LIST_FIELD (J);
+  PARSE_JCH_LIST_FIELD (C);
+  PARSE_JCH_LIST_FIELD (h);
+
+  if (! NILP (jch_list))
+    return false;
+  return true;
+}
+
+static bool
+parse_jab_list (Lisp_Object jab_list, lcmsJab_t *color)
+{
+#define PARSE_JAB_LIST_FIELD(field)					\
+  if (CONSP (jab_list) && NUMBERP (XCAR (jab_list)))			\
+    {									\
+      color->field = XFLOATINT (XCAR (jab_list));			\
+      jab_list = XCDR (jab_list);					\
+    }									\
+  else									\
+    return false;
+
+  PARSE_JAB_LIST_FIELD (J);
+  PARSE_JAB_LIST_FIELD (a);
+  PARSE_JAB_LIST_FIELD (b);
+
+  return true;
+}
+
 static bool
 parse_viewing_conditions (Lisp_Object view, const cmsCIEXYZ *wp,
                           cmsViewingConditions *vc)
@@ -216,6 +263,204 @@ parse_viewing_conditions (Lisp_Object view, const cmsCIEXYZ *wp,
   return true;
 }
 
+static void
+xyz_to_jch (const cmsCIEXYZ *xyz, cmsJCh *jch, const cmsViewingConditions *vc)
+{
+  cmsHANDLE h;
+
+  h = cmsCIECAM02Init (0, vc);
+  cmsCIECAM02Forward (h, xyz, jch);
+  cmsCIECAM02Done (h);
+}
+
+static void
+jch_to_xyz (const cmsJCh *jch, cmsCIEXYZ *xyz, const cmsViewingConditions *vc)
+{
+  cmsHANDLE h;
+
+  h = cmsCIECAM02Init (0, vc);
+  cmsCIECAM02Reverse (h, jch, xyz);
+  cmsCIECAM02Done (h);
+}
+
+static void
+jch_to_jab (const cmsJCh *jch, lcmsJab_t *jab, double FL, double c1, double c2)
+{
+  double Mp = 43.86 * log (1.0 + c2 * (jch->C * sqrt (sqrt (FL))));
+  jab->J = 1.7 * jch->J / (1.0 + (c1 * jch->J));
+  jab->a = Mp * cos (deg2rad (jch->h));
+  jab->b = Mp * sin (deg2rad (jch->h));
+}
+
+static void
+jab_to_jch (const lcmsJab_t *jab, cmsJCh *jch, double FL, double c1, double c2)
+{
+  jch->J = jab->J / (1.0 + c1 * (100.0 - jab->J));
+  jch->h = atan2 (jab->b, jab->a);
+  double Mp = sqrt (jab->a * jab->a + jab->b * jab->b);
+  jch->h = rad2deg (jch->h);
+  if (jch->h < 0.0)
+    jch->h += 360.0;
+  jch->C = (exp (c2 * Mp) - 1) / (c2 * sqrt (sqrt (FL)));
+}
+
+DEFUN ("lcms-xyz->jch", Flcms_xyz_to_jch, Slcms_xyz_to_jch, 1, 3, 0,
+       doc: /* Convert CIE CAM02 JCh to CIE XYZ.
+COLOR is a list (X Y Z), with Y scaled about unity.
+Optional arguments WHITEPOINT and VIEW are the same as in `lcms-cam02-ucs',
+which see.  */)
+  (Lisp_Object color, Lisp_Object whitepoint, Lisp_Object view)
+{
+  cmsViewingConditions vc;
+  cmsJCh jch;
+  cmsCIEXYZ xyz, xyzw;
+
+#ifdef WINDOWSNT
+  if (!lcms_initialized)
+    lcms_initialized = init_lcms_functions ();
+  if (!lcms_initialized)
+    {
+      message1 ("lcms2 library not found");
+      return Qnil;
+    }
+#endif
+
+  if (!(CONSP (color) && parse_xyz_list (color, &xyz)))
+    signal_error ("Invalid color", color);
+  if (NILP (whitepoint))
+    xyzw = illuminant_d65;
+  else if (!(CONSP (whitepoint) && parse_xyz_list (whitepoint, &xyzw)))
+    signal_error ("Invalid white point", whitepoint);
+  if (NILP (view))
+    default_viewing_conditions (&xyzw, &vc);
+  else if (!(CONSP (view) && parse_viewing_conditions (view, &xyzw, &vc)))
+    signal_error ("Invalid viewing conditions", view);
+
+  xyz_to_jch(&xyz, &jch, &vc);
+  return list3 (make_float (jch.J), make_float (jch.C), make_float (jch.h));
+}
+
+DEFUN ("lcms-jch->xyz", Flcms_jch_to_xyz, Slcms_jch_to_xyz, 1, 3, 0,
+       doc: /* Convert CIE XYZ to CIE CAM02 JCh.
+COLOR is a list (J C h), where lightness of white is equal to 100, and hue
+is given in degrees.
+Optional arguments WHITEPOINT and VIEW are the same as in `lcms-cam02-ucs',
+which see.  */)
+  (Lisp_Object color, Lisp_Object whitepoint, Lisp_Object view)
+{
+  cmsViewingConditions vc;
+  cmsJCh jch;
+  cmsCIEXYZ xyz, xyzw;
+
+#ifdef WINDOWSNT
+  if (!lcms_initialized)
+    lcms_initialized = init_lcms_functions ();
+  if (!lcms_initialized)
+    {
+      message1 ("lcms2 library not found");
+      return Qnil;
+    }
+#endif
+
+  if (!(CONSP (color) && parse_jch_list (color, &jch)))
+    signal_error ("Invalid color", color);
+  if (NILP (whitepoint))
+    xyzw = illuminant_d65;
+  else if (!(CONSP (whitepoint) && parse_xyz_list (whitepoint, &xyzw)))
+    signal_error ("Invalid white point", whitepoint);
+  if (NILP (view))
+    default_viewing_conditions (&xyzw, &vc);
+  else if (!(CONSP (view) && parse_viewing_conditions (view, &xyzw, &vc)))
+    signal_error ("Invalid viewing conditions", view);
+
+  jch_to_xyz(&jch, &xyz, &vc);
+  return list3 (make_float (xyz.X / 100.0),
+                make_float (xyz.Y / 100.0),
+                make_float (xyz.Z / 100.0));
+}
+
+DEFUN ("lcms-jch->jab", Flcms_jch_to_jab, Slcms_jch_to_jab, 1, 3, 0,
+       doc: /* Convert CIE CAM02 JCh to CAM02-UCS J'a'b'.
+COLOR is a list (J C h) as described in `lcms-jch->xyz', which see.
+Optional arguments WHITEPOINT and VIEW are the same as in `lcms-cam02-ucs',
+which see.  */)
+  (Lisp_Object color, Lisp_Object whitepoint, Lisp_Object view)
+{
+  cmsViewingConditions vc;
+  lcmsJab_t jab;
+  cmsJCh jch;
+  cmsCIEXYZ xyzw;
+  double FL, k, k4;
+
+#ifdef WINDOWSNT
+  if (!lcms_initialized)
+    lcms_initialized = init_lcms_functions ();
+  if (!lcms_initialized)
+    {
+      message1 ("lcms2 library not found");
+      return Qnil;
+    }
+#endif
+
+  if (!(CONSP (color) && parse_jch_list (color, &jch)))
+    signal_error ("Invalid color", color);
+  if (NILP (whitepoint))
+    xyzw = illuminant_d65;
+  else if (!(CONSP (whitepoint) && parse_xyz_list (whitepoint, &xyzw)))
+    signal_error ("Invalid white point", whitepoint);
+  if (NILP (view))
+    default_viewing_conditions (&xyzw, &vc);
+  else if (!(CONSP (view) && parse_viewing_conditions (view, &xyzw, &vc)))
+    signal_error ("Invalid viewing conditions", view);
+
+  k = 1.0 / (1.0 + (5.0 * vc.La));
+  k4 = k * k * k * k;
+  FL = vc.La * k4 + 0.1 * (1 - k4) * (1 - k4) * cbrt (5.0 * vc.La);
+  jch_to_jab (&jch, &jab, FL, 0.007, 0.0228);
+  return list3 (make_float (jab.J), make_float (jab.a), make_float (jab.b));
+}
+
+DEFUN ("lcms-jab->jch", Flcms_jab_to_jch, Slcms_jab_to_jch, 1, 3, 0,
+       doc: /* Convert CAM02-UCS J'a'b' to CIE CAM02 JCh.
+COLOR is a list (J' a' b'), where white corresponds to lightness J equal to 100.
+Optional arguments WHITEPOINT and VIEW are the same as in `lcms-cam02-ucs',
+which see.  */)
+  (Lisp_Object color, Lisp_Object whitepoint, Lisp_Object view)
+{
+  cmsViewingConditions vc;
+  cmsJCh jch;
+  lcmsJab_t jab;
+  cmsCIEXYZ xyzw;
+  double FL, k, k4;
+
+#ifdef WINDOWSNT
+  if (!lcms_initialized)
+    lcms_initialized = init_lcms_functions ();
+  if (!lcms_initialized)
+    {
+      message1 ("lcms2 library not found");
+      return Qnil;
+    }
+#endif
+
+  if (!(CONSP (color) && parse_jab_list (color, &jab)))
+    signal_error ("Invalid color", color);
+  if (NILP (whitepoint))
+    xyzw = illuminant_d65;
+  else if (!(CONSP (whitepoint) && parse_xyz_list (whitepoint, &xyzw)))
+    signal_error ("Invalid white point", whitepoint);
+  if (NILP (view))
+    default_viewing_conditions (&xyzw, &vc);
+  else if (!(CONSP (view) && parse_viewing_conditions (view, &xyzw, &vc)))
+    signal_error ("Invalid viewing conditions", view);
+
+  k = 1.0 / (1.0 + (5.0 * vc.La));
+  k4 = k * k * k * k;
+  FL = vc.La * k4 + 0.1 * (1 - k4) * (1 - k4) * cbrt (5.0 * vc.La);
+  jab_to_jch (&jab, &jch, FL, 0.007, 0.0228);
+  return list3 (make_float (jch.J), make_float (jch.C), make_float (jch.h));
+}
+
 /* References:
    Li, Luo et al. "The CRI-CAM02UCS colour rendering index." COLOR research
    and application, 37 No.3, 2012.
@@ -239,10 +484,9 @@ The default viewing conditions are (20 100 1 1).  */)
 {
   cmsViewingConditions vc;
   cmsJCh jch1, jch2;
-  cmsHANDLE h1, h2;
   cmsCIEXYZ xyz1, xyz2, xyzw;
-  double Jp1, ap1, bp1, Jp2, ap2, bp2;
-  double Mp1, Mp2, FL, k, k4;
+  lcmsJab_t jab1, jab2;
+  double FL, k, k4;
 
 #ifdef WINDOWSNT
   if (!lcms_initialized)
@@ -267,41 +511,18 @@ The default viewing conditions are (20 100 1 1).  */)
   else if (!(CONSP (view) && parse_viewing_conditions (view, &xyzw, &vc)))
     signal_error ("Invalid view conditions", view);
 
-  h1 = cmsCIECAM02Init (0, &vc);
-  h2 = cmsCIECAM02Init (0, &vc);
-  cmsCIECAM02Forward (h1, &xyz1, &jch1);
-  cmsCIECAM02Forward (h2, &xyz2, &jch2);
-  cmsCIECAM02Done (h1);
-  cmsCIECAM02Done (h2);
+  xyz_to_jch (&xyz1, &jch1, &vc);
+  xyz_to_jch (&xyz2, &jch2, &vc);
 
-  /* Now have colors in JCh, need to calculate J'a'b'
-
-     M = C * F_L^0.25
-     J' = 1.7 J / (1 + 0.007 J)
-     M' = 43.86 ln(1 + 0.0228 M)
-     a' = M' cos(h)
-     b' = M' sin(h)
-
-     where
-
-     F_L = 0.2 k^4 (5 L_A) + 0.1 (1 - k^4)^2 (5 L_A)^(1/3),
-     k = 1/(5 L_A + 1)
-  */
   k = 1.0 / (1.0 + (5.0 * vc.La));
   k4 = k * k * k * k;
   FL = vc.La * k4 + 0.1 * (1 - k4) * (1 - k4) * cbrt (5.0 * vc.La);
-  Mp1 = 43.86 * log (1.0 + 0.0228 * (jch1.C * sqrt (sqrt (FL))));
-  Mp2 = 43.86 * log (1.0 + 0.0228 * (jch2.C * sqrt (sqrt (FL))));
-  Jp1 = 1.7 * jch1.J / (1.0 + (0.007 * jch1.J));
-  Jp2 = 1.7 * jch2.J / (1.0 + (0.007 * jch2.J));
-  ap1 = Mp1 * cos (deg2rad (jch1.h));
-  ap2 = Mp2 * cos (deg2rad (jch2.h));
-  bp1 = Mp1 * sin (deg2rad (jch1.h));
-  bp2 = Mp2 * sin (deg2rad (jch2.h));
+  jch_to_jab (&jch1, &jab1, FL, 0.007, 0.0228);
+  jch_to_jab (&jch2, &jab2, FL, 0.007, 0.0228);
 
-  return make_float (sqrt ((Jp2 - Jp1) * (Jp2 - Jp1) +
-                           (ap2 - ap1) * (ap2 - ap1) +
-                           (bp2 - bp1) * (bp2 - bp1)));
+  return make_float (sqrt ((jab2.J - jab1.J) * (jab2.J - jab1.J) +
+                           (jab2.a - jab1.a) * (jab2.a - jab1.a) +
+                           (jab2.b - jab1.b) * (jab2.b - jab1.b)));
 }
 
 DEFUN ("lcms-temp->white-point", Flcms_temp_to_white_point, Slcms_temp_to_white_point, 1, 1, 0,
@@ -359,6 +580,10 @@ void
 syms_of_lcms2 (void)
 {
   defsubr (&Slcms_cie_de2000);
+  defsubr (&Slcms_xyz_to_jch);
+  defsubr (&Slcms_jch_to_xyz);
+  defsubr (&Slcms_jch_to_jab);
+  defsubr (&Slcms_jab_to_jch);
   defsubr (&Slcms_cam02_ucs);
   defsubr (&Slcms2_available_p);
   defsubr (&Slcms_temp_to_white_point);
diff --git a/src/lcms.h b/src/lcms.h
new file mode 100644
index 0000000000..6080de06ca
--- /dev/null
+++ b/src/lcms.h
@@ -0,0 +1,30 @@
+/* Definitions for data structures and routines for the
+   interface to Little CMS
+   Copyright (C) 2017 Free Software Foundation, Inc.
+
+This file is part of GNU Emacs.
+
+GNU Emacs is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or (at
+your option) any later version.
+
+GNU Emacs is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
+
+#ifndef _LCMS_H
+#define _LCMS_H 1
+
+typedef struct
+{
+  double J;
+  double a;
+  double b;
+} lcmsJab_t;
+
+#endif /* lcms.h */
diff --git a/test/src/lcms-tests.el b/test/src/lcms-tests.el
index d6d1d16b9a..cc324af68b 100644
--- a/test/src/lcms-tests.el
+++ b/test/src/lcms-tests.el
@@ -94,6 +94,38 @@ lcms-rgb255->xyz
     (apply #'color-xyz-to-xyy (lcms-temp->white-point 7504))
     '(0.29902 0.31485 1.0))))
 
+(ert-deftest lcms-roundtrip ()
+  "Test accuracy of converting to and from different color spaces"
+  (skip-unless (featurep 'lcms2))
+  (should
+   (let ((color '(.5 .3 .7)))
+     (lcms-triple-approx-p (lcms-jch->xyz (lcms-xyz->jch color))
+                           color
+                           0.0001)))
+  (should
+   (let ((color '(.8 -.2 .2)))
+     (lcms-triple-approx-p (lcms-jch->jab (lcms-jab->jch color))
+                           color
+                           0.0001))))
+
+(ert-deftest lcms-ciecam02-gold ()
+  "Test CIE CAM02 JCh gold values"
+  (skip-unless (featurep 'lcms2))
+  (should
+   (lcms-triple-approx-p
+    (lcms-xyz->jch '(0.1931 0.2393 0.1014)
+                   '(0.9888 0.900 0.3203)
+                   '(18 200 1 1.0))
+    '(48.0314 38.7789 191.0452)
+    0.02))
+  (should
+   (lcms-triple-approx-p
+    (lcms-xyz->jch '(0.1931 0.2393 0.1014)
+                   '(0.9888 0.90 0.3203)
+                   '(18 20 1 1.0))
+    '(47.6856 36.0527 185.3445)
+    0.09)))
+
 (ert-deftest lcms-dE-cam02-ucs-silver ()
   "Test CRI-CAM02-UCS deltaE metric values from colorspacious."
   (skip-unless (featurep 'lcms2))
@@ -114,4 +146,16 @@ lcms-rgb255->xyz
     8.503323264883667
     0.04)))
 
+(ert-deftest lcms-jmh->cam02-ucs-silver ()
+  "Compare JCh conversion to CAM02-UCS to values from colorspacious."
+  (skip-unless (featurep 'lcms2))
+  (should
+   (lcms-triple-approx-p (lcms-jch->jab '(50 20 10))
+                         '(62.96296296 16.22742674 2.86133316)
+                         0.05))
+  (should
+   (lcms-triple-approx-p (lcms-jch->jab '(10 60 100))
+                         '(15.88785047 -6.56546789 37.23461867)
+                         0.04)))
+
 ;;; lcms-tests.el ends here
-- 
2.14.2

Re: [PATCH] lcms2 (was Re: Emacs 26.1 release branch created)

[Eli Zaretskii]

> Date: Fri, 29 Sep 2017 16:25:40 -0400
> From: Mark Oteiza <mvoteiza@udel.edu>
> Cc: emacs-devel@gnu.org
> 
> Here is the patch I thought I would not get done.

Thanks, it looks good (didn't try to build it, though).

> * src/lcms.h: New file.

Not sure why you needed a header file.  Do you envision the struct
defined in it to be used elsewhere in Emacs sources?  If not, you can
define the struct in lcms.c instead.

> +static void
> +jch_to_xyz (const cmsJCh *jch, cmsCIEXYZ *xyz, const cmsViewingConditions *vc)
> +{
> +  cmsHANDLE h;
> +
> +  h = cmsCIECAM02Init (0, vc);
> +  cmsCIECAM02Reverse (h, jch, xyz);
> +  cmsCIECAM02Done (h);
> +}

cmsCIECAM02Reverse was not used previously, so it will have to be
added to the WINDOWSNT parts.  Let me know if you want me to send a
patch for that.

> +  double Mp = sqrt (jab->a * jab->a + jab->b * jab->b);

I'd use 'hypot' here, it's supposed to be more accurate and avoids
overflow/underflow for large or small a and b.  Or are we sure a and b
are always confined to some small range of values?

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, Eli.

On Sat, Sep 16, 2017 at 15:56:02 +0300, Eli Zaretskii wrote:
> I've created a new emacs-26 branch which will be used to release Emacs
> 26.x, starting with Emacs 26.1.  This branch should be used for fixing
> bugs; new development should continue on master.  (If there are
> features that are already on the branch, and their developers want to
> put a few finishing touches or additions to those features, please ask
> here before pushing further changes that are not bugfixes.)

Thanks.  This is good progress.

> Alan, you will probably want to cherry-pick your latest commit from
> master master to this branch.

I've actually not committed it yet (that's the fix of syntax-ppss).
When I do (very soon) I will commit to the Emacs 26 branch.

Thanks for the notice.

> Nicolas, please produce the first pretest in, say, a week's time.
> Let's optimistically call that pretest 26.0.90.

> Thanks.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[Rasmus]

Hi,

> I've created a new emacs-26 branch which will be used to release Emacs
> 26.x, starting with Emacs 26.1.  This branch should be used for fixing
> bugs; new development should continue on master.  (If there are
> features that are already on the branch, and their developers want to
> put a few finishing touches or additions to those features, please ask
> here before pushing further changes that are not bugfixes.)

That sounds great.

If possible, I would like to add the new version of Org, v9.1.  It is a
fairly modest update compared to v9.0.

Would it be OK to aim for including 9.1 in 26.1?

Thanks,
Rasmus

-- 
Hooray!

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> From: Rasmus <rasmus@gmx.us>
> Date: Sat, 16 Sep 2017 19:05:21 +0200
> 
> Would it be OK to aim for including 9.1 in 26.1?

If you consider it to be stable enough, then yes.

Thanks.

Re: Emacs 26.1 release branch created

[Rasmus]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Rasmus <rasmus@gmx.us>
>> Date: Sat, 16 Sep 2017 19:05:21 +0200
>> 
>> Would it be OK to aim for including 9.1 in 26.1?
>
> If you consider it to be stable enough, then yes.

It is considered stable.

Aside: what would be the "correct" or "best" procedure to update Org it in
both the master branch and the emacs-26?  E.g. should I commit it to
master and then cherry pick it into the emacs-26 branch?

Thanks,
Rasmus

-- 
Governments should be afraid of their people

Re: Emacs 26.1 release branch created

[Rasmus]

Rasmus <rasmus@gmx.us> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> From: Rasmus <rasmus@gmx.us>
>>> Date: Sat, 16 Sep 2017 19:05:21 +0200
>>> 
>>> Would it be OK to aim for including 9.1 in 26.1?
>>
>> If you consider it to be stable enough, then yes.
>
> It is considered stable.
>
> Aside: what would be the "correct" or "best" procedure to update Org it in
> both the master branch and the emacs-26?  E.g. should I commit it to
> master and then cherry pick it into the emacs-26 branch?

I found the answer in another thread: commit to emacs-26, which is then
eventually merged with master.

Thanks,
Rasmus

-- 
It was you, Jezebel, it was you

Re: Emacs 26.1 release branch created

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 897 bytes --]

On Mon, Sep 18, 2017, 5:47 AM Rasmus <rasmus@gmx.us> wrote:

> Rasmus <rasmus@gmx.us> writes:
>
> > Eli Zaretskii <eliz@gnu.org> writes:
> >
> >>> From: Rasmus <rasmus@gmx.us>
> >>> Date: Sat, 16 Sep 2017 19:05:21 +0200
> >>>
> >>> Would it be OK to aim for including 9.1 in 26.1?
> >>
> >> If you consider it to be stable enough, then yes.
> >
> > It is considered stable.
> >
> > Aside: what would be the "correct" or "best" procedure to update Org it
> in
> > both the master branch and the emacs-26?  E.g. should I commit it to
> > master and then cherry pick it into the emacs-26 branch?
>
> I found the answer in another thread: commit to emacs-26, which is then
> eventually merged with master.
>

Thanks for doing this!

It will be awesome to see the brand new Org (now 9.1.1) in the emacs 26.1
RC.

May be @Nicolas can wait for this merge before cutting the first RC?

> --

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1752 bytes --]

Re: Emacs 26.1 release branch created

[Nicolas Petton]

[-- Attachment #1: Type: text/plain, Size: 206 bytes --]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> May be @Nicolas can wait for this merge before cutting the first RC?

I could, but I'm not there yet, the first pretest is not even out yet :)

Cheers,
Nico

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: Emacs 26.1 release branch created

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 331 bytes --]

On Wed, Sep 20, 2017, 7:59 AM Nicolas Petton <nicolas@petton.fr> wrote:

> Kaushal Modi <kaushal.modi@gmail.com> writes:
>
> > May be @Nicolas can wait for this merge before cutting the first RC?
>
> I could, but I'm not there yet, the first pretest is not even out yet :)
>

Oops! I meant the pretest, not RC.

> --

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 914 bytes --]

Re: Emacs 26.1 release branch created

[Rasmus]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> On Mon, Sep 18, 2017, 5:47 AM Rasmus <rasmus@gmx.us> wrote:
>
>> Rasmus <rasmus@gmx.us> writes:
>>
>> > Eli Zaretskii <eliz@gnu.org> writes:
>> >
>> >>> From: Rasmus <rasmus@gmx.us>
>> >>> Date: Sat, 16 Sep 2017 19:05:21 +0200
>> >>>
>> >>> Would it be OK to aim for including 9.1 in 26.1?
>> >>
>> >> If you consider it to be stable enough, then yes.
>> >
>> > It is considered stable.
>> >
>> > Aside: what would be the "correct" or "best" procedure to update Org it
>> in
>> > both the master branch and the emacs-26?  E.g. should I commit it to
>> > master and then cherry pick it into the emacs-26 branch?
>>
>> I found the answer in another thread: commit to emacs-26, which is then
>> eventually merged with master.
>>
>
> Thanks for doing this!
>
> It will be awesome to see the brand new Org (now 9.1.1) in the emacs 26.1
> RC.

Org 9.1.1 in the emacs.git scratch/org-mode-merge branch.

Kyle spotted some mistakes, but /hopefully/ there shouldn’t be any more
now...

I would like to figure out about the issue with "num" that you pointed out
on the Org list before merging.

Rasmus

-- 
To err is human. To screw up 10⁶ times per second, you need a computer

Re: Emacs 26.1 release branch created

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 650 bytes --]

On Wed, Sep 20, 2017, 8:17 AM Rasmus <rasmus@gmx.us> wrote:

>
> Org 9.1.1 in the emacs.git scratch/org-mode-merge branch.
>
> Kyle spotted some mistakes, but /hopefully/ there shouldn’t be any more
> now...
>

Thanks.

I would like to figure out about the issue with "num" that you pointed out
> on the Org list before merging.
>

Thankfully, as would be expected of such a major change, that is only on
the master[1] branch of Org, and not maint. So this merge to emacs-26
branch should be unaffected.

[1]:
http://orgmode.org/cgit.cgi/org-mode.git/commit/?id=bd2378161e76932103c9ef1f8343ffcc0d275007

> --

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1461 bytes --]

Re: Emacs 26.1 release branch created

[Rasmus]

Hi,

Kaushal Modi <kaushal.modi@gmail.com> writes:

> Thankfully, as would be expected of such a major change, that is only on
> the master[1] branch of Org, and not maint. So this merge to emacs-26
> branch should be unaffected.

I realize I must have misunderstood the issue.  Thanks.

Rasmus

-- 
There are known knowns; there are things we know that we know

Re: Emacs 26.1 release branch created

[Nicolas Petton]

[-- Attachment #1: Type: text/plain, Size: 180 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

> Nicolas, please produce the first pretest in, say, a week's time.
> Let's optimistically call that pretest 26.0.90.

Will do!

Cheers,
Nico

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: Emacs 26.1 release branch created

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> I've created a new emacs-26 branch which will be used to release Emacs
> 26.x, starting with Emacs 26.1. 

Yay!

What will the version number on master be now?  27.0.50 or (err)
26.1.50?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: emacs-devel@gnu.org,  Nicolas Petton <nicolas@petton.fr>,  Alan Mackenzie <acm@muc.de>
> Date: Sat, 16 Sep 2017 21:54:23 +0200
> 
> What will the version number on master be now?  27.0.50 or (err)
> 26.1.50?

It already is: 27.0.50.

Re: Emacs 26.1 release branch created

[Alan Third]

On Sat, Sep 16, 2017 at 03:56:02PM +0300, Eli Zaretskii wrote:
> I've created a new emacs-26 branch which will be used to release Emacs
> 26.x, starting with Emacs 26.1.  This branch should be used for fixing
> bugs; new development should continue on master.  (If there are
> features that are already on the branch, and their developers want to
> put a few finishing touches or additions to those features, please ask
> here before pushing further changes that are not bugfixes.)

I have a change that I’d like included in Emacs 26, but I don’t know
if it fits the criteria. We don’t have a bug report for it, but I
consider two‐finger scrolling on mac trackpads to be broken. I’ve got
a patch for it:

https://lists.gnu.org/archive/html/emacs-devel/2017-09/msg00482.html

but have I missed my chance?

(I forgot to CC you into the original email)
-- 
Alan Third

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> Date: Mon, 18 Sep 2017 17:22:29 +0100
> From: Alan Third <alan@idiocy.org>
> Cc: emacs-devel@gnu.org
> 
> I have a change that I’d like included in Emacs 26, but I don’t know
> if it fits the criteria. We don’t have a bug report for it, but I
> consider two‐finger scrolling on mac trackpads to be broken. I’ve got
> a patch for it:
> 
> https://lists.gnu.org/archive/html/emacs-devel/2017-09/msg00482.html
> 
> but have I missed my chance?

Please go ahead and push to emacs-26.

Thanks.

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, John and Eli.

On Sat, Sep 16, 2017 at 15:56:02 +0300, Eli Zaretskii wrote:
> I've created a new emacs-26 branch which will be used to release Emacs
> 26.x, starting with Emacs 26.1.  This branch should be used for fixing
> bugs; new development should continue on master.  (If there are
> features that are already on the branch, and their developers want to
> put a few finishing touches or additions to those features, please ask
> here before pushing further changes that are not bugfixes.)

[ .... ]

> Nicolas, please produce the first pretest in, say, a week's time.
> Let's optimistically call that pretest 26.0.90.

This is rather sudden, leaving not much time for last minute
enhancements.

Can we please have a user option in Emacs 26 to disable curly quote
translation in messages and doc strings?  I am (more than) willing to
implement and document this, and could do so quickly.

> Thanks.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> Date: Tue, 19 Sep 2017 17:35:11 +0000
> Cc: emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> This is rather sudden, leaving not much time for last minute
> enhancements.

Is it necessarily bad?

> Can we please have a user option in Emacs 26 to disable curly quote
> translation in messages and doc strings?

I thought we already had that: text-quoting-style.

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, Eli.

On Tue, Sep 19, 2017 at 20:54:16 +0300, Eli Zaretskii wrote:
> > Date: Tue, 19 Sep 2017 17:35:11 +0000
> > Cc: emacs-devel@gnu.org
> > From: Alan Mackenzie <acm@muc.de>

> > This is rather sudden, leaving not much time for last minute
> > enhancements.

> Is it necessarily bad?

> > Can we please have a user option in Emacs 26 to disable curly quote
> > translation in messages and doc strings?

> I thought we already had that: text-quoting-style.

It is not a user option, and it is not documented in the Emacs manual,
with the result that anybody who needs it has a far harder time finding
it than she should.

It is also rather complicated, and lacks a prime property that such a
variable should have, namely that nil mean "no translation".

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> Date: Tue, 19 Sep 2017 18:09:45 +0000
> Cc: jwiegley@gmail.com, emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > > Can we please have a user option in Emacs 26 to disable curly quote
> > > translation in messages and doc strings?
> 
> > I thought we already had that: text-quoting-style.
> 
> It is not a user option, and it is not documented in the Emacs manual,
> with the result that anybody who needs it has a far harder time finding
> it than she should.
> 
> It is also rather complicated, and lacks a prime property that such a
> variable should have, namely that nil mean "no translation".

That's okay, because there's still controversy regarding the need for
users to tweak this variable.  Some of use think most users will never
need it (you, obviously, disagree).  Therefore, I think we should
first see how many users actually ask about something like that, and
if it turns out many do, we can make the option more visible and
user-friendly.

So for now, I think we should leave things as they are and wait for
feedback.

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> Date: Tue, 19 Sep 2017 21:34:01 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: jwiegley@gmail.com, emacs-devel@gnu.org
> 
> That's okay, because there's still controversy regarding the need for
> users to tweak this variable.  Some of use think most users will never
                                 ^^^^^^^^^^^
"Some of us", obviously.  Sorry.

Re: Emacs 26.1 release branch created

[Paul Eggert]

[-- Attachment #1: Type: text/plain, Size: 461 bytes --]

On 09/19/2017 11:34 AM, Eli Zaretskii wrote:
> So for now, I think we should leave things as they are and wait for
> feedback.

To address some of Alan's concerns, how about adding a brief note to the 
user manual, in its section "Display Custom" that already says 
"Beginning users can skip [this section]" and that already mentions 
things like tty-suppress-bold-inverse-default-colors that are meant for 
expert users. Something like the attached, perhaps?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Mention-text-quoting-style-in-user-manual.patch --]
[-- Type: text/x-patch; name="0001-Mention-text-quoting-style-in-user-manual.patch", Size: 1530 bytes --]

From dab4b8b8fe444412ac017278ee4c801f2fe6fb24 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Tue, 19 Sep 2017 12:08:37 -0700
Subject: [PATCH] Mention text-quoting-style in user manual

* doc/emacs/display.texi (Display Custom):
Document text-quoting-style, briefly.
Lack of documentation noted by Alan Mackenzie in:
http://lists.gnu.org/archive/html/emacs-devel/2017-09/msg00632.html
---
 doc/emacs/display.texi | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 2aa79e1161..878632692e 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -1839,6 +1839,15 @@ Display Custom
 @code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil}
 argument to suppress the effect of bold-face in this case.
 
+@vindex text-quoting-style
+  Emacs infers how to quote in messages, help and info by examining
+its environment.  By default, Emacs quotes @t{‘like this’} with curved
+single quotes if displayable, and @t{`like this'} with grave accent
+and apostrophe otherwise.  If the default does not work for you, you
+can override it by setting the variable @code{text-quoting-style}.
+@xref{Keys in Documentation,, Substituting Key Bindings in
+Documentation, elisp, The GNU Emacs Lisp Reference Manual}.
+
 @vindex display-raw-bytes-as-hex
   Raw bytes are displayed in octal format by default, for example a
 byte with a decimal value of 128 is displayed as @code{\200}.  To
-- 
2.13.5

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, Paul.

On Tue, Sep 19, 2017 at 12:11:02 -0700, Paul Eggert wrote:
> On 09/19/2017 11:34 AM, Eli Zaretskii wrote:
> > So for now, I think we should leave things as they are and wait for
> > feedback.

A few days ago, somebody on the help list complained that his quotes
were being messed up in help messages.  Eli answered him by explaining
about curly quotes, and what Emacs does with ASCII quotes.  That much is
not in the manual.

> To address some of Alan's concerns, how about adding a brief note to the 
> user manual, in its section "Display Custom" that already says 
> "Beginning users can skip [this section]" and that already mentions 
> things like tty-suppress-bold-inverse-default-colors that are meant for 
> expert users. Something like the attached, perhaps?

No, nothing like the attached.  I doubt you'll be surprised at all, but
that fails to address my concerns.

My main concern at the moment is my belief that you have been and are
attempting to maximise the difficulty faced by Emacs users in disabling
curly quotes.  I would appreciate clarification on this point.  I would
appreciate even more a clear statement that this isn't the case, and
that you will work together with me to make it as easy as possible for
users who might so wish to disable substitution of ` and ' by curly
quotes.


> >>From dab4b8b8fe444412ac017278ee4c801f2fe6fb24 Mon Sep 17 00:00:00 2001
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Tue, 19 Sep 2017 12:08:37 -0700
> Subject: [PATCH] Mention text-quoting-style in user manual

> * doc/emacs/display.texi (Display Custom):
> Document text-quoting-style, briefly.
> Lack of documentation noted by Alan Mackenzie in:
> http://lists.gnu.org/archive/html/emacs-devel/2017-09/msg00632.html
> ---
>  doc/emacs/display.texi | 9 +++++++++
>  1 file changed, 9 insertions(+)

> diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
> index 2aa79e1161..878632692e 100644
> --- a/doc/emacs/display.texi
> +++ b/doc/emacs/display.texi
> @@ -1839,6 +1839,15 @@ Display Custom
>  @code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil}
>  argument to suppress the effect of bold-face in this case.

> +@vindex text-quoting-style
> +  Emacs infers how to quote in messages, help and info by examining
> +its environment.  By default, Emacs quotes @t{???like this???} with curved
> +single quotes if displayable, and @t{`like this'} with grave accent
> +and apostrophe otherwise.  If the default does not work for you, you
> +can override it by setting the variable @code{text-quoting-style}.
> +@xref{Keys in Documentation,, Substituting Key Bindings in
> +Documentation, elisp, The GNU Emacs Lisp Reference Manual}.
> +
>  @vindex display-raw-bytes-as-hex
>    Raw bytes are displayed in octal format by default, for example a
>  byte with a decimal value of 128 is displayed as @code{\200}.  To
> -- 
> 2.13.5

-- 
Alan Mackenzie (Nuremberg, Germany).

About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 598 bytes --]

On Tue, Sep 19, 2017 at 3:50 PM Alan Mackenzie <acm@muc.de> wrote:

> Hello, Paul.
>
> On Tue, Sep 19, 2017 at 12:11:02 -0700, Paul Eggert wrote:
> > On 09/19/2017 11:34 AM, Eli Zaretskii wrote:
> > > So for now, I think we should leave things as they are and wait for
> > > feedback.
>
> A few days ago, somebody on the help list complained that his quotes
> were being messed up in help messages.  Eli answered him by explaining
> about curly quotes, and what Emacs does with ASCII quotes.  That much is
> not in the manual.
>

FWIW I am one of the happy users of curly quotes.
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1011 bytes --]

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Alan Mackenzie]

Hello, Kaushal.

On Tue, Sep 19, 2017 at 20:54:47 +0000, Kaushal Modi wrote:


> FWIW I am one of the happy users of curly quotes.

That's great!  I've no problem with that.

What I do have a problem with is that normal users don't get to chose.
They have curly quotes foisted on them whether they want them or not.
The only way to disable them, setting text-quoting-style, you are
darkly, and unnecessarily, warned against using by the sentence in
Emacs-25 NEWS which says "As the variable is not intended for casual
use, it is not a user option."

Can you think of any reason why text-quoting-style isn't suitable for
"casual use", whatever that is?  No?  Neither can I.

> -- 

> Kaushal Modi

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[John Wiegley]

>>>>> Alan Mackenzie <acm@muc.de> writes:

> Can you think of any reason why text-quoting-style isn't suitable for
> "casual use", whatever that is? No? Neither can I.

I vaguely recall a discussion from 1.5 years ago where it was decided that it
*should* be a user configurable option, since many of us dislike curly quotes
and there is no reason we shouldn't be able to easily turn them off.

So, unless someone has a reason to offer, I'd like to make this configurable
in 26.1.

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

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Paul Eggert]

John Wiegley wrote:
> I vaguely recall a discussion from 1.5 years ago where it was decided that it
> *should*  be a user configurable option

I found that discussion here:

https://debbugs.gnu.org/23372

and it concluded with your agreeing that there was no need for a defcustom in 
25.1, and that we could wait until after 25.1 was out and then see whether a lot 
of Emacs users were unhappy with the situation.

Again, I don't care whether it's a defcustom. You and Eli get to decide (not me, 
thank goodness :-).

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Marcin Borkowski]

On 2017-09-20, at 01:33, John Wiegley <jwiegley@gmail.com> wrote:

>>>>>> Alan Mackenzie <acm@muc.de> writes:
>
>> Can you think of any reason why text-quoting-style isn't suitable for
>> "casual use", whatever that is? No? Neither can I.
>
> I vaguely recall a discussion from 1.5 years ago where it was decided that it
> *should* be a user configurable option, since many of us dislike curly quotes
> and there is no reason we shouldn't be able to easily turn them off.
>
> So, unless someone has a reason to offer, I'd like to make this configurable
> in 26.1.

+1

And for the matter, I'm one of the persons which does not like curl
quotes (they broke isearching for keys in Info, didn't they?)

-- 
Marcin Borkowski

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Noam Postavsky]

On Wed, Sep 20, 2017 at 12:16 AM, Marcin Borkowski <mbork@mbork.pl> wrote:

> And for the matter, I'm one of the persons which does not like curl
> quotes (they broke isearching for keys in Info, didn't they?)

FYI, the curly quotes in info are produced by makeinfo, not Emacs, so
text-quoting-style will not affect them. If you use makeinfo 4.13 then
you won't get them. Also note this entry in NEWS.25:

    *** 'isearch' and 'query-replace' can now perform character folding[...]
    For instance, the ASCII double quote character " will match all
    variants of double quotes[...]
    Character folding is enabled by customizing 'search-default-mode' to
    the value 'char-fold-to-regexp'.  You can also toggle character
    folding in the middle of a search by typing 'M-s ''.

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Marcin Borkowski]

On 2017-09-20, at 08:17, Noam Postavsky <npostavs@users.sourceforge.net> wrote:

> On Wed, Sep 20, 2017 at 12:16 AM, Marcin Borkowski <mbork@mbork.pl> wrote:
>
>> And for the matter, I'm one of the persons which does not like curl
>> quotes (they broke isearching for keys in Info, didn't they?)
>
> FYI, the curly quotes in info are produced by makeinfo, not Emacs, so
> text-quoting-style will not affect them. If you use makeinfo 4.13 then
> you won't get them. Also note this entry in NEWS.25:
>
>     *** 'isearch' and 'query-replace' can now perform character folding[...]
>     For instance, the ASCII double quote character " will match all
>     variants of double quotes[...]
>     Character folding is enabled by customizing 'search-default-mode' to
>     the value 'char-fold-to-regexp'.  You can also toggle character
>     folding in the middle of a search by typing 'M-s ''.

Thanks, I'll check it.

Still, the _default_ behavior is broken here.

Best,

-- 
Marcin Borkowski

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Eli Zaretskii]

> From: Marcin Borkowski <mbork@mbork.pl>
> Date: Sat, 23 Sep 2017 13:18:25 +0200
> Cc: Paul Eggert <eggert@cs.ucla.edu>, John Wiegley <jwiegley@gmail.com>,
> 	Emacs developers <emacs-devel@gnu.org>,
> 	Kaushal Modi <kaushal.modi@gmail.com>,
> 	Alan Mackenzie <acm@muc.de>, Eli Zaretskii <eliz@gnu.org>
> 
> 
> > FYI, the curly quotes in info are produced by makeinfo, not Emacs, so
> > text-quoting-style will not affect them. If you use makeinfo 4.13 then
> > you won't get them. Also note this entry in NEWS.25:
> >
> >     *** 'isearch' and 'query-replace' can now perform character folding[...]
> >     For instance, the ASCII double quote character " will match all
> >     variants of double quotes[...]
> >     Character folding is enabled by customizing 'search-default-mode' to
> >     the value 'char-fold-to-regexp'.  You can also toggle character
> >     folding in the middle of a search by typing 'M-s ''.
> 
> Thanks, I'll check it.
> 
> Still, the _default_ behavior is broken here.

If it's broken, it isn't broken by Emacs, right?

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Marcin Borkowski]

On 2017-09-23, at 14:14, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Marcin Borkowski <mbork@mbork.pl>
>> Date: Sat, 23 Sep 2017 13:18:25 +0200
>> Cc: Paul Eggert <eggert@cs.ucla.edu>, John Wiegley <jwiegley@gmail.com>,
>> 	Emacs developers <emacs-devel@gnu.org>,
>> 	Kaushal Modi <kaushal.modi@gmail.com>,
>> 	Alan Mackenzie <acm@muc.de>, Eli Zaretskii <eliz@gnu.org>
>> 
>> 
>> > FYI, the curly quotes in info are produced by makeinfo, not Emacs, so
>> > text-quoting-style will not affect them. If you use makeinfo 4.13 then
>> > you won't get them. Also note this entry in NEWS.25:
>> >
>> >     *** 'isearch' and 'query-replace' can now perform character folding[...]
>> >     For instance, the ASCII double quote character " will match all
>> >     variants of double quotes[...]
>> >     Character folding is enabled by customizing 'search-default-mode' to
>> >     the value 'char-fold-to-regexp'.  You can also toggle character
>> >     folding in the middle of a search by typing 'M-s ''.
>> 
>> Thanks, I'll check it.
>> 
>> Still, the _default_ behavior is broken here.
>
> If it's broken, it isn't broken by Emacs, right?

Kind of.  If TeXinfo's default is now to use curly braces, can't it be
switched off?  I did not use TeXinfo myself - it must have been the
Emacs' makefile who did this.  If Emacs' makefile orders TeXinfo to use
borked quotes, Emacs itself should turn isearch folding so that I'm able
to look for them in Info buffers, no?  It's a matter of consistency,
isn't it?

Best,

-- 
Marcin Borkowski

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Eli Zaretskii]

> From: Marcin Borkowski <mbork@mbork.pl>
> Cc: npostavs@users.sourceforge.net, eggert@cs.ucla.edu, jwiegley@gmail.com, emacs-devel@gnu.org, kaushal.modi@gmail.com, acm@muc.de
> Date: Sat, 23 Sep 2017 21:40:03 +0200
> 
> >> Still, the _default_ behavior is broken here.
> >
> > If it's broken, it isn't broken by Emacs, right?
> 
> Kind of.  If TeXinfo's default is now to use curly braces, can't it be
> switched off?

No, not unless we customize Texinfo on the lowest level, i.e, the
level of text transformation in texi2any.  Since no other project does
that, I don't recommend that we do it.  In any case, it will only
affect the manuals maintained by the Emacs project -- other Info
manuals will still be using curly quotes.

> If Emacs' makefile orders TeXinfo to use borked quotes, Emacs itself
> should turn isearch folding so that I'm able to look for them in
> Info buffers, no?

We could discuss turning character folding on in Info buffers, yes.
Not sure if people will agree, given the fact that they wanted it off
by default, but feel free to start such a discussion.

> It's a matter of consistency, isn't it?

No, not really.  I, for one, never search for quotes in Info manuals,
I use the index search (which finds symbols much faster).

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Marcin Borkowski]

On 2017-09-24, at 04:46, Eli Zaretskii <eliz@gnu.org> wrote:

>> It's a matter of consistency, isn't it?
>
> No, not really.  I, for one, never search for quotes in Info manuals,
> I use the index search (which finds symbols much faster).

How about searching for (a) key bindings and (b) interactive codes?

Best,

-- 
Marcin Borkowski

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Eli Zaretskii]

On September 25, 2017 2:40:56 PM GMT+01:00, Marcin Borkowski <mbork@mbork.pl> wrote:
> 
> On 2017-09-24, at 04:46, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> >> It's a matter of consistency, isn't it?
> >
> > No, not really.  I, for one, never search for quotes in Info
> manuals,
> > I use the index search (which finds symbols much faster).
> 
> How about searching for (a) key bindings and (b) interactive codes?
> 
> Best,

Key bindings are all indexed. Interactive codes are described in a single section that is indexed. So I guess my answer will be still the same: just use index search.

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Marcin Borkowski]

On 2017-09-25, at 20:57, Eli Zaretskii <eliz@gnu.org> wrote:

>> > No, not really.  I, for one, never search for quotes in Info
>> manuals,
>> > I use the index search (which finds symbols much faster).
>>
>> How about searching for (a) key bindings and (b) interactive codes?
>>
>> Best,
>
> Key bindings are all indexed. Interactive codes are described in a single section that is indexed. So I guess my answer will be still the same: just use index search.

In theory, yes.  But: `C-x <DEL>'.  (Although this is obviously
a bug/omission.)  And the section on interactive codes is really long,
and I search for it often enough that the curly quotes do annoy me.

OTOH, I admit that this is a bit nitpicky.

Best,

--
Marcin Borkowski

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Eli Zaretskii]

> From: Marcin Borkowski <mbork@mbork.pl>
> Cc: emacs-devel@gnu.org, eggert@cs.ucla.edu, npostavs@users.sourceforge.net, jwiegley@gmail.com, kaushal.modi@gmail.com, acm@muc.de
> Date: Tue, 26 Sep 2017 14:39:33 +0200
> 
> >> How about searching for (a) key bindings and (b) interactive codes?
> >>
> >> Best,
> >
> > Key bindings are all indexed. Interactive codes are described in a single section that is indexed. So I guess my answer will be still the same: just use index search.
> 
> In theory, yes.  But: `C-x <DEL>'.

Not sure what is your problem with this" "i C-x DEL RET" finds that
binding nicely.

> (Although this is obviously a bug/omission.)

Is it?

> And the section on interactive codes is really long, and I search
> for it often enough that the curly quotes do annoy me.

Again, not sure what's the problem.  here's what I'd do:

  "i interactive code RET" followed by "C-s ^" (for example)

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Marcin Borkowski]

On 2017-09-29, at 14:22, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Marcin Borkowski <mbork@mbork.pl>
>> Cc: emacs-devel@gnu.org, eggert@cs.ucla.edu, npostavs@users.sourceforge.net, jwiegley@gmail.com, kaushal.modi@gmail.com, acm@muc.de
>> Date: Tue, 26 Sep 2017 14:39:33 +0200
>> 
>> >> How about searching for (a) key bindings and (b) interactive codes?
>> >>
>> >> Best,
>> >
>> > Key bindings are all indexed. Interactive codes are described in a single section that is indexed. So I guess my answer will be still the same: just use index search.
>> 
>> In theory, yes.  But: `C-x <DEL>'.
>
> Not sure what is your problem with this" "i C-x DEL RET" finds that
> binding nicely.

Funny: i C-x DEL RET works, but i C-x <DEL> not.  (OTOH, i C-x <RET>
works again.)

>> (Although this is obviously a bug/omission.)
>
> Is it?

So probably yes, at least an inconsistency (a minor one, I admit).

>> And the section on interactive codes is really long, and I search
>> for it often enough that the curly quotes do annoy me.
>
> Again, not sure what's the problem.  here's what I'd do:
>
>   "i interactive code RET" followed by "C-s ^" (for example)

How about C-s P? ;-)

Best,

-- 
Marcin Borkowski

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Eli Zaretskii]

> From: Marcin Borkowski <mbork@mbork.pl>
> Cc: emacs-devel@gnu.org, eggert@cs.ucla.edu, npostavs@users.sourceforge.net, jwiegley@gmail.com, kaushal.modi@gmail.com, acm@muc.de
> Date: Sat, 30 Sep 2017 09:58:22 +0200
> 
> >> In theory, yes.  But: `C-x <DEL>'.
> >
> > Not sure what is your problem with this" "i C-x DEL RET" finds that
> > binding nicely.
> 
> Funny: i C-x DEL RET works, but i C-x <DEL> not.

"C-x <DEL>" should NOT work.  Key bindings are indexed without the
<..> markup.

> (OTOH, i C-x <RET> works again.)

How do you mean "works"?  Where in the manual does it land you?

> >> (Although this is obviously a bug/omission.)
> >
> > Is it?
> 
> So probably yes, at least an inconsistency (a minor one, I admit).

There was a small number of incorrect index entries for key bindings,
I fixed them now.

> >> And the section on interactive codes is really long, and I search
> >> for it often enough that the curly quotes do annoy me.
> >
> > Again, not sure what's the problem.  here's what I'd do:
> >
> >   "i interactive code RET" followed by "C-s ^" (for example)
> 
> How about C-s P? ;-)

Why would I do something like that?

Anyway, I think we can close this discussion now.

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Marcin Borkowski]

On 2017-09-30, at 10:31, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Marcin Borkowski <mbork@mbork.pl>
>> Cc: emacs-devel@gnu.org, eggert@cs.ucla.edu, npostavs@users.sourceforge.net, jwiegley@gmail.com, kaushal.modi@gmail.com, acm@muc.de
>> Date: Sat, 30 Sep 2017 09:58:22 +0200
>> 
>> >> In theory, yes.  But: `C-x <DEL>'.
>> >
>> > Not sure what is your problem with this" "i C-x DEL RET" finds that
>> > binding nicely.
>> 
>> Funny: i C-x DEL RET works, but i C-x <DEL> not.
>
> "C-x <DEL>" should NOT work.  Key bindings are indexed without the
> <..> markup.
>
>> (OTOH, i C-x <RET> works again.)
>
> How do you mean "works"?  Where in the manual does it land you?
>
>> >> (Although this is obviously a bug/omission.)
>> >
>> > Is it?
>> 
>> So probably yes, at least an inconsistency (a minor one, I admit).
>
> There was a small number of incorrect index entries for key bindings,
> I fixed them now.

Thanks.

>> >> And the section on interactive codes is really long, and I search
>> >> for it often enough that the curly quotes do annoy me.
>> >
>> > Again, not sure what's the problem.  here's what I'd do:
>> >
>> >   "i interactive code RET" followed by "C-s ^" (for example)
>> 
>> How about C-s P? ;-)
>
> Why would I do something like that?

To find the explanation of the interactive code `P'?  (or ‘P’)?

> Anyway, I think we can close this discussion now.

Agreed.

Best,

-- 
Marcin Borkowski

RE: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Drew Adams]

> >>>>>> Alan Mackenzie <acm@muc.de> writes:
> >
> >> Can you think of any reason why text-quoting-style isn't suitable for
> >> "casual use", whatever that is? No? Neither can I.
> >
> > I vaguely recall a discussion from 1.5 years ago where it was decided that
> > it *should* be a user configurable option, since many of us dislike curly
> > quotes and there is no reason we shouldn't be able to easily turn them off.
> >
> > So, unless someone has a reason to offer, I'd like to make this
> > configurable in 26.1.
> 
> +1
> 
> And for the matter, I'm one of the persons which does not like curl
> quotes (they broke isearching for keys in Info, didn't they?)

+1

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Eli Zaretskii]

> From: John Wiegley <jwiegley@gmail.com>
> Cc: Kaushal Modi <kaushal.modi@gmail.com>,  Paul Eggert <eggert@cs.ucla.edu>,  Eli Zaretskii <eliz@gnu.org>,  emacs-devel@gnu.org
> Date: Tue, 19 Sep 2017 16:33:31 -0700
> 
> So, unless someone has a reason to offer, I'd like to make this configurable
> in 26.1.

I gave my reasons.

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[John Wiegley]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

> I gave my reasons.

Reading back on the message thread, I now think more strongly that it should
be a defcustom in 26.1. I don't see why we'd want to remove that defcustom
after providing it, which I believe was your main concern. Enough non-curly
users want it (just on this list), and it seems odd that it's not there.

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

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Eli Zaretskii]

> From: John Wiegley <jwiegley@gmail.com>
> Cc: acm@muc.de,  kaushal.modi@gmail.com,  eggert@cs.ucla.edu,  emacs-devel@gnu.org
> Date: Wed, 20 Sep 2017 07:45:39 -0700
> 
> >>>>> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > I gave my reasons.
> 
> Reading back on the message thread, I now think more strongly that it should
> be a defcustom in 26.1. I don't see why we'd want to remove that defcustom
> after providing it, which I believe was your main concern. Enough non-curly
> users want it (just on this list), and it seems odd that it's not there.

I just don't yet see strong enough reasons to reverse our decision not
to make it a defcustom.

Re: About curly quotes (again) [Was: Emacs 26.1 release branch created]

[Filipp Gunbin]

On 20/09/2017 07:45 -0700, John Wiegley wrote:

> Reading back on the message thread, I now think more strongly that it should
> be a defcustom in 26.1. I don't see why we'd want to remove that defcustom
> after providing it, which I believe was your main concern. Enough non-curly
> users want it (just on this list), and it seems odd that it's not there.

I think there are a lot of users even here, who just silently dislike
curly quotes and do not want to create noise posting about it (which I'm
doing right now).

So +1 for defcustom.

Filipp

Re: Emacs 26.1 release branch created

[Paul Eggert]

Alan Mackenzie wrote:
> No, nothing like the attached.  I doubt you'll be surprised at all, but
> that fails to address my concerns.

That patch was not attempting to address all the concerns you raised, only the 
part where you wrote, "it is not documented in the Emacs manual". The idea of 
the patch was to address concerns where common ground can be found, even if we 
don't agree about everything.

> My main concern at the moment is my belief that you have been and are
> attempting to maximise the difficulty faced by Emacs users in disabling
> curly quotes.

Please don't be concerned about that. Your belief is incorrect. I don't care 
whether text-quoting-style preference is expressed only via setq or also via M-x 
customize. It's currently done only via setq because the previous maintainer 
decided to do it that way in Emacs 25, and because he and the current 
maintainers haven't seen the need to change it since then.

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> Date: Tue, 19 Sep 2017 19:43:56 +0000
> Cc: Eli Zaretskii <eliz@gnu.org>, jwiegley@gmail.com, emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> A few days ago, somebody on the help list complained that his quotes
> were being messed up in help messages.  Eli answered him by explaining
> about curly quotes, and what Emacs does with ASCII quotes.  That much is
> not in the manual.

That problem was due to a faulty font used by the OP, so it had
absolutely nothing to do with curly quotes per se.  The same problem
would have happened with any other non-ASCII character, the quotes
just served as a "canary".

> My main concern at the moment is my belief that you have been and are
> attempting to maximise the difficulty faced by Emacs users in disabling
> curly quotes.

I don't think many users will want to do that.  Until now, the only
voices I heard are from this list, and people here will not have any
difficulty in using a not-so-documented non-defcustom.

One of important principles in Emacs development should be that we
don't revert our decisions too lightly, unless a decision proves to be
a disaster.  And we are not there yet, not by far.

Re: Emacs 26.1 release branch created

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

The display of curly quotes in Emacs is a weirdness.  I think
it is worth documenting in the manual.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> CC: eggert@cs.ucla.edu, jwiegley@gmail.com, eliz@gnu.org,
> 	emacs-devel@gnu.org
> Date: Wed, 20 Sep 2017 09:01:48 -0400
> 
> The display of curly quotes in Emacs is a weirdness.  I think
> it is worth documenting in the manual.

It is already documented -- in the ELisp manual, where similar
transformations in substitute-command-keys etc. are documented.

This thread is about something else -- about a user option that would
disable converting `..' into ‘..’.

Re: Emacs 26.1 release branch created

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > The display of curly quotes in Emacs is a weirdness.  I think
  > > it is worth documenting in the manual.

  > It is already documented -- in the ELisp manual, where similar
  > transformations in substitute-command-keys etc. are documented.

That's documentation for Lisp program writers.
It is a weirdness for Emacs users, so I think the aspects
that affect users should be in the Emacs Manual.

  > This thread is about something else -- about a user option that would
  > disable converting `..' into ‘..’.

Maybe that should be part of what it says about curly quotes
conversion in the Emacs Manual.

I am not insisting this particular option is worth including there.
Maybe it is, but that's not my point.  I think the fact that this
conversion EXISTS should be there.


-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: Emacs 26.1 release branch created

[Paul Eggert]

[-- Attachment #1: Type: text/plain, Size: 295 bytes --]

On 09/20/2017 01:37 PM, Richard Stallman wrote:
> I am not insisting this particular option is worth including there.
> Maybe it is, but that's not my point.  I think the fact that this
> conversion EXISTS should be there.

How about the attached patch to do that? (I have not installed this.)


[-- Attachment #2: 0001-Mention-quoting-in-user-manual.txt --]
[-- Type: text/plain, Size: 1324 bytes --]

From 01102f0b42076fc732783b6bf852cadc2609527a Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Thu, 21 Sep 2017 13:33:22 -0700
Subject: [PATCH] Mention quoting in user manual

* doc/emacs/display.texi (Display Custom): Briefly mention quoting.
Lack of documentation noted by Alan Mackenzie in:
http://lists.gnu.org/archive/html/emacs-devel/2017-09/msg00632.html
---
 doc/emacs/display.texi | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 2aa79e1161..a668317e85 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -1839,6 +1839,13 @@ Display Custom
 @code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil}
 argument to suppress the effect of bold-face in this case.
 
+  Emacs infers how to quote in help and messages by examining its
+environment.  By default, Emacs quotes @t{‘like this’} with curved
+single quotes if displayable, and @t{`like this'} with grave accent
+and apostrophe otherwise.  @xref{Keys in Documentation,, Substituting
+Key Bindings in Documentation, elisp, The GNU Emacs Lisp Reference
+Manual}.
+
 @vindex display-raw-bytes-as-hex
   Raw bytes are displayed in octal format by default, for example a
 byte with a decimal value of 128 is displayed as @code{\200}.  To
-- 
2.13.5

RE: Emacs 26.1 release branch created

[Drew Adams]

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
> 
> The display of curly quotes in Emacs is a weirdness.  I think
> it is worth documenting in the manual.

Weirdness, indeed.  Hopping on yesterday's bandwagon...

Worth documenting, not promoting, and giving users a
well-advertised way out.

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> Cc: jwiegley@gmail.com, emacs-devel@gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Tue, 19 Sep 2017 12:11:02 -0700
> 
> To address some of Alan's concerns, how about adding a brief note to the 
> user manual, in its section "Display Custom" that already says 
> "Beginning users can skip [this section]" and that already mentions 
> things like tty-suppress-bold-inverse-default-colors that are meant for 
> expert users. Something like the attached, perhaps?

Thanks, but I'd prefer not to add documentation of non-options.  And,
as I expected, this doesn't really address Alan's concerns.

Re: Emacs 26.1 release branch created

[Paul Eggert]

On 09/19/2017 10:35 AM, Alan Mackenzie wrote:
> Can we please have a user option in Emacs 26 to disable curly quote
> translation in messages and doc strings?

If I understand this request correctly, it's already implemented in 
emacs-26; see commit 433d366dc7b053048abf710d790ff62421dd1570 dated May 
10 07:38:23 2016 -0700. (setq text-quoting-style 'grave) should have the 
requested effect.

Re: Emacs 26.1 release branch created

[John Wiegley]

>>>>> Alan Mackenzie <acm@muc.de> writes:

> Can we please have a user option in Emacs 26 to disable curly quote
> translation in messages and doc strings? I am (more than) willing to
> implement and document this, and could do so quickly.

Hi Alan, can you prepare this patch for us, including additions to NEWS and
the manual? I'd like to get it into the emacs-26 branch soonish. Eli and I
discussed offline, and while it's still technically premature, I have a strong
wish to see it happen anyway.

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

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, John

On Wed, Sep 20, 2017 at 11:30:35 -0700, John Wiegley wrote:
> >>>>> Alan Mackenzie <acm@muc.de> writes:

> > Can we please have a user option in Emacs 26 to disable curly quote
> > translation in messages and doc strings? I am (more than) willing to
> > implement and document this, and could do so quickly.

> Hi Alan, can you prepare this patch for us, including additions to NEWS and
> the manual? I'd like to get it into the emacs-26 branch soonish. Eli and I
> discussed offline, and while it's still technically premature, I have a strong
> wish to see it happen anyway.

Thanks for this!

I have pushed a first draught into the new branch
scratch/customize-quotes.  Comments would be welcome.

One thing which I hope isn't too controversial, is that I have redefined
the value of nil in text-quoting-style to mean "no translation of
quotes" and introduced t to mean "prefer curved quotes", the meaning nil
previously had.  The default value for text-quoting-style remains
"prefer curved quotes".

My reasoning here was that having nil meaning "do nothing" is
intrinsically the Right Thing.  Also very few people, if any, will
already have explicitly set the variable to nil.  And in any case, the
use of the variable was restricted to experts, all of whom will be able
to adapt to the new nil and t without difficulty.

@Richard: I have described the fact that translation of ASCII quote
characters takes place on the page "Text Display" in the Emacs manual,
as you suggested.

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

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[Paul Eggert]

Alan Mackenzie wrote:
> I have redefined
> the value of nil in text-quoting-style to mean "no translation of
> quotes" and introduced t to mean "prefer curved quotes", the meaning nil
> previously had.

Let's not change the semantics of text-quoting-style's values. Such a change is 
not worth the compatibility hassle to users. John asked you to propose a patch 
to make text-quoting-style customizable, not to change its semantics. Whether 
text-quoting-style is customizable is orthogonal to what its values mean, and we 
shouldn't conflate the two issues.

>  quotes.  In contrast, a call using a format like @t{"Missing '%s'"}
>  with only apostrophes typically generates a message like @t{"Missing
>  ’foo’"} with only closing curved quotes, an unusual style in English.
> +One way around this problem is to bind @code{text-quoting-style} to
> +@code{nil} around the call to @code{error}; this causes the
> +@acronym{ASCII} quote characters to be output unchanged.

This doc patch, which occurs in multiple places, heads in the wrong direction. 
"Missing `%s'" is the typical way to quote in Emacs source code. The current 
documentation gently warns the programmer to avoid "Missing '%s'" as this is not 
the usual Emacs style and typically won't look good anyway. If the warning is 
not clear enough we should clarify it, not encourage proliferation of atypical 
formats.

> +** The variable `text-quoting-style' is now a customizable option.  It

This (and other changes to NEWS) should use straight quotes, as that's the style 
used in NEWS now.

Re: Emacs 26.1 release branch created

[John Wiegley]

>>>>> "PE" == Paul Eggert <eggert@cs.ucla.edu> writes:

PE> Let's not change the semantics of text-quoting-style's values. Such a
PE> change is not worth the compatibility hassle to users. John asked you to
PE> propose a patch to make text-quoting-style customizable, not to change its
PE> semantics. Whether text-quoting-style is customizable is orthogonal to
PE> what its values mean, and we shouldn't conflate the two issues.

Just to confirm, Paul's assessment is correct: at this late stage, I only want
to add customizability, no other changes.

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

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, Paul.

On Thu, Sep 21, 2017 at 22:19:53 -0700, Paul Eggert wrote:
> Alan Mackenzie wrote:
> > I have redefined
> > the value of nil in text-quoting-style to mean "no translation of
> > quotes" and introduced t to mean "prefer curved quotes", the meaning nil
> > previously had.

> Let's not change the semantics of text-quoting-style's values. Such a change is 
> not worth the compatibility hassle to users.

What compatibility hassle?  There is none.  The only hassle would come
if some user had written something like:

    (setq text-quoting-style nil)

in her .emacs.  Users don't set configuration variables to their
defaults.  Life is too short for that.

Or can you picture some other scenario which would cause hassle?

> John asked you to propose a patch to make text-quoting-style
> customizable, not to change its semantics.

Its semantics is entirely unchanged in every important respect.

> Whether text-quoting-style is customizable is orthogonal to what its
> values mean, and we shouldn't conflate the two issues.

There will be no other chance to correct the poor choice of symbols in
text-quoting-style.  It has to be done now, or it can never be done.

> >  quotes.  In contrast, a call using a format like @t{"Missing '%s'"}
> >  with only apostrophes typically generates a message like @t{"Missing
> >  ’foo’"} with only closing curved quotes, an unusual style in English.
> > +One way around this problem is to bind @code{text-quoting-style} to
> > +@code{nil} around the call to @code{error}; this causes the
> > +@acronym{ASCII} quote characters to be output unchanged.

> This doc patch, which occurs in multiple places, heads in the wrong direction. 
> "Missing `%s'" is the typical way to quote in Emacs source code. The current 
> documentation gently warns the programmer to avoid "Missing '%s'" as this is not 
> the usual Emacs style ....

See below.

> .... and typically won't look good anyway. If the warning is not clear
> enough we should clarify it, not encourage proliferation of atypical
> formats.

Again, see below.

But the main point here is to remind the reader that quotes can be
output as is by binding text-quoting-style, regardless of whether these
quotes are used in pairs to, er, quote something, or whether they need
to stand for themselves (as was the case in cc-engine.el some while
ago).  Perhaps you could suggest an improved wording which would give
the reader clear information about binding text-quoting-style, but
without appearing to encourage any non-standard quoting styles.

> > +** The variable `text-quoting-style' is now a customizable option.  It

> This (and other changes to NEWS) should use straight quotes, as that's the style 
> used in NEWS now.

A non-standard quoting style in NEWS?  ;-)  OK, I'll fix that NEWS item.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[John Wiegley]

>>>>> "AM" == Alan Mackenzie <acm@muc.de> writes:

AM> There will be no other chance to correct the poor choice of symbols in
AM> text-quoting-style. It has to be done now, or it can never be done.

But this isn't what was asked for, which was only to make text-quoting-style
customizable. Correcting the choice of symbols is an orthogonal matter, to
decided separately. Whether that is done for 26.1 or not has yet to even be
considered.

We cannot accept the change as is, but I'd be happy for a change that only
makes the current text-quoting-style customizable, although with documentation
in the manual and NEWS. Thanks!

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

Re: Emacs 26.1 release branch created

[Paul Eggert]

[-- Attachment #1: Type: text/plain, Size: 1052 bytes --]

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). It's better for the Elisp 
manual to suggest the techniques that are typically used.

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


[-- Attachment #2: 0001-Improve-text-quoting-style-doc-in-lispref.txt --]
[-- Type: text/plain, Size: 11311 bytes --]

From dd9535349f18346f85f9f40940451a0b20f3897c Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Fri, 22 Sep 2017 13:29:17 -0700
Subject: [PATCH] Improve text-quoting-style doc in lispref

* doc/lispref/control.texi (Signaling Errors):
* doc/lispref/display.texi (Displaying Messages):
* doc/lispref/strings.texi (Formatting Strings):
Edit for brevity, farming out the details to the new
Text Quoting Style node.
* doc/lispref/help.texi (Text Quoting Style): New section.
Move detailed discussion of text-quoting-style here.
Add discussion about how to output grave accent and apostrophe in
documentation and messages.  Adjust xrefs to point to this section
when appropriate.
---
 doc/lispref/control.texi | 10 +++----
 doc/lispref/display.texi | 12 ++++-----
 doc/lispref/elisp.texi   |  1 +
 doc/lispref/help.texi    | 69 ++++++++++++++++++++++++++++++++++--------------
 doc/lispref/strings.texi | 12 ++++-----
 doc/lispref/tips.texi    |  4 +--
 6 files changed, 66 insertions(+), 42 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 401a999cf2..ffa6b59f49 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -1101,13 +1101,11 @@ Signaling Errors
 error symbol @code{error}, and a list containing the string returned by
 @code{format-message}.
 
+@vindex text-quoting-style
 The @code{text-quoting-style} variable controls what quotes are
-generated; @xref{Keys in Documentation}.  A call using a format like
-@t{"Missing `%s'"} with grave accents and apostrophes typically
-generates a message like @t{"Missing ‘foo’"} with matching curved
-quotes.  In contrast, a call using a format like @t{"Missing '%s'"}
-with only apostrophes typically generates a message like @t{"Missing
-’foo’"} with only closing curved quotes, an unusual style in English.
+generated.  Typically grave accent and apostrophe in the format
+generate matching curved quotes, e.g., @t{"Missing `%s'"} might
+generate @t{"Missing ‘foo’"}.  @xref{Text Quoting Style}.
 
 @strong{Warning:} If you want to use your own string as an error message
 verbatim, don't just write @code{(error @var{string})}.  If @var{string}
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 3dae984f33..2322766945 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -265,13 +265,11 @@ Displaying Messages
 The string is also added to the @file{*Messages*} buffer, but without
 text properties (@pxref{Logging Messages}).
 
+@vindex text-quoting-style
 The @code{text-quoting-style} variable controls what quotes are
-generated; @xref{Keys in Documentation}.  A call using a format like
-@t{"Missing `%s'"} with grave accents and apostrophes typically
-generates a message like @t{"Missing ‘foo’"} with matching curved
-quotes.  In contrast, a call using a format like @t{"Missing '%s'"}
-with only apostrophes typically generates a message like @t{"Missing
-’foo’"} with only closing curved quotes, an unusual style in English.
+generated.  Typically grave accent and apostrophe in the format
+generate matching curved quotes, e.g., @t{"Missing `%s'"} might
+generate @t{"Missing ‘foo’"}.  @xref{Text Quoting Style}.
 
 In batch mode, the message is printed to the standard error stream,
 followed by a newline.
@@ -7035,7 +7033,7 @@ Active Display Table
 is outputting text to the standard output or error streams.  Although its
 default is typically @code{nil}, in an interactive session if the
 terminal cannot display curved quotes, its default maps curved quotes
-to ASCII approximations.  @xref{Keys in Documentation}.
+to ASCII approximations.  @xref{Text Quoting Style}.
 @end defvar
 
 The @file{disp-table} library defines several functions for changing
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 4cbcdf855d..c752594584 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -940,6 +940,7 @@ Top
 * Documentation Basics::    Where doc strings are defined and stored.
 * Accessing Documentation:: How Lisp programs can access doc strings.
 * Keys in Documentation::   Substituting current key bindings.
+* Text Quoting Style::      Quotation marks in doc strings and messages.
 * Describing Characters::   Making printable descriptions of
                               non-printing characters and key sequences.
 * Help Functions::          Subroutines used by Emacs help facilities.
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index cb21411352..c3cc5a98a6 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -33,6 +33,7 @@ Documentation
 * Documentation Basics::      Where doc strings are defined and stored.
 * Accessing Documentation::   How Lisp programs can access doc strings.
 * Keys in Documentation::     Substituting current key bindings.
+* Text Quoting Style::        Quotation marks in doc strings and messages.
 * Describing Characters::     Making printable descriptions of
                                 non-printing characters and key sequences.
 * Help Functions::            Subroutines used by Emacs help facilities.
@@ -336,6 +337,7 @@ Keys in Documentation
 (grave accent) stands for a left quote.
 This generates a left single quotation mark, an apostrophe, or a grave
 accent depending on the value of @code{text-quoting-style}.
+@xref{Text Quoting Style}.
 
 @item '
 (apostrophe) stands for a right quote.
@@ -351,26 +353,6 @@ Keys in Documentation
 @strong{Please note:} Each @samp{\} must be doubled when written in a
 string in Emacs Lisp.
 
-@defvar text-quoting-style
-@cindex curved quotes
-@cindex curly quotes
-The value of this variable is a symbol that specifies the style Emacs
-should use for single quotes in the wording of help and messages.
-If the variable's value is @code{curve}, the style is
-@t{‘like this’} with curved single quotes.  If the value is
-@code{straight}, the style is @t{'like this'} with straight
-apostrophes.  If the value is @code{grave},
-quotes are not translated and the style is @t{`like
-this'} with grave accent and apostrophe, the standard style
-before Emacs version 25.  The default value @code{nil}
-acts like @code{curve} if curved single quotes are displayable, and
-like @code{grave} otherwise.
-
-This variable can be used by experts on platforms that have problems
-with curved quotes.  As it is not intended for casual use, it is not a
-user option.
-@end defvar
-
 @defun substitute-command-keys string
 This function scans @var{string} for the above special sequences and
 replaces them by what they stand for, returning the result as a string.
@@ -429,6 +411,53 @@ Keys in Documentation
 strings---for instance, you can refer to functions, variables, and
 sections of this manual.  @xref{Documentation Tips}, for details.
 
+@node Text Quoting Style
+@section Text Quoting Style
+
+  Typically, grave accents and apostrophes are treated specially in
+documentation strings and diagnostic messages, and generate matching
+single quotation marks (also called ``curved quotes'').  For example,
+the documentation string @t{"Alias for `foo'."} and the function call
+@code{(message "Alias for `foo'.")} both generate @t{"Alias for
+‘foo’."}.  Less commonly, Emacs displays grave accents and apostrophes
+as themselves, or as apostrophes only (e.g., @t{"Alias for 'foo'."}).
+Documentation strings and message formats should be written so that
+they display well with any of these styles.  For example, the
+documentation string @t{"Alias for 'foo'."} is probably not what you
+want, as it can display as @t{"Alias for ’foo’."}, an unusual style in
+English.
+
+  Sometimes you may need to display a grave accent or apostrophe
+without translation, regardless of text quoting style.  In a
+documentation string, you can do this with escapes.  For example, in
+the documentation string @t{"\\=`(a ,(sin 0)) ==> (a 0.0)"} the grave
+accent is intended to denote Lisp code, so it is escaped and displays
+as itself regardless of quoting style.  In a call to @code{message} or
+@code{error}, you can avoid translation by using a format @t{"%s"}
+with an argument that is a call to @code{format}.  For example,
+@code{(message "%s" (format "`(a ,(sin %S)) ==> (a %S)" x (sin x)))}
+displays a message that starts with grave accent regardless of text
+quoting style.
+
+@defvar text-quoting-style
+@cindex curved quotes
+@cindex curly quotes
+The value of this variable is a symbol that specifies the style Emacs
+should use for single quotes in the wording of help and messages.  If
+the variable's value is @code{curve}, the style is @t{‘like this’}
+with curved single quotes.  If the value is @code{straight}, the style
+is @t{'like this'} with straight apostrophes.  If the value is
+@code{grave}, quotes are not translated and the style is @t{`like
+this'} with grave accent and apostrophe, the standard style before
+Emacs version 25.  The default value @code{nil} acts like @code{curve}
+if curved single quotes are displayable, and like @code{grave}
+otherwise.
+
+This variable can be used by experts on platforms that have problems
+with curved quotes.  As it is not intended for casual use, it is not a
+user option.
+@end defvar
+
 @node Describing Characters
 @section Describing Characters for Help Messages
 @cindex describe characters and events
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 219225d412..09434ce573 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -826,17 +826,15 @@ Formatting Strings
 @defun format-message string &rest objects
 @cindex curved quotes, in formatted messages
 @cindex curly quotes, in formatted messages
-@cindex @code{text-quoting-style}, and formatting messages
 This function acts like @code{format}, except it also converts any
 grave accents (@t{`}) and apostrophes (@t{'}) in @var{string} as per the
 value of @code{text-quoting-style}.
 
-A format that quotes with grave accents and apostrophes @t{`like
-this'} typically generates curved quotes @t{‘like this’}.  In
-contrast, a format that quotes with only apostrophes @t{'like this'}
-typically generates two closing curved quotes @t{’like this’}, an
-unusual style in English.  @xref{Keys in Documentation}, for how the
-@code{text-quoting-style} variable affects generated quotes.
+@vindex text-quoting-style
+The @code{text-quoting-style} variable controls what quotes are
+generated.  Typically grave accent and apostrophe in the format
+generate matching curved quotes, e.g., @t{"Missing `%s'"} might
+generate @t{"Missing ‘foo’"}.  @xref{Text Quoting Style}.
 @end defun
 
 @cindex @samp{%} in format
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 17fd4a1027..0bccde66cd 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -683,8 +683,8 @@ Documentation Tips
 older convention was designed for now-obsolete displays in which grave
 accent and apostrophe were mirror images.
 Documentation using this convention is converted to the user's
-preferred format when it is copied into a help buffer.  @xref{Keys in
-Documentation}.
+preferred format when it is copied into a help buffer.  @xref{Text
+Quoting Style}.
 
 @cindex hyperlinks in documentation strings
 Help mode automatically creates a hyperlink when a documentation string
-- 
2.13.5

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

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

Re: Emacs 26.1 release branch created

[Paul Eggert]

[-- Attachment #1: Type: text/plain, Size: 2100 bytes --]

Alan Mackenzie wrote:

> Putting a single output
> operation through two `format'-like operations is bizarre and
> extravagant.  It's not something we should encourage.

It's not bizarre; it's routine in Emacs Lisp code. And it's not extravagant: the 
loss in efficiency for messages is tiny, and is not something users have noticed 
or complained about.

> By contrast, binding a controlling variable around an operation is the
> standard Emacs way of doing such things.

It's standard for other things, but it's definitely not standard here. The Emacs 
source code never does it this way.

> How many such instances are there in the code anyway?

There are about 400 instances of '(message "%s"' or '(error "%s"' in the Emacs 
source code. For decades this has been common practice when an Elisp programmer 
wants to avoid translation or formatting in the argument to 'message'-like 
functions. It's not that easy to count how many of the 400 instances are for 
quotes as opposed to being for other things, but I'd guess dozens.

> This would need fleshing out with something like "To inhibit
> or influence this translation of ASCII quotes, see text-quoting-style".

Sure, that's easy. Revised proposal attached.

> The "boilerplate" you want to replace is short and to the point,

It is not short; it's discursive and it gets in the way. In your proposal, it's 
about ten lines of boilerplate for each affected function, boilerplate that is 
about as long as the main function description itself. We should move most of 
this boilerplate to a common section, and briefly allude to it in each affected 
function. This will give us room to expand on the issue in the common section, 
which I've done in my proposal - it has about twenty lines discussing the issue, 
and this is shorter and provides more useful info than repeating ten lines in 
multiple places.

> A further general point about this bit of doc is its rather strange use
> of the verb "generate".

Also easy; the revised proposal (attached) uses "translates to" instead of 
"generates".

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improve-text-quoting-style-doc-in-lispref.patch --]
[-- Type: text/x-patch; name="0001-Improve-text-quoting-style-doc-in-lispref.patch", Size: 11498 bytes --]

From 8bc41bd77d272e2273e4f40cf7b4a57fe8900045 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sun, 24 Sep 2017 11:02:40 -0700
Subject: [PATCH] Improve text-quoting-style doc in lispref

* doc/lispref/control.texi (Signaling Errors):
* doc/lispref/display.texi (Displaying Messages):
* doc/lispref/strings.texi (Formatting Strings):
Edit for brevity, farming out the details to the new
Text Quoting Style node.
* doc/lispref/help.texi (Text Quoting Style): New section.
Move detailed discussion of text-quoting-style here.
Add discussion about how to output grave accent and apostrophe in
documentation and messages.  Adjust xrefs to point to this section
when appropriate.
---
 doc/lispref/control.texi | 11 +++-----
 doc/lispref/display.texi | 13 ++++-----
 doc/lispref/elisp.texi   |  1 +
 doc/lispref/help.texi    | 69 ++++++++++++++++++++++++++++++++++--------------
 doc/lispref/strings.texi | 12 +++------
 doc/lispref/tips.texi    |  4 +--
 6 files changed, 65 insertions(+), 45 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 401a999cf2..ab0b49266d 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -1101,13 +1101,10 @@ Signaling Errors
 error symbol @code{error}, and a list containing the string returned by
 @code{format-message}.
 
-The @code{text-quoting-style} variable controls what quotes are
-generated; @xref{Keys in Documentation}.  A call using a format like
-@t{"Missing `%s'"} with grave accents and apostrophes typically
-generates a message like @t{"Missing ‘foo’"} with matching curved
-quotes.  In contrast, a call using a format like @t{"Missing '%s'"}
-with only apostrophes typically generates a message like @t{"Missing
-’foo’"} with only closing curved quotes, an unusual style in English.
+Typically grave accent and apostrophe in the format translate to
+matching curved quotes, e.g., @t{"Missing `%s'"} might result in
+@t{"Missing ‘foo’"}.  @xref{Text Quoting Style}, for how to control
+this translation.
 
 @strong{Warning:} If you want to use your own string as an error message
 verbatim, don't just write @code{(error @var{string})}.  If @var{string}
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 3dae984f33..12ca065d86 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -265,13 +265,10 @@ Displaying Messages
 The string is also added to the @file{*Messages*} buffer, but without
 text properties (@pxref{Logging Messages}).
 
-The @code{text-quoting-style} variable controls what quotes are
-generated; @xref{Keys in Documentation}.  A call using a format like
-@t{"Missing `%s'"} with grave accents and apostrophes typically
-generates a message like @t{"Missing ‘foo’"} with matching curved
-quotes.  In contrast, a call using a format like @t{"Missing '%s'"}
-with only apostrophes typically generates a message like @t{"Missing
-’foo’"} with only closing curved quotes, an unusual style in English.
+Typically grave accent and apostrophe in the format translate to
+matching curved quotes, e.g., @t{"Missing `%s'"} might result in
+@t{"Missing ‘foo’"}.  @xref{Text Quoting Style}, for how to control
+this translation.
 
 In batch mode, the message is printed to the standard error stream,
 followed by a newline.
@@ -7035,7 +7032,7 @@ Active Display Table
 is outputting text to the standard output or error streams.  Although its
 default is typically @code{nil}, in an interactive session if the
 terminal cannot display curved quotes, its default maps curved quotes
-to ASCII approximations.  @xref{Keys in Documentation}.
+to ASCII approximations.  @xref{Text Quoting Style}.
 @end defvar
 
 The @file{disp-table} library defines several functions for changing
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 4cbcdf855d..c752594584 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -940,6 +940,7 @@ Top
 * Documentation Basics::    Where doc strings are defined and stored.
 * Accessing Documentation:: How Lisp programs can access doc strings.
 * Keys in Documentation::   Substituting current key bindings.
+* Text Quoting Style::      Quotation marks in doc strings and messages.
 * Describing Characters::   Making printable descriptions of
                               non-printing characters and key sequences.
 * Help Functions::          Subroutines used by Emacs help facilities.
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index cb21411352..3da365904e 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -33,6 +33,7 @@ Documentation
 * Documentation Basics::      Where doc strings are defined and stored.
 * Accessing Documentation::   How Lisp programs can access doc strings.
 * Keys in Documentation::     Substituting current key bindings.
+* Text Quoting Style::        Quotation marks in doc strings and messages.
 * Describing Characters::     Making printable descriptions of
                                 non-printing characters and key sequences.
 * Help Functions::            Subroutines used by Emacs help facilities.
@@ -336,6 +337,7 @@ Keys in Documentation
 (grave accent) stands for a left quote.
 This generates a left single quotation mark, an apostrophe, or a grave
 accent depending on the value of @code{text-quoting-style}.
+@xref{Text Quoting Style}.
 
 @item '
 (apostrophe) stands for a right quote.
@@ -351,26 +353,6 @@ Keys in Documentation
 @strong{Please note:} Each @samp{\} must be doubled when written in a
 string in Emacs Lisp.
 
-@defvar text-quoting-style
-@cindex curved quotes
-@cindex curly quotes
-The value of this variable is a symbol that specifies the style Emacs
-should use for single quotes in the wording of help and messages.
-If the variable's value is @code{curve}, the style is
-@t{‘like this’} with curved single quotes.  If the value is
-@code{straight}, the style is @t{'like this'} with straight
-apostrophes.  If the value is @code{grave},
-quotes are not translated and the style is @t{`like
-this'} with grave accent and apostrophe, the standard style
-before Emacs version 25.  The default value @code{nil}
-acts like @code{curve} if curved single quotes are displayable, and
-like @code{grave} otherwise.
-
-This variable can be used by experts on platforms that have problems
-with curved quotes.  As it is not intended for casual use, it is not a
-user option.
-@end defvar
-
 @defun substitute-command-keys string
 This function scans @var{string} for the above special sequences and
 replaces them by what they stand for, returning the result as a string.
@@ -429,6 +411,53 @@ Keys in Documentation
 strings---for instance, you can refer to functions, variables, and
 sections of this manual.  @xref{Documentation Tips}, for details.
 
+@node Text Quoting Style
+@section Text Quoting Style
+
+  Typically, grave accents and apostrophes are treated specially in
+documentation strings and diagnostic messages, and translate to matching
+single quotation marks (also called ``curved quotes'').  For example,
+the documentation string @t{"Alias for `foo'."} and the function call
+@code{(message "Alias for `foo'.")} both translate to @t{"Alias for
+‘foo’."}.  Less commonly, Emacs displays grave accents and apostrophes
+as themselves, or as apostrophes only (e.g., @t{"Alias for 'foo'."}).
+Documentation strings and message formats should be written so that
+they display well with any of these styles.  For example, the
+documentation string @t{"Alias for 'foo'."} is probably not what you
+want, as it can display as @t{"Alias for ’foo’."}, an unusual style in
+English.
+
+  Sometimes you may need to display a grave accent or apostrophe
+without translation, regardless of text quoting style.  In a
+documentation string, you can do this with escapes.  For example, in
+the documentation string @t{"\\=`(a ,(sin 0)) ==> (a 0.0)"} the grave
+accent is intended to denote Lisp code, so it is escaped and displays
+as itself regardless of quoting style.  In a call to @code{message} or
+@code{error}, you can avoid translation by using a format @t{"%s"}
+with an argument that is a call to @code{format}.  For example,
+@code{(message "%s" (format "`(a ,(sin %S)) ==> (a %S)" x (sin x)))}
+displays a message that starts with grave accent regardless of text
+quoting style.
+
+@defvar text-quoting-style
+@cindex curved quotes
+@cindex curly quotes
+The value of this variable is a symbol that specifies the style Emacs
+should use for single quotes in the wording of help and messages.  If
+the variable's value is @code{curve}, the style is @t{‘like this’}
+with curved single quotes.  If the value is @code{straight}, the style
+is @t{'like this'} with straight apostrophes.  If the value is
+@code{grave}, quotes are not translated and the style is @t{`like
+this'} with grave accent and apostrophe, the standard style before
+Emacs version 25.  The default value @code{nil} acts like @code{curve}
+if curved single quotes are displayable, and like @code{grave}
+otherwise.
+
+This variable can be used by experts on platforms that have problems
+with curved quotes.  As it is not intended for casual use, it is not a
+user option.
+@end defvar
+
 @node Describing Characters
 @section Describing Characters for Help Messages
 @cindex describe characters and events
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 219225d412..a89e9671d7 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -826,17 +826,13 @@ Formatting Strings
 @defun format-message string &rest objects
 @cindex curved quotes, in formatted messages
 @cindex curly quotes, in formatted messages
-@cindex @code{text-quoting-style}, and formatting messages
 This function acts like @code{format}, except it also converts any
 grave accents (@t{`}) and apostrophes (@t{'}) in @var{string} as per the
 value of @code{text-quoting-style}.
-
-A format that quotes with grave accents and apostrophes @t{`like
-this'} typically generates curved quotes @t{‘like this’}.  In
-contrast, a format that quotes with only apostrophes @t{'like this'}
-typically generates two closing curved quotes @t{’like this’}, an
-unusual style in English.  @xref{Keys in Documentation}, for how the
-@code{text-quoting-style} variable affects generated quotes.
+Typically grave accent and apostrophe in the format translate to
+matching curved quotes, e.g., @t{"Missing `%s'"} might result in
+@t{"Missing ‘foo’"}.  @xref{Text Quoting Style}, for how to control
+this translation.
 @end defun
 
 @cindex @samp{%} in format
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 17fd4a1027..0bccde66cd 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -683,8 +683,8 @@ Documentation Tips
 older convention was designed for now-obsolete displays in which grave
 accent and apostrophe were mirror images.
 Documentation using this convention is converted to the user's
-preferred format when it is copied into a help buffer.  @xref{Keys in
-Documentation}.
+preferred format when it is copied into a help buffer.  @xref{Text
+Quoting Style}.
 
 @cindex hyperlinks in documentation strings
 Help mode automatically creates a hyperlink when a documentation string
-- 
2.13.5

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, Paul.

On Sun, Sep 24, 2017 at 11:13:06 -0700, Paul Eggert wrote:
> Alan Mackenzie wrote:

> > Putting a single output
> > operation through two `format'-like operations is bizarre and
> > extravagant.  It's not something we should encourage.

> It's not bizarre; it's routine in Emacs Lisp code.

It occurs once in Emacs Lisp code, in cc-engine.el.  I doubt it's used
more than once, and you are remarkably evasive about this point.

> And it's not extravagant: the loss in efficiency for messages is tiny,
> and is not something users have noticed or complained about.

But it's a loss of efficiency nevertheless, no matter how slight.
You've given no reasons to use it, other than "we've already used it
once", which is a poor reason.

> > By contrast, binding a controlling variable around an operation is the
> > standard Emacs way of doing such things.

> It's standard for other things, but it's definitely not standard here. The Emacs 
> source code never does it this way.

It soon will, once I amend cc-engine.el.

> > How many such instances are there in the code anyway?

[ Trim evasive non-answer ]

Why won't you anwer this question, Paul?  Why do you twist my text by
selective quoting?  What are you trying to hide?  Once again, how many
instances of this double format technique exist in the Lisp code?  Cite
another one which isn't in cc-engine.el.

> > This would need fleshing out with something like "To inhibit
> > or influence this translation of ASCII quotes, see text-quoting-style".

> Sure, that's easy. Revised proposal attached.

Thanks, I'll read it.

> > The "boilerplate" you want to replace is short and to the point,

> It is not short; it's discursive and it gets in the way. In your proposal, it's 
> about ten lines of boilerplate for each affected function, ....

of which I've contributed only around three lines.  "Boilerplate" is
hardly an accurate term for it, since it only occurs three times, and
it's essential information for users of these functions, which would get
lost if moved into a separate page.

> .... boilerplate that is about as long as the main function
> description itself. We should move most of this boilerplate to a
> common section, and briefly allude to it in each affected function.
> This will give us room to expand on the issue in the common section,
> which I've done in my proposal - it has about twenty lines discussing
> the issue, and this is shorter and provides more useful info than
> repeating ten lines in multiple places.

> > A further general point about this bit of doc is its rather strange use
> > of the verb "generate".

> Also easy; the revised proposal (attached) uses "translates to" instead of 
> "generates".

Thanks.

[ .... ]

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> Date: Thu, 21 Sep 2017 20:54:47 +0000
> From: Alan Mackenzie <acm@muc.de>
> Cc: Richard Stallman <rms@gnu.org>
> 
> I have pushed a first draught into the new branch
> scratch/customize-quotes.  Comments would be welcome.
> 
> One thing which I hope isn't too controversial, is that I have redefined
> the value of nil in text-quoting-style to mean "no translation of
> quotes" and introduced t to mean "prefer curved quotes", the meaning nil
> previously had.  The default value for text-quoting-style remains
> "prefer curved quotes".

This _is_ controversial, since it means we are introducing a backward
incompatible change.

> My reasoning here was that having nil meaning "do nothing" is
> intrinsically the Right Thing.  Also very few people, if any, will
> already have explicitly set the variable to nil.  And in any case, the
> use of the variable was restricted to experts, all of whom will be able
> to adapt to the new nil and t without difficulty.

IMO, this reasoning is too weak to justify the incompatible change.

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, Eli and John.

I'm putting your two posts together to answer them together.

On Fri, Sep 22, 2017 at 10:17:15 +0300, Eli Zaretskii wrote:
> > Date: Thu, 21 Sep 2017 20:54:47 +0000
> > From: Alan Mackenzie <acm@muc.de>
> > Cc: Richard Stallman <rms@gnu.org>

> > I have pushed a first draught into the new branch
> > scratch/customize-quotes.  Comments would be welcome.

> > One thing which I hope isn't too controversial, is that I have redefined
> > the value of nil in text-quoting-style to mean "no translation of
> > quotes" and introduced t to mean "prefer curved quotes", the meaning nil
> > previously had.  The default value for text-quoting-style remains
> > "prefer curved quotes".

> This _is_ controversial, since it means we are introducing a backward
> incompatible change.

> > My reasoning here was that having nil meaning "do nothing" is
> > intrinsically the Right Thing.  Also very few people, if any, will
> > already have explicitly set the variable to nil.  And in any case, the
> > use of the variable was restricted to experts, all of whom will be able
> > to adapt to the new nil and t without difficulty.

> IMO, this reasoning is too weak to justify the incompatible change.

On Thu, Sep 21, 2017 at 22:58:40 -0700, John Wiegley wrote:
> >>>>> "PE" == Paul Eggert <eggert@cs.ucla.edu> writes:

> PE> Let's not change the semantics of text-quoting-style's values.   Such a
> PE> change is not worth the compatibility hassle to users. John asked you to
> PE> propose a patch to make text-quoting-style customizable, not to change its
> PE> semantics. Whether text-quoting-style is customizable is orthogonal to
> PE> what its values mean, and we shouldn't conflate the two issues.

> Just to confirm, Paul's assessment is correct: at this late stage, I only want
> to add customizability, no other changes.

I'm surprised and dismayed by both your reactions to my proposed patch.
I thought the issues through carefully before investing time and energy
in it.

You talk about backward incompatibility.  Well, backward incomptibility
is only bad when it inconveniences users, which is most of the time.  It
isn't the case here.  Neither of you, nor Paul has suggested a scenario
in which a user might suffer.  I put it to you that there aren't any,
particularly considering how text-quoting-style was kept away from
ordinary users in Emacs 25.

The current set of symbols used for text-quoting-style is bad.  Nobody
in recent posts, if ever, has defended them as being good.  Its worth
bearing in mind that they found their way into the Emacs master without
any sort of review beforehand.  How are we going to defend the use of
the symbol `grave' having the meaning "don't do any translation" five or
ten years from now?  What makes it worse is its suggestion of "grave
danger" alongside "grave accent".

I'm concerned for the quality of Emacs, and the use of nil in
text-quoting-style sticks out like a sore thumb.  The only possible time
to fix this problem is now - after text-quoting-style is released for
ordinary users in Emacs-26, it will be too late.

So, I'm asking you once more to consider very carefully the issues
behind my proposed amendment.  For my part, I undertake to accept your
decision on the matter without further argument, and to change the code
in scratch/customize-quotes to the simple change you were expecting,
should you say no again.

Thanks.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[Stefan Monnier]

> I'm surprised and dismayed by both your reactions to my proposed patch.

Yet, it was very predictable: which symbol to use for which meaning has
no technical importance, so it's a perfect candidate for bikeshedding.

Worse yet: while it has no technical importance, it does have
political/emotional importance.  Since the decision not to define it as
a defcustom was taken for strategic reasons, clearly the
political/emotional aspect is very relevant here.  And it's also your
prime motivation for this change.


        Stefan

Re: Emacs 26.1 release branch created

[John Wiegley]

>>>>> "AM" == Alan Mackenzie <acm@muc.de> writes:

AM> I'm surprised and dismayed by both your reactions to my proposed patch. I
AM> thought the issues through carefully before investing time and energy in
AM> it.

You offered to make text-quoting-style customizable, and we agreed and asked
for a patch. The patch you came up with did more than this, changing other
aspects of text-quoting-style. This isn't what was asked for.

First, let's make text-quoting-style customizable, as this can definitely make
it into 26.1. *Then*, we can start a discussion on whether to change it
further, as you've proposed. Whether this will happen in 26.1 is another
question, but at least we'll get the customization point out of the way.

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

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, John.

On Fri, Sep 22, 2017 at 12:28:40 -0700, John Wiegley wrote:

> First, let's make text-quoting-style customizable, as this can definitely make
> it into 26.1. *Then*, we can start a discussion on whether to change it
> further, as you've proposed. Whether this will happen in 26.1 is another
> question, but at least we'll get the customization point out of the way.

OK, I'll work on transforming that patch.  It shouldn't take me long.

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

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[John Wiegley]

>>>>> "AM" == Alan Mackenzie <acm@muc.de> writes:

AM> OK, I'll work on transforming that patch. It shouldn't take me long.

That's great, Alan, thank you for acting on this quickly!

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

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, John.

On Fri, Sep 22, 2017 at 12:46:03 -0700, John Wiegley wrote:
> >>>>> "AM" == Alan Mackenzie <acm@muc.de> writes:

> AM> OK, I'll work on transforming that patch. It shouldn't take me long.

> That's great, Alan, thank you for acting on this quickly!

That's the job done!  Time for bed.

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

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, John and Eli.

On Fri, Sep 22, 2017 at 22:07:00 +0000, Alan Mackenzie wrote:
> On Fri, Sep 22, 2017 at 12:46:03 -0700, John Wiegley wrote:
> > >>>>> "AM" == Alan Mackenzie <acm@muc.de> writes:

> > AM> OK, I'll work on transforming that patch. It shouldn't take me long.

> > That's great, Alan, thank you for acting on this quickly!

> That's the job done!  Time for bed.

Is there anything standing in the way of me merging this branch into
emacs-26 now?

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[Paul Eggert]

Alan Mackenzie wrote:
> Is there anything standing in the way of me merging this branch into
> emacs-26 now?

Although the code part of that branch looks good, the documentation patch still 
has significant unaddressed problems, first mentioned here:

http://lists.gnu.org/archive/html/emacs-devel/2017-09/msg00775.html

with followup discussion ongoing as of today. Your latest proposal continues to 
recommend an awkward text-quoting-style programming technique used nowhere in 
Emacs, while refusing to mention the technique that is actually used. (Also, 
it's too wordy.) This needs to be fixed, and I trust that the ongoing discussion 
will help do that.

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, Paul.

On Sun, Sep 24, 2017 at 11:26:55 -0700, Paul Eggert wrote:
> Alan Mackenzie wrote:
> > Is there anything standing in the way of me merging this branch into
> > emacs-26 now?

> Although the code part of that branch looks good, the documentation patch still 
> has significant unaddressed problems, first mentioned here:

> http://lists.gnu.org/archive/html/emacs-devel/2017-09/msg00775.html

> with followup discussion ongoing as of today. Your latest proposal
> continues to recommend an awkward text-quoting-style programming
> technique ....

Ruhbish!  It suggests the natural and economical way, the way used
countless times for many, many purposes throughout Emacs.

> used nowhere in Emacs, ....

There are historical reasons for that, which I doubt you want to go into
at the moment.  Those reasons no longer hold.

> .... while refusing to mention the technique that is actually used.

It's used once, in cc-engine.el (and that might well change).  It's a
bizarre and poor technique, unnecessarily putting a single conversion
through `format'-like operations twice.

I think that a typical hacker, with awareness of both techniques, is
going to chose binding text-quoting-style rather than the double format
alternative.

> (Also, it's too wordy.) This needs to be fixed, and I trust that the
> ongoing discussion will help do that.

When you introduce something like curly quotes to Emacs, there is bound
to be a lot of documentation needed about it.  I don't think your way of
dealing with this, namely fragmenting the documentation of three
functions, is the right way.

But I suggest that neither of us is in a position to give a definitive
unbiassed judgment of the point.  Let's wait for more level-headed
people to express their viewpoint.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[John Wiegley]

>>>>> "AM" == Alan Mackenzie <acm@muc.de> writes:

AM> But I suggest that neither of us is in a position to give a definitive
AM> unbiassed judgment of the point. Let's wait for more level-headed people
AM> to express their viewpoint.

I've been scanning the messages in this thread, but I must admit I'm not
seeing the forest for the trees. Can someone summarize the points to be
decided here?

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

Re: Emacs 26.1 release branch created

[Paul Eggert]

John Wiegley wrote:
> I've been scanning the messages in this thread, but I must admit I'm not
> seeing the forest for the trees. Can someone summarize the points to be
> decided here?

The main issue is whether text-quoting-style should be customizable, as opposed 
to being a simple Lisp variable as it is now. Eli said "no", you said "yes", and 
as I recall this issue was unresolved the last time it was mentioned on this 
list. (I don't care, myself.)

The latest email flurry is minor by comparison. The main issues there are about 
the Elisp manual, and are:

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

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

Re: Emacs 26.1 release branch created

[John Wiegley]

>>>>> "PE" == Paul Eggert <eggert@cs.ucla.edu> writes:

PE> The main issue is whether text-quoting-style should be customizable, as
PE> opposed to being a simple Lisp variable as it is now. Eli said "no", you
PE> said "yes", and as I recall this issue was unresolved the last time it was
PE> mentioned on this list. (I don't care, myself.)

It will be customizable, this is decided, as Eli has told me he's OK with it.

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

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

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.

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

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 <eggert@cs.ucla.edu> 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).

RE: Emacs 26.1 release branch created

[Drew Adams]

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

Another difference between the two (of course): With #1
you can easily control the scope of the effect.

For example, you can use a single such `let' for multiple
such messages.  And you can of course do this at any depth.
And you can override that locally at some depth using another
`let', binding a different value to `text-quoting-style'.

Re: Emacs 26.1 release branch created

[John Wiegley]

>>>>> "DA" == Drew Adams <drew.adams@oracle.com> writes:

DA> Another difference between the two (of course): With #1 you can easily
DA> control the scope of the effect.

DA> For example, you can use a single such `let' for multiple such messages.
DA> And you can of course do this at any depth. And you can override that
DA> locally at some depth using another `let', binding a different value to
DA> `text-quoting-style'.

Why not mention both ways of resolving the matter in the documentation?
(message "%s") for all the simple cases (which should be most of them), and
let-binding text-quoting-style for the complex cases. Programmers should
really know about both.

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

Re: Emacs 26.1 release branch created

[Paul Eggert]

On 09/25/2017 01:24 PM, John Wiegley wrote:
> Why not mention both ways of resolving the matter in the documentation?
> (message "%s") for all the simple cases (which should be most of them), and
> let-binding text-quoting-style for the complex cases.

Because the complex cases are where the let-binding style falls down. 
For example, this plausible-looking code:

    (let ((text-quoting-style 'grave))
      (message "(setq coding-system '%S)"
               (find-operation-coding-system 'write-region "x")))

is incorrect, because it changes the quoting style not just for the 
message, but also for the internals of find-operation-coding-system, 
internals that are unrelated to the message and which will behave 
contrary to user preference. In contrast, this:

   (message "%s" (format "(setq coding-system '%S)"
                         (find-operation-coding-system 'write-region "x")))

limits the style override to just the format, which is what is typically 
wanted for messages.As the size of the 'let' increases, this sort of 
error becomes more likely.

The let-binding approach is appropriate only for simple cases where you 
know all the code that will be executed inside the 'let', and know that 
you want to override user preference for all of the code. It is 
inflexible and error-prone compared to the easier-to-use '(message "%s" 
...)' style that Emacs has used for decades.This is not a close call: we 
should document what has worked rather than try to promote an 
experimental alternative that has no significant technical advantages.

RE: Emacs 26.1 release branch created

[Drew Adams]

> (let ((text-quoting-style 'grave))
>   (message "(setq coding-system '%S)"
>            (find-operation-coding-system 'write-region "x")))
> 
> is incorrect, because it changes the quoting style not just for the
> message, but also for the internals of find-operation-coding-system,
> internals that are unrelated to the message and which will behave
> contrary to user preference.

So don't do that.  Just because you _can_ try to evaluate
`(cons 42)', that doesn't mean it is usually a great idea
to do so.

> The let-binding approach is appropriate only for simple cases
> where you know all the code that will be executed inside the 'let',

On the contrary (see RMS URL below).  It is especially
useful where you do NOT know all of the code that will
be executed within the dynamic extent of the `let' -
BUT where you are sure that you want all of that code
to respect such a binding.

That's the point.  The point of control is at the
`(let...)': it's there that you express your intent
wrt `text-quoting-style'.

If you don't know the extent over which you want a
setting of that variable to last in some context
then perhaps you shouldn't be using it.  Or dig in
and find an appropriate place for it.  It's about
what you want: where and when you want the setting
to hold.

The point is that you _can_ use it to control a
given extent of processing - even processing that
you don't know in detail or whose code you cannot
change.

That's the power of using `let' here: control the
extent of a given quote-behavior setting.

> and know that you want to override user preference

Gee, I thought you didn't look at `text-quoting-style'
as expressing a user preference, and so didn't want
it to be a user option.  Now it's a user preference
all of a sudden?  Hoorah.

> for all of the code. It is inflexible and error-prone
> compared to the easier-to-use '(message "%s" ...)'

Binding the variable is _more_ flexible, not less.
Whether it is also more error prone as a result of that
I won't argue.  It's true that to use `let' you need to
know what `let' does and pay attention to that.  Use it
wrong and errors can result.

> style that Emacs has used for decades.

Uh, let-binding dynamic variables is as old as the hills.
It's older than Emacs (and that's saying something).

> This is not a close call: we should document what has
> worked rather than try to promote an experimental
> alternative that has no significant technical advantages.

Ah, so you too prefer tried-and-true `let'? ;-)

The `let' approach is more flexible and more powerful.
It gives you more control over the scope (extent, really).
Do it where/when it makes sense to do it.  At least you
have a choice, and it is _easy_ to choose the extent of
its coverage.

Your ability to create straw-man examples of _bad_ uses
of `let' - inappropriate extent - shows nothing, except
that you are able to create bad uses of `let'.

The difference is not at all about "simple" vs "complex"
cases.  (I disagree with you and John about this.)  `let'
is appropriate for _both_ simple and complex cases - it
is simply more flexible.  Do with it what you will.

And yes, as it is more flexible you can certainly shoot
yourself in the foot with it.  This is Lisp.

https://www.gnu.org/software/emacs/emacs-paper.html#SEC15

Re: Emacs 26.1 release branch created

[Paul Eggert]

Drew Adams wrote:

> I thought you didn't look at `text-quoting-style'
> as expressing a user preference,

Perhaps you're confusing me with someone else? I don't recall expressing an 
opinion on the topic. In the current thread I explicitly said I didn't care.

> Binding the variable is _more_ flexible, not less.
> Whether it is also more error prone as a result of that
> I won't argue.

I'm written quite a bit of of code that does text quoting, and this practical 
experience tells me that the let-binding approach is less desirable, partly 
because it's more verbose, partly because because it tends to affect more 
behavior than it should. Theoretical arguments to the contrary are less 
convincing. Although let-binding has its place, this isn't it.

Re: Emacs 26.1 release branch created

[Philipp Stephani]

[-- Attachment #1: Type: text/plain, Size: 522 bytes --]

Drew Adams <drew.adams@oracle.com> schrieb am Di., 26. Sep. 2017 um
04:53 Uhr:

>
> Uh, let-binding dynamic variables is as old as the hills.
> It's older than Emacs (and that's saying something).
> <https://www.gnu.org/software/emacs/emacs-paper.html#SEC15>


It's still no good. Dynamic variables are global mutable state, with all
its downsides.
Early Lisps had only dynamic binding because people didn't know better. But
now we know that global mutable state is almost always undesirable and
avoid id wherever we can.

[-- Attachment #2: Type: text/html, Size: 874 bytes --]

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, Philipp.

On Tue, Sep 26, 2017 at 19:28:07 +0000, Philipp Stephani wrote:
> Drew Adams <drew.adams@oracle.com> schrieb am Di., 26. Sep. 2017 um
> 04:53 Uhr:

> > Uh, let-binding dynamic variables is as old as the hills.
> > It's older than Emacs (and that's saying something).
> > <https://www.gnu.org/software/emacs/emacs-paper.html#SEC15>


> It's still no good. Dynamic variables are global mutable state, with all
> its downsides.

And upsides.  And upside downs.

> Early Lisps had only dynamic binding because people didn't know better. But
> now we know that global mutable state is almost always undesirable and
> avoid id wherever we can.

But my buffers are global mutable states.  The whole world is a global
mutable state.  Literally.  How can we model them without such things in
our languages?  Why would we want to?

But you're trolling, aren't you?

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[Alexis]

Alan Mackenzie <acm@muc.de> writes:

> But my buffers are global mutable states.  The whole world is a 
> global
> mutable state.  Literally.  How can we model them without such 
> things
> in our languages?

See: Haskell. :-)

For those thinking "But Haskell is just an academic
programming language!", see:

https://github.com/commercialhaskell/commercialhaskell

> Why would we want to?

http://www.lispcast.com/the-world-is-mutable

> But you're trolling, aren't you?

i didn't get that feeling from Philipp's post, but i might be 
wrong.


Alexis.

Re: Emacs 26.1 release branch created

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

If you want to argue based on the premise that side effects are bad,
please take it elsewhere.  The GNU Project does not accept that
premise.

Anyway, we do not want to rewrite GNU Emacs in another language.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: Emacs 26.1 release branch created

[Alexis]

Richard Stallman <rms@gnu.org> writes:

> If you want to argue based on the premise that side effects are 
> bad,
> please take it elsewhere.  The GNU Project does not accept that
> premise.

Okay, i respect that position.

> Anyway, we do not want to rewrite GNU Emacs in another language.

i'm certainly not arguing for that! Indeed, i've made several 
posts to
Reddit criticising that idea on various grounds, even going so far 
as to
write a satirical post about the notion of rewriting Emacs in
JavaScript. i only mentioned Haskell in response to (what seemed 
to me
to be) the implication that discouraging global mutable state 
makes it
inherently impractical to deal with concepts such as buffers.

At any rate, i'll not comment any further on this issue here.


Alexis.

Re: Emacs 26.1 release branch created

[Óscar Fuentes]

Alexis <flexibeast@gmail.com> writes:

> For those thinking "But Haskell is just an academic
> programming language!", see:
>
> https://github.com/commercialhaskell/commercialhaskell

It seems to me that that page is not what you think.

I like the idea of immutability but...

>> Why would we want to?
>
> http://www.lispcast.com/the-world-is-mutable

... this is the poorest and most ridiculous defense of immutability I've
ever read. It makes me think that the author does not understand what it
is about. But then I realized that the article is just a silly advert
for some product sold by the author.

Please do not spam this mailing list.

Re: Emacs 26.1 release branch created

[Alexis]

Óscar Fuentes <ofv@wanadoo.es> writes:

> Alexis <flexibeast@gmail.com> writes:
>
>> For those thinking "But Haskell is just an academic
>> programming language!", see:
>>
>> https://github.com/commercialhaskell/commercialhaskell
>
> It seems to me that that page is not what you think.

It seems to me to be a page of organisations and individuals that 
have
an interest in using Haskell in a commercial setting. But i guess 
the
argument could be made: "They might be /interested/ in doing so, 
but
that doesn't mean they're /actually/ doing so." Okay:

https://wiki.haskell.org/Haskell_in_industry

And in terms of writing an /editor/ in a mutability-discouraging
context, there's Yi:

https://en.wikipedia.org/wiki/Yi_(editor)

i'm only linking to these things to demonstrate that it's possible 
to
write 'real-world' software in a context where global mutable 
state is
discouraged, in order to counter the idea that such an approach is
/necessarily/ impractical. That's all; nothing more than 
that. Richard
has said that the GNU Project does not accept the premise that 
side
effects are bad, and i respect that position.

> I like the idea of immutability but...
>
>>> Why would we want to?
>>
>> http://www.lispcast.com/the-world-is-mutable
>
> ... this is the poorest and most ridiculous defense of 
> immutability
> I've ever read. It makes me think that the author does not 
> understand
> what it is about. But then I realized that the article is just a 
> silly
> advert for some product sold by the author.
>
> Please do not spam this mailing list.

Okay, i'm sorry. i'll be much more careful about any links i post 
in the
future.


Alexis.

Re: Emacs 26.1 release branch created

[Philippe Vaucher]

[-- Attachment #1: Type: text/plain, Size: 758 bytes --]

>
> > Early Lisps had only dynamic binding because people didn't know better.
> But
> > now we know that global mutable state is almost always undesirable and
> > avoid id wherever we can.
>
> But my buffers are global mutable states.  The whole world is a global
> mutable state.  Literally.  How can we model them without such things in
> our languages?  Why would we want to?
>

I think this is the wrong way to approach this. What counts here are the
benefits: by avoiding global mutable state we make code that is easier to
reason about, easier to test, etc.
There is simply no real argument for using global mutable state when we can
avoid it, except for somewhat weak arguments like "it's convenient" or
"it'd require too much refactoring".

Philippe

[-- Attachment #2: Type: text/html, Size: 1097 bytes --]

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, Philippe.

On Wed, Sep 27, 2017 at 13:54:29 +0200, Philippe Vaucher wrote:

> > > Early Lisps had only dynamic binding because people didn't know better.
> > But
> > > now we know that global mutable state is almost always undesirable and
> > > avoid id wherever we can.

> > But my buffers are global mutable states.  The whole world is a global
> > mutable state.  Literally.  How can we model them without such things in
> > our languages?  Why would we want to?


> I think this is the wrong way to approach this. What counts here are the
> benefits: by avoiding global mutable state we make code that is easier to
> reason about, easier to test, etc.

What about the costs?  Emacs has a large state, including variable
numbers of buffers, variable variables (libraries can be loaded at any
time), variable properties and text properties, ....

What you're asserting, I think, is that there is a better way to house
this state rather than "globally".  No details of this other way have
been forthcoming.

> There is simply no real argument for using global mutable state when we can
> avoid it, .....

I suspect that in Emacs we can't.  Or if we could, it would be at too
great a cost.

> .... except for somewhat weak arguments like "it's convenient" or
> "it'd require too much refactoring".

They're weak arguments?  I'd like to hear what might be considered
strong ones!

> Philippe

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[Philippe Vaucher]

[-- Attachment #1: Type: text/plain, Size: 1070 bytes --]

>
> > I think this is the wrong way to approach this. What counts here are the
> > benefits: by avoiding global mutable state we make code that is easier to
> > reason about, easier to test, etc.
>
> What about the costs?  Emacs has a large state, including variable
> numbers of buffers, variable variables (libraries can be loaded at any
> time), variable properties and text properties, ....
>
> What you're asserting, I think, is that there is a better way to house
> this state rather than "globally".  No details of this other way have
> been forthcoming.
>
> > There is simply no real argument for using global mutable state when we
> can
> > avoid it, .....
>
> I suspect that in Emacs we can't.  Or if we could, it would be at too
> great a cost.
>

Yes, probably that in Emacs the costs would be too big. My point was about
you defending global mutable state as something that is fine to use all the
time when it is not.

Anyway, this subject is not really welcome and wouldn't be very productive
anyway, so I'll remain silent on that issue.

Thanks,
Philippe

[-- Attachment #2: Type: text/html, Size: 1487 bytes --]

RE: Emacs 26.1 release branch created

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 1445 bytes --]

Uh, let-binding dynamic variables is as old as the hills.
It's older than Emacs (and that's saying something).

 

It's still no good. Dynamic variables are global mutable state, with all its downsides.

 

Of course they are. With all their upsides and downsides. Nothing new here.

 

Early Lisps had only dynamic binding because people didn't know better. But now we know that global mutable state is almost always undesirable and avoid id wherever we can.

 

There's nothing new about knowing that global mutable state can be problematic, both for users and language optimizers. Old as the sea.

 

HYPERLINK "http://library.readscheme.org/page1.html"Lexical binding for Lisp was available before Emacs Lisp. It was actively discussed in Lisp circles at the time, in particular in the context of designing Common Lisp. I'm sure RMS was quite well aware of it - its advantages as well as its limitations.

 

He used dynamic binding for Emacs not because he "didn't know better". In the article I cited he tells you clearly HYPERLINK "https://www.gnu.org/software/emacs/emacs-paper.html#SEC15"why dynamic binding is important ("vital" was the word he used) for an application like Emacs. Those reasons are just as valid today as when they were written.

 

But you're free to propose that Emacs Lisp should not have user options and other global variables.

 

("Now we know", indeed. Such hubris.)

[-- Attachment #2: Type: text/html, Size: 5135 bytes --]

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> Date: Mon, 25 Sep 2017 19:52:22 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> > (let ((text-quoting-style 'grave))
> >   (message "(setq coding-system '%S)"
> >            (find-operation-coding-system 'write-region "x")))
> > 
> > is incorrect, because it changes the quoting style not just for the
> > message, but also for the internals of find-operation-coding-system,
> > internals that are unrelated to the message and which will behave
> > contrary to user preference.
> 
> So don't do that.  Just because you _can_ try to evaluate
> `(cons 42)', that doesn't mean it is usually a great idea
> to do so.

We are talking about what to say in the manual.  That some particular
way of achieving things isn't mentioned in the manual doesn't yet mean
it doesn't work when used correctly.

This all is a side lobe of the current discussion, let's not allow
ourselves to be distracted from the main issue at hand.

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> Date: Mon, 25 Sep 2017 12:43:44 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, Paul Eggert <eggert@cs.ucla.edu>,
>         rms@gnu.org
> 
> > 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)
> 
> Another difference between the two (of course): With #1
> you can easily control the scope of the effect.
> 
> For example, you can use a single such `let' for multiple
> such messages.  And you can of course do this at any depth.
> And you can override that locally at some depth using another
> `let', binding a different value to `text-quoting-style'.

The above use case is a marginal one: there's rarely a reason to
display symbols like 'foo in echo-area messages, let alone in a series
of such messages.

So let's not let marginal use cases drive this discussion, which is
complex enough already.

FWIW, Paul's proposal sounds better to me, for the purposes of
documenting the "fire escape".

RE: Emacs 26.1 release branch created

[Drew Adams]

> > > 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)
> >
> > Another difference between the two (of course): With #1
> > you can easily control the scope of the effect.
> >
> > For example, you can use a single such `let' for multiple
> > such messages.  And you can of course do this at any depth.
> > And you can override that locally at some depth using another
> > `let', binding a different value to `text-quoting-style'.
> 
> The above use case is a marginal one: there's rarely a reason to
> display symbols like 'foo in echo-area messages, let alone in a series
> of such messages.

I agree.  It was Paul's (or Alan's?) example, not mine.

> So let's not let marginal use cases drive this discussion,
> which is complex enough already.

Marginal use cases are not driving what I've said in this
discussion - at all.  That's why I emphasized the greater
flexibility of using `let' - easy to use for both marginal
and more significant use cases.

> FWIW, Paul's proposal sounds better to me, for the purposes
> of documenting the "fire escape".

Wunderbar - but you don't say _why_ it is better for that
documentation purpose.

But I'm guessing its because you look at this little bit of
doc as essentially a footnote - hiding `text-quoting-style'
in plain sight.  Now you see it; now you don't.

Calling reverting curly-quoting just a "fire escape"
suggests a desire not to have to offer `text-quoting-style'
at all - thinking of it reluctantly as a perhaps necessary
eyesore and bother, fit only for the back alley.

That's not the way I look at `text-quoting-style' or its
doc.  I don't see user control over pandemic curly-quotitis
as being just a fire escape - something to use only in case
of emergency.

The first question to decide is whether `text-quoting-style'
should be a user option.  I say yes (as does Paul himself,
apparently).  When the whole city is on fire little is more
important that finding a formerly inconspicuous fire escape
or fire hydrant - a welcome eyesore, if ever there was one.

Re: Emacs 26.1 release branch created

[Paul Eggert]

Drew Adams wrote:
> The first question to decide is whether `text-quoting-style'
> should be a user option.  I say yes (as does Paul himself,
> apparently).

No, I've said I have no opinion. That is, I don't care whether 
text-quoting-style is customizable.  Anyway, this issue is moot as the 
maintainers have decided it.

RE: Emacs 26.1 release branch created

[Drew Adams]

> > The first question to decide is whether `text-quoting-style'
> > should be a user option.  I say yes (as does Paul himself,
> > apparently).
> 
> No, I've said I have no opinion.

You're right.  Sorry for misremembering.

You did, however, refer to let-binding it as overriding user
preference, which is considered (here, not by me) a no-no
for user options (only?).

Re: Emacs 26.1 release branch created

[Paul Eggert]

[-- Attachment #1: Type: text/plain, Size: 1608 bytes --]

On 09/25/2017 12:03 PM, Alan Mackenzie wrote:
> At the moment, there is a single known example in the Emacs lisp code

There are plenty of examples other than the one you noticed in 
cc-engine.el. For example, here's one in shell.el's 
shell-dirstack-message function:

    (message "%s" msg)

MSG is a string containing directory names followed by spaces, and the 
"%s" avoids translation of directory names that happen to contain grave 
accents or apostrophes (or percents, for that matter). This is a common 
programming technique in Emacs source code, and has been for decades.

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

Sure, that's easy. Revised patch attached.

> How about merging this change into emacs-26 anyway, now?

I now see one minor error in the scratch/customize-quotes patch, which 
is that its etc/NEWS file incorrectly states ", except that 
'text-quoting-style' no longer affects the treatment of curved quotes in 
format arguments to functions like 'message' and 'format-message'", a 
phrase that appears to be a stray leftover from an earlier version of 
your proposal. The attached patch fixes that, and also has been rebased 
to apply after the scratch/customize-quotes is merged in, so I suggest 
that you merge scratch/customize-quotes and that I then apply the 
attached patch.

[-- Attachment #2: 0001-Improve-text-quoting-style-doc-in-lispref.txt --]
[-- Type: text/plain, Size: 12740 bytes --]

From 61d118e52b971300ecec5e0a5e404631d51e372e Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Mon, 25 Sep 2017 16:29:51 -0700
Subject: [PATCH] Improve text-quoting-style doc in lispref

* doc/lispref/control.texi (Signaling Errors):
* doc/lispref/display.texi (Displaying Messages):
* doc/lispref/strings.texi (Formatting Strings):
Edit for brevity, farming out the details to the new
Text Quoting Style node.
* doc/lispref/help.texi (Text Quoting Style): New section.
Move detailed discussion of text-quoting-style here.
Add discussion about how to output grave accent and apostrophe in
documentation and messages.  Adjust xrefs to point to this section
when appropriate.
* etc/NEWS: text-quoting-style semantics have not changed.
---
 doc/lispref/control.texi | 14 +++--------
 doc/lispref/display.texi | 16 ++++--------
 doc/lispref/elisp.texi   |  1 +
 doc/lispref/help.texi    | 64 ++++++++++++++++++++++++++++++++++--------------
 doc/lispref/strings.texi | 15 +++---------
 doc/lispref/tips.texi    |  4 +--
 etc/NEWS                 |  6 ++---
 7 files changed, 63 insertions(+), 57 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index c39e035459..4eddbe9c12 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -1101,16 +1101,10 @@ Signaling Errors
 error symbol @code{error}, and a list containing the string returned by
 @code{format-message}.
 
-The @code{text-quoting-style} variable controls what quotes are
-generated; @xref{Keys in Documentation}.  A call using a format like
-@t{"Missing `%s'"} with grave accents and apostrophes typically
-generates a message like @t{"Missing ‘foo’"} with matching curved
-quotes.  In contrast, a call using a format like @t{"Missing '%s'"}
-with only apostrophes typically generates a message like @t{"Missing
-’foo’"} with only closing curved quotes, an unusual style in English.
-One way around this problem is to bind @code{text-quoting-style} to
-the symbol @code{grave} around the call to @code{error}; this causes
-@acronym{ASCII} quote characters to be output unchanged.
+Typically grave accent and apostrophe in the format translate to
+matching curved quotes, e.g., @t{"Missing `%s'"} might result in
+@t{"Missing ‘foo’"}.  @xref{Text Quoting Style}, for how to influence
+or inhibit this translation.
 
 @strong{Warning:} If you want to use your own string as an error message
 verbatim, don't just write @code{(error @var{string})}.  If @var{string}
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 62b136f6c6..afd09cfb33 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -265,16 +265,10 @@ Displaying Messages
 The string is also added to the @file{*Messages*} buffer, but without
 text properties (@pxref{Logging Messages}).
 
-The @code{text-quoting-style} variable controls what quotes are
-generated; @xref{Keys in Documentation}.  A call using a format like
-@t{"Missing `%s'"} with grave accents and apostrophes typically
-generates a message like @t{"Missing ‘foo’"} with matching curved
-quotes.  In contrast, a call using a format like @t{"Missing '%s'"}
-with only apostrophes typically generates a message like @t{"Missing
-’foo’"} with only closing curved quotes, an unusual style in English.
-One way around this problem is to bind @code{text-quoting-style} to
-the symbol @code{grave} around calls to @code{message}; this causes
-@acronym{ASCII} quote characters to be output unchanged.
+Typically grave accent and apostrophe in the format translate to
+matching curved quotes, e.g., @t{"Missing `%s'"} might result in
+@t{"Missing ‘foo’"}.  @xref{Text Quoting Style}, for how to influence
+or inhibit this translation.
 
 In batch mode, the message is printed to the standard error stream,
 followed by a newline.
@@ -7038,7 +7032,7 @@ Active Display Table
 is outputting text to the standard output or error streams.  Although its
 default is typically @code{nil}, in an interactive session if the
 terminal cannot display curved quotes, its default maps curved quotes
-to ASCII approximations.  @xref{Keys in Documentation}.
+to ASCII approximations.  @xref{Text Quoting Style}.
 @end defvar
 
 The @file{disp-table} library defines several functions for changing
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 4cbcdf855d..c752594584 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -940,6 +940,7 @@ Top
 * Documentation Basics::    Where doc strings are defined and stored.
 * Accessing Documentation:: How Lisp programs can access doc strings.
 * Keys in Documentation::   Substituting current key bindings.
+* Text Quoting Style::      Quotation marks in doc strings and messages.
 * Describing Characters::   Making printable descriptions of
                               non-printing characters and key sequences.
 * Help Functions::          Subroutines used by Emacs help facilities.
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 74dc6dac9c..5fc18785b6 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -33,6 +33,7 @@ Documentation
 * Documentation Basics::      Where doc strings are defined and stored.
 * Accessing Documentation::   How Lisp programs can access doc strings.
 * Keys in Documentation::     Substituting current key bindings.
+* Text Quoting Style::        Quotation marks in doc strings and messages.
 * Describing Characters::     Making printable descriptions of
                                 non-printing characters and key sequences.
 * Help Functions::            Subroutines used by Emacs help facilities.
@@ -336,6 +337,7 @@ Keys in Documentation
 (grave accent) stands for a left quote.
 This generates a left single quotation mark, an apostrophe, or a grave
 accent depending on the value of @code{text-quoting-style}.
+@xref{Text Quoting Style}.
 
 @item '
 (apostrophe) stands for a right quote.
@@ -351,25 +353,6 @@ Keys in Documentation
 @strong{Please note:} Each @samp{\} must be doubled when written in a
 string in Emacs Lisp.
 
-@defopt text-quoting-style
-@cindex curved quotes
-@cindex curly quotes
-The value of this variable is a symbol that specifies the style Emacs
-should use for single quotes in the wording of help and messages.  If
-the variable's value is @code{curve}, the style is @t{‘like this’}
-with curved single quotes.  If the value is @code{straight}, the style
-is @t{'like this'} with straight apostrophes.  If the value is
-@code{grave}, quotes are not translated and the style is @t{`like
-this'} with grave accent and apostrophe, the standard style before
-Emacs version 25.  The default value @code{nil} acts like @code{curve}
-if curved single quotes seem to be displayable, and like @code{grave}
-otherwise.
-
-This option is useful on platforms that have problems with curved
-quotes.  You can customize it freely according to your personal
-preference.
-@end defopt
-
 @defun substitute-command-keys string
 This function scans @var{string} for the above special sequences and
 replaces them by what they stand for, returning the result as a string.
@@ -428,6 +411,49 @@ Keys in Documentation
 strings---for instance, you can refer to functions, variables, and
 sections of this manual.  @xref{Documentation Tips}, for details.
 
+@node Text Quoting Style
+@section Text Quoting Style
+
+  Typically, grave accents and apostrophes are treated specially in
+documentation strings and diagnostic messages, and translate to matching
+single quotation marks (also called ``curved quotes'').  For example,
+the documentation string @t{"Alias for `foo'."} and the function call
+@code{(message "Alias for `foo'.")} both translate to @t{"Alias for
+‘foo’."}.  Less commonly, Emacs displays grave accents and apostrophes
+as themselves, or as apostrophes only (e.g., @t{"Alias for 'foo'."}).
+Documentation strings and message formats should be written so that
+they display well with any of these styles.  For example, the
+documentation string @t{"Alias for 'foo'."} is probably not what you
+want, as it can display as @t{"Alias for ’foo’."}, an unusual style in
+English.
+
+  Sometimes you may need to display a grave accent or apostrophe
+without translation, regardless of text quoting style.  In a
+documentation string, you can do this with escapes.  For example, in
+the documentation string @t{"\\=`(a ,(sin 0)) ==> (a 0.0)"} the grave
+accent is intended to denote Lisp code, so it is escaped and displays
+as itself regardless of quoting style.  In a call to @code{message} or
+@code{error}, you can avoid translation by using a format @t{"%s"}
+with an argument that is a call to @code{format}.  For example,
+@code{(message "%s" (format "`(a ,(sin %S)) ==> (a %S)" x (sin x)))}
+displays a message that starts with grave accent regardless of text
+quoting style.
+
+@defvar text-quoting-style
+@cindex curved quotes
+@cindex curly quotes
+The value of this variable is a symbol that specifies the style Emacs
+should use for single quotes in the wording of help and messages.  If
+the variable's value is @code{curve}, the style is @t{‘like this’}
+with curved single quotes.  If the value is @code{straight}, the style
+is @t{'like this'} with straight apostrophes.  If the value is
+@code{grave}, quotes are not translated and the style is @t{`like
+this'} with grave accent and apostrophe, the standard style before
+Emacs version 25.  The default value @code{nil} acts like @code{curve}
+if curved single quotes are displayable, and like @code{grave}
+otherwise.
+@end defvar
+
 @node Describing Characters
 @section Describing Characters for Help Messages
 @cindex describe characters and events
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 10385e0550..1fb1a0e148 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -826,21 +826,14 @@ Formatting Strings
 @defun format-message string &rest objects
 @cindex curved quotes, in formatted messages
 @cindex curly quotes, in formatted messages
-@cindex @code{text-quoting-style}, and formatting messages
 This function acts like @code{format}, except it also converts any
 grave accents (@t{`}) and apostrophes (@t{'}) in @var{string} as per the
 value of @code{text-quoting-style}.
 
-A format that quotes with grave accents and apostrophes @t{`like
-this'} typically generates curved quotes @t{‘like this’}.  In
-contrast, a format that quotes with only apostrophes @t{'like this'}
-typically generates two closing curved quotes @t{’like this’}, an
-unusual style in English.  One way around such problems is to bind
-@code{text-quoting-style} to the symbol @code{grave} around calls to
-@code{format-message}; this causes @acronym{ASCII} quoting characters
-to be output unchanged.  @xref{Keys in Documentation}, for how the
-@code{text-quoting-style} variable affects generated quotes.
-@end defun
+Typically grave accent and apostrophe in the format translate to
+matching curved quotes, e.g., @t{"Missing `%s'"} might result in
+@t{"Missing ‘foo’"}.  @xref{Text Quoting Style}, for how to influence
+or inhibit this translation.
 
 @cindex @samp{%} in format
 @cindex format specification
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index bed3bed95b..73b5224bc3 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -680,8 +680,8 @@ Documentation Tips
 older convention was designed for now-obsolete displays in which grave
 accent and apostrophe were mirror images.
 Documentation using this convention is converted to the user's
-preferred format when it is copied into a help buffer.  @xref{Keys in
-Documentation}.
+preferred format when it is copied into a help buffer.  @xref{Text
+Quoting Style}.
 
 @cindex hyperlinks in documentation strings
 Help mode automatically creates a hyperlink when a documentation string
diff --git a/etc/NEWS b/etc/NEWS
index 755893b9b5..634a3600d1 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1234,10 +1234,8 @@ change FOO, respectively.  The exhaustive list of removed variables is:
 ** The variable 'text-quoting-style' is now a customizable option.  It
 controls whether to and how to translate ASCII quotes in messages and
 help output.  Its possible values and their semantics remain unchanged
-from Emacs 25, except that 'text-quoting-style' no longer affects the
-treatment of curved quotes in format arguments to functions like
-'message' and 'format-message'.  In particular, when this variable's
-value is 'grave', all quotes in formats are output as-is.
+from Emacs 25.  In particular, when this variable's value is 'grave',
+all quotes in formats are output as-is.
 
 ---
 ** Functions like 'check-declare-file' and 'check-declare-directory'
-- 
2.13.5

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, Paul.

On Mon, Sep 25, 2017 at 16:36:28 -0700, Paul Eggert wrote:
> On 09/25/2017 12:03 PM, Alan Mackenzie wrote:

[ .... ]

> > How about merging this change into emacs-26 anyway, now?

> I now see one minor error in the scratch/customize-quotes patch, which 
> is that its etc/NEWS file incorrectly states ", except that 
> 'text-quoting-style' no longer affects the treatment of curved quotes in 
> format arguments to functions like 'message' and 'format-message'", a 
> phrase that appears to be a stray leftover from an earlier version of 
> your proposal. The attached patch fixes that, and also has been rebased 
> to apply after the scratch/customize-quotes is merged in, so I suggest 
> that you merge scratch/customize-quotes and that I then apply the 
> attached patch.

OK.  What I have done is to apply your patch, with a few changes, in
scratch/customize-quotes.  These changes concern text-quoting-style
being a user option rather than just a variable, acknowledging (with a
"seems to") that Emacs doesn't always correctly determine if certain
characters are displayable, and adding back the bit about the option
being "freely usable".  I think that's all.  In particular, there is no
longer a bit about binding t-q-s to the symbol grave to inhibit quote
translation.

If you want to check it for one last time, please do, otherwise I think
I should just merge it into emacs-26.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[Paul Eggert]

Alan Mackenzie wrote:
> If you want to check it for one last time, please do, otherwise I think
> I should just merge it into emacs-26.

Thanks, it looks good, except that in the latest commit an unrelated change 
crept into doc/lispref/syntax.texi - something about syntax-pps, which is a 
different topic. There should be no need to change doc/lispref/syntax.texi 
because of text-quoting-style, so I assume that part of the change was intended 
for some other patch and got added to the scratch/customize-quotes branch 
inadvertently.

Re: Emacs 26.1 release branch created

[Alan Mackenzie]

Hello, Paul.

On Sat, Sep 30, 2017 at 17:16:53 -0700, Paul Eggert wrote:
> Alan Mackenzie wrote:
> > If you want to check it for one last time, please do, otherwise I think
> > I should just merge it into emacs-26.

> Thanks, it looks good, except that in the latest commit an unrelated change 
> crept into doc/lispref/syntax.texi - something about syntax-pps, which is a 
> different topic. There should be no need to change doc/lispref/syntax.texi 
> because of text-quoting-style, so I assume that part of the change was intended 
> for some other patch and got added to the scratch/customize-quotes branch 
> inadvertently.

Sorry, that's exactly what happened.  I've fixed it now and merged
scratch/customize-quotes into emacs-26.

I think we're finished.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Emacs 26.1 release branch created

[Paul Eggert]

Alan Mackenzie wrote:
> Let's wait for more level-headed
> people to express their viewpoint.

John weighed in, so let's go with that. I suggest that you merge your code+doc 
branch (scratch/customize-quotes) into emacs-26. I'll then merge in the doc-only 
patch I proposed, along the lines that John suggested. After that we can discuss 
any further changes or fixes that are needed.

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> Date: Fri, 22 Sep 2017 18:41:59 +0000
> Cc: emacs-devel@gnu.org, rms@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> I thought the issues through carefully before investing time and energy
> in it.

So did I.  And I'm sure John did as well.  Let's please assume that
everybody involved in this discussion have their positions carefully
thought through.

> You talk about backward incompatibility.  Well, backward incomptibility
> is only bad when it inconveniences users, which is most of the time.  It
> isn't the case here.  Neither of you, nor Paul has suggested a scenario
> in which a user might suffer.  I put it to you that there aren't any,
> particularly considering how text-quoting-style was kept away from
> ordinary users in Emacs 25.

Why do we need a scenario?  This variable existed in its current
semantics since Emacs 25.1, released more than a year ago.  It was
introduced on the-then master a year before that.  Which means it's in
use for more than 2 years now.  Changing its semantics in incompatible
ways at this time would need a _very_ good reason.  IOW, it's _you_
who needs to provide us with convincing scenarios where the current
values cause serious trouble, so serious that backward-incompatible
change is a must.

> So, I'm asking you once more to consider very carefully the issues
> behind my proposed amendment.  For my part, I undertake to accept your
> decision on the matter without further argument, and to change the code
> in scratch/customize-quotes to the simple change you were expecting,
> should you say no again.

Please do, and thanks.

Re: Emacs 26.1 release branch created

[João Távora]

Eli Zaretskii <eliz@gnu.org> writes:

> put a few finishing touches or additions to those features, please ask
> here before pushing further changes that are not bugfixes.)

I noticed that the emacs-26 branch contains a half-baked version of the
flymake.el rewrite that I'm working on. More than a month ago, I asked
here whether this work, that I prematurely and mistankenly pushed to the
then-master branch in error, should be reverted.

Stefan said it "was going in the right direction", so it wasn't
reverted. The finished work isn't quite ready yet, so now I see these
alternatives:

1. Either the half-baked work is reverted in the emacs-26 branch; or

2. It is left in as-is. This is not recommended. Although
   it doesn't break any compatibility I know of, it's not good work
   at all. Among other things, it introduces a user-visible variable that I got
   rid of in the meantime.

3. "A few finishing touches" aka "makeup on a pig" are applied.

4. The bulk of my flymake rewrite somehow makes it into emacs-26 in
   time. It would be nice to see it in a release, but it's certainly not
   "a few finishing touches"

5. ?

Sorry for noticing this so late in the process.

The flymake rewrite is progressing quite nicely in the
scratch/flymake-refactor branch. It is mostly ready for review, I will
post here very soon.

João

Re: Emacs 26.1 release branch created

[John Wiegley]

>>>>> "JT" == João Távora <joaotavora@gmail.com> writes:

JT> 1. Either the half-baked work is reverted in the emacs-26 branch; or

I think it should be reverted in emacs-26, and marked as "don't merge".

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

Re: Emacs 26.1 release branch created

[João Távora]

John Wiegley <jwiegley@gmail.com> writes:

>>>>>> "JT" == João Távora <joaotavora@gmail.com> writes:
>
> JT> 1. Either the half-baked work is reverted in the emacs-26 branch; or
>
> I think it should be reverted in emacs-26, and marked as "don't merge".

Done in 7cf59c6 and ce540f8.

Thanks, João

Re: Emacs 26.1 release branch created

[João Távora]

John Wiegley <jwiegley@gmail.com> writes:

>>>>>> "JT" == João Távora <joaotavora@gmail.com> writes:
>
> JT> 1. Either the half-baked work is reverted in the emacs-26 branch; or
>
> I think it should be reverted in emacs-26, and marked as "don't merge".

Done in 7cf59c6 and ce540f8.

Thanks, João

Re: Emacs 26.1 release branch created

[John Wiegley]

>>>>> João Távora <joaotavora@gmail.com> writes:

> Done in 7cf59c6 and ce540f8.
> Thanks, João

Thank you for catching this before 26 went out!

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

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> From: joaotavora@gmail.com (João Távora)
> Date: Wed, 27 Sep 2017 19:09:53 +0100
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> 1. Either the half-baked work is reverted in the emacs-26 branch; or
> 
> 2. It is left in as-is. This is not recommended. Although
>    it doesn't break any compatibility I know of, it's not good work
>    at all. Among other things, it introduces a user-visible variable that I got
>    rid of in the meantime.
> 
> 3. "A few finishing touches" aka "makeup on a pig" are applied.
> 
> 4. The bulk of my flymake rewrite somehow makes it into emacs-26 in
>    time. It would be nice to see it in a release, but it's certainly not
>    "a few finishing touches"
> 
> 5. ?
> 
> Sorry for noticing this so late in the process.
> 
> The flymake rewrite is progressing quite nicely in the
> scratch/flymake-refactor branch. It is mostly ready for review, I will
> post here very soon.

I'm confused: why are there parts of this work on emacs-26, and other
parts on a scratch branch?  Does the latter continue where the former
left off? or is it an entirely different code?

Also, how long (calendar-wise) do you envision it to take you to get
to the point where the code is not "half-baked"?

Thanks.

Re: Emacs 26.1 release branch created

[João Távora]

Eli Zaretskii <eliz@gnu.org> writes:

> I'm confused: why are there parts of this work on emacs-26, and other
> parts on a scratch branch?

Sorry, I'm afraid this isn't easy to understand, though I believe John
has already and the matter is solved. Let me try again. As I explained
in the part that you cut out:

>> More than a month ago, I asked here whether this work, that I
>> prematurely and mistankenly pushed to the then-master branch in error,
>> should be reverted.

These are the two commits that I prematurely pushed to what was then master:

* 13993c46a2..: João Távora 2017-08-17 Add flymake-backends defcustom
* eb34f7f5a2..: João Távora 2017-08-17 Split flymake.el into flymake-proc.el and flymake-ui.el

Some days later, on Aug. 21, I noticed the mistake and wrote here
(https://lists.gnu.org/archive/html/emacs-devel/2017-08/msg00460.html)

>> Unfortunately, I seemed to have jumped the gun and inadvertently
>> pushed these commits into master instead of keeping them in the
>> scratch/flymake-refactor branch until I got some reviews, which
>> naturally was my intention. Sorry about that.
>> [... They don't break
>> anything, but] since they were pushed in error, I can revert them if
>> someone feels that's necessary.

The only reply that I got to this was Stefan's, on Aug. 22 who said the
work was going "in the right direction", so I shouldn't revert it. And I
didn't.

In the meantime I was sidetracked and you created emacs-26. So this is
why there is (rather "was", read below) this half-baked,
going-in-the-right-direction work on the emacs-26.

So a few days ago, the work was in both emacs-26 and on
master. Following John's opinion in this thread (and my first choice) I
reverted it on emacs-26 and marked it "don't merge". I took care that
this reversion kept minor bugfixes by Paul and Sam commited on top of it
in the meantime. The 'git revert' commits are:

* ce540f8a68..: João Távora 2017-09-27 Revert "Split flymake.el into flymake-proc.el and flymake-ui.el"
* 7cf59c6635..: João Távora 2017-09-27 Revert "Add flymake-backends defcustom"

Besides the title, the commit messages also explain the situation in
detail. So now, the half-baked work is only on master.

> Does the latter continue where the former
> left off? or is it an entirely different code?

It continues where the former left off, but very heavily expands on it,
and changes some early design decisions.

> Also, how long (calendar-wise) do you envision it to take you to get
> to the point where the code is not "half-baked"?

The code is 90% baked right now.

I requested comments yesterday, and Stefan's review (in the "Flymake
refactored" thread in this list) was very speedy and very productive
(naturally I would very much appreciate other opinions). I'm more than
halfway through integrating Stefan's suggestions, and none seem very
controversial. I'm very interested in getting this onto master ASAP,
since I have other pressing matters to attend to.

If you are considering opening an exception and letting it go to
emacs-26, I have this to say: the code is stable in my testing,
backwards compatible to both user and third-party lisp (with few
exceptions that I can detail). I have expanded the
automated test coverage quite a bit, fixed longstanding bugs, and
also started rewriting the documentation.

So I'd say:

* "one week" to master (where, AFAIU, doc and NEWS aren't showstoppers)
* "three weeks" to emacs-26 (NEWS, doc and polishing)

Obviously, less if someone helps out.

João

Re: Emacs 26.1 release branch created

[Eli Zaretskii]

> From: joaotavora@gmail.com (João Távora)
> Cc: monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Fri, 29 Sep 2017 18:04:03 +0100
> 
> So I'd say:
> 
> * "one week" to master (where, AFAIU, doc and NEWS aren't showstoppers)
> * "three weeks" to emacs-26 (NEWS, doc and polishing)
> 
> Obviously, less if someone helps out.

Thanks for explaining.  With this schedule, I see no reason not to
merge to emacs-26 when you are done.  Given that this code was on
master for quite some time, I see no reason to postpone it to Emacs
27.  Unless John objects, of course.

Re: Emacs 26.1 release branch created

[John Wiegley]

>>>>> "EZ" == Eli Zaretskii <eliz@gnu.org> writes:

EZ> Thanks for explaining. With this schedule, I see no reason not to merge to
EZ> emacs-26 when you are done. Given that this code was on master for quite
EZ> some time, I see no reason to postpone it to Emacs 27. Unless John
EZ> objects, of course.

No objection here.

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