Translation of single quotes in doc strings is now optional.

Translation of single quotes in doc strings is now optional.

[Alan Mackenzie]

Hello, Emacs.

I've just committed an enhancement to C-h f, C-h v, such that ` and '
are no longer translated mandatorily into their curly equivalents for
display.  There is a new customisable variable, `help-quote-translation'
(in the Help group) which takes one of the values nil (default),
'traditional, and 'prefer-unicode, which directs C-h f and C-h v which
direction, if any, to translate single quotes in.

Please regard this as a quick fix to ease problems that we've already
discussed extensively elsewhere.  Nevertheless, if curly quotes are
going to become permanent in Emacs, something of the like is going to be
needed on a permanent basis.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Translation of single quotes in doc strings is now optional.

[Paul Eggert]

Alan Mackenzie wrote:
> Please regard this as a quick fix to ease problems that we've already
> discussed extensively elsewhere.  Nevertheless, if curly quotes are
> going to become permanent in Emacs, something of the like is going to be
> needed on a permanent basis.

Although this quick fix adds complexity, perhaps it's worth it.  Glenn fixed 
some minor glitches introduced by the quick fix, and I just now patched most of 
the other problems I found with it.  I changed the values to be more mnemonic, 
so that one can now use (setq 'help-quote-translation ?`) to get the traditional 
Emacs quoting style.  The default behavior when the user has not customized the 
new variable is now to generate curved quotes when possible and to fall back on 
straight quotes when in environments that can't handle curved quotes, as this 
should yield better behavior on newer platforms without making things more 
difficult on old-fashioned ones.

I'd like to use the new variable to customize quotes used in diagnostics too. 
So perhaps we should rename it from help-quote-translation to just 
quote-translation.  But this can wait until we think through how diagnostic 
handling should be done.  A simple approach would be to extend 'format' via a ` 
flag, so that we can replace (format "Rename `%s' to `%s'" old new) with (format 
"Rename %`s to %`s" old new) to get customizable quotes, but this would entail 
changing several format calls in the source and I am trying to think of 
something less intrusive.

Re: Translation of single quotes in doc strings is now optional.

[Artur Malabarba]

>  A simple approach would be to extend 'format' via
> a ` flag, so that we can replace (format "Rename `%s' to `%s'" old new) with
> (format "Rename %`s to %`s" old new) to get customizable quotes, but this
> would entail changing several format calls in the source and I am trying to
> think of something less intrusive.
>

How about defining a new function, `format-and-quote-translate', which
converts all `' in the format-string to round quotes if desired?
We would still have to go through the source and edit many `format'
calls, but simply renaming the function is easier than editing the
format-strings.

Re: Translation of single quotes in doc strings is now optional.

[Paul Eggert]

Artur Malabarba wrote:
> How about defining a new function, `format-and-quote-translate', which
> converts all `' in the format-string to round quotes if desired?

Yes, that's the sort of thing I had in mind.  The idea is that 'message' will 
call the new function instead of plain 'format', and that other functions like 
'message' will be similar.  The new function will generate quotes in the style 
the user prefers (style setting established by the new custom variable, which 
probably needs renaming).  The name I came up with was 'format-message', since 
it'll be the format style that 'message' uses (and that's shorter and easier to 
remember than 'format-and-quote-translate'....)

This wouldn't suffice in general, as there are many instances that don't use 
'format' or anything like it.  However, it'd handle many (perhaps most) of the 
diagnostics that currently quote with grave accent.

Re: Translation of single quotes in doc strings is now optional.

[Alan Mackenzie]

Hello, Paul.

On Fri, Jun 19, 2015 at 01:13:55AM -0700, Paul Eggert wrote:
> Alan Mackenzie wrote:
> > Please regard this as a quick fix to ease problems that we've already
> > discussed extensively elsewhere.  Nevertheless, if curly quotes are
> > going to become permanent in Emacs, something of the like is going to be
> > needed on a permanent basis.

> Although this quick fix adds complexity, perhaps it's worth it.  Glenn fixed 
> some minor glitches introduced by the quick fix, ....

Thanks, Glenn.

> .... and I just now patched most of the other problems I found with it.

You've introduced problems yourself.  Why have you removed the "no
translation" option?  That was the whole main point of my patch.  Emacs
developers, in particular, will want to be able to see what's there,
rather than a "prettyfied" version of it.  The "no translation" option
must come back.

> I changed the values to be more mnemonic, so that one can now use
> (setq 'help-quote-translation ?`) to get the traditional Emacs quoting
> style.

Fine.  So on a terminal where grave and curly quote share a glyph, the
difference will be invisible.  On one where there is no pertinent glyph,
the curly character will look like a "?".  This is a bad change.
Options such as this should be ASCII.

> The default behavior when the user has not customized the new
> variable is now to generate curved quotes when possible and to fall
> back on straight quotes when in environments that can't handle curved
> quotes, ....

What about KISS?  Why not leave the default behaviour as "no
translation"?  Then people who definitely want it can choose it, those
who don't won't be bothered by it.

> .... as this should yield better behavior on newer platforms without
> making things more difficult on old-fashioned ones.

The "behavior" (actually, merely display) is not better, but we've
already been over this at some length in bug #20707.  And that's
assuming that we can reliably detect environments which don't properly
display curly quotes.

> I'd like to use the new variable to customize quotes used in diagnostics too. 
> So perhaps we should rename it from help-quote-translation to just 
> quote-translation.  But this can wait until we think through how diagnostic 
> handling should be done.

Correct me if I'm wrong, but this whole business of converting to curly
quotes hasn't yet had the go-ahead from the project maintainer.  How
about waiting until this is forthcoming, before making any more far
reaching and controversial changes in this area?  Stefan?

> A simple approach would be to extend 'format' via a ` flag, so that we
> can replace (format "Rename `%s' to `%s'" old new) with (format
> "Rename %`s to %`s" old new) to get customizable quotes, but this
> would entail changing several format calls in the source and I am
> trying to think of something less intrusive.

I won't have time over the next few days to do anything in Emacs.  If
the above problems still persist after this time, I'll attend to them
then.

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Translation of single quotes in doc strings is now optional.

[Paul Eggert]

Alan Mackenzie wrote:
> Emacs developers, in particular, will want to be able to see what's there,
> rather than a "prettyfied" version of it.

There have always been multiple ways that a doc string can generate quotes. 
It's true that recent changes have added more ways to do it, but these changes 
haven't introduced a new issue -- it's an issue Emacs already had.

If there is a real need to put raw doc strings in help buffers, we could add 
such a feature -- but any such feature should affect all docstring formatting, 
not just curved quotes, and it certainly shouldn't be the default.  And I don't 
see the need for such a feature anyway.  What's the use case?  Is it an Emacs 
developer who lacks access to the source code but still needs to debug its 
documentation?

> on a terminal where grave and curly quote share a glyph, the
> difference will be invisible.

I don't see that as a serious problem, as people will rarely change this 
setting, and if they do the context will make it clear.  In contrast, the symbol 
names were hard to remember and were not well-chosen for future expansion.  For 
example, the name ‘prefer-unicode’ implied that there would be only one Unicode 
choice, but we might in the future want to support quoting with curved double 
quotes, which would also be Unicode characters.

That being said, if you still prefer ASCII, how about using the Unicode names 
for the characters in question?  That is, ‘APOSTROPHE’, ‘GRAVE ACCENT’, ‘LEFT 
SINGLE QUOTATION MARK’.  That would be easier to remember than ‘prefer-utf8’ and 
the like.

> this whole business of converting to curly
> quotes hasn't yet had the go-ahead from the project maintainer.

You're mistaken.  About a month ago Stefan gave the go-ahead to start using 
curved quotes.

Re: Translation of single quotes in doc strings is now optional.

[Michael Albinus]

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

> I'd like to use the new variable to customize quotes used in
> diagnostics too. So perhaps we should rename it from
> help-quote-translation to just quote-translation.  But this can wait
> until we think through how diagnostic handling should be done.  A
> simple approach would be to extend 'format' via a ` flag, so that we
> can replace (format "Rename `%s' to `%s'" old new) with (format
> "Rename %`s to %`s" old new) to get customizable quotes, but this
> would entail changing several format calls in the source and I am
> trying to think of something less intrusive.

My usual rant: this is not backward compatible, and would bring
tramp*.el sources into trouble. And yes, Tramp sends this kind of
messages. 

Why not the other way around: let `format' translate the quotes, unless
they are written as (format "Rename \\=`%s' to \\=`%s'" old new)

Best regards, Michael.

Re: Translation of single quotes in doc strings is now optional.

[Paul Eggert]

Michael Albinus wrote:
> Why not the other way around: let `format' translate the quotes, unless
> they are written as (format "Rename \\=`%s' to \\=`%s'" old new)

Unfortunately 'format' is often used to format regular expressions that contain 
grave accents.  For example:

(format "\\`%s\\'" (car e))

We could change all the Emacs code that does this, but I expect user code does 
it too, and so it'd probably be a mistake to alter 'format' in the way you're 
suggesting.

Re: Translation of single quotes in doc strings is now optional.

[Paul Eggert]

Michael Albinus wrote:
> Paul Eggert <eggert@cs.ucla.edu> writes:
>
>> A simple approach would be to extend 'format' via a ` flag, so that we
>> can replace (format "Rename `%s' to `%s'" old new) with (format
>> "Rename %`s to %`s" old new) to get customizable quotes, but this
>> would entail changing several format calls in the source and I am
>> trying to think of something less intrusive.
>
> My usual rant: this is not backward compatible, and would bring
> tramp*.el sources into trouble. And yes, Tramp sends this kind of
> messages.

By "backward compatible", I assume you mean that code using the new ` flag would 
not be portable to older Emacs.  There shouldn't be any compatibility problem in 
the usual sense, as the change would be a pure extension to 'format', i.e, it 
wouldn't affect Tramp's behavior if we left Tramp alone.

Re: Translation of single quotes in doc strings is now optional.

[Michael Albinus]

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

> By "backward compatible", I assume you mean that code using the new `
> flag would not be portable to older Emacs.  There shouldn't be any
> compatibility problem in the usual sense, as the change would be a
> pure extension to 'format', i.e, it wouldn't affect Tramp's behavior
> if we left Tramp alone.

For sure. However, Tramp uses the same wording as the original functions
it provides handlers for. As a consequence, a user would see the message
"Rename ‘old’ to ‘new’" for local files, and "Rename `old' to `new'" for
remote files. This looks inconsistent.

Best regards, Michael.

Re: Translation of single quotes in doc strings is now optional.

[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 default behavior when the user has not customized the 
  > new variable is now to generate curved quotes when possible and to fall back on 
  > straight quotes when in environments that can't handle curved quotes, as this 
  > should yield better behavior on newer platforms without making things more 
  > difficult on old-fashioned ones.

That seems ideal.

-- 
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: Translation of single quotes in doc strings is now optional.

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

  > I've just committed an enhancement to C-h f, C-h v, such that ` and '
  > are no longer translated mandatorily into their curly equivalents for
  > display.  There is a new customisable variable, `help-quote-translation'
  > (in the Help group) which takes one of the values nil (default),
  > 'traditional, and 'prefer-unicode, which directs C-h f and C-h v which
  > direction, if any, to translate single quotes in.

That's a good feature.  Note that we deprecate the practice of writing
a singlequote before a symbol to indicate it is a symbol.

Is it possible to determine automatically whether the terminal
can display curly quotes, and set the variable accordingly?
-- 
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: Translation of single quotes in doc strings is now optional.

[Paul Eggert]

Richard Stallman wrote:
> Is it possible to determine automatically whether the terminal
> can display curly quotes, and set the variable accordingly?

That's already done, in the master version.  set-locale-environment uses 
char-displayable-p and sets a variable that's later used by the variable.  This 
is all recently-added code; it been tested in some environments but I imagine it 
may still need tweaking in others.