Discussion:
[Emacs-diffs] master b533552 2/5: Documentation fixes re quotes
(too old to reply)
Dmitry Gutov
2015-08-31 06:26:53 UTC
Permalink
Prefer curved quotes in examples if users will typically see
curved quotes when the examples run.
Who said the source code examples should looks the same as a output? It
source code, people won't expect every program to be a quine.

I'm obviously against this, because these encourage users to copy and
paste the snippets containing curly quotes in their programs.
Dmitry Gutov
2015-08-31 06:29:08 UTC
Permalink
- (insert "Don't output anything.\n"))
+ (insert "Don’t output anything.\n"))
I thought you were going to consider translating unpaired quotes, too?
Paul Eggert
2015-08-31 06:38:06 UTC
Permalink
Post by Dmitry Gutov
- (insert "Don't output anything.\n"))
+ (insert "Don’t output anything.\n"))
I thought you were going to consider translating unpaired quotes, too?
Yes, they're translated. I just forgot to translate that one. Fixed in master
commit 6514fe88904e658c527deae5be9a3f6ac539653f.
Stefan Monnier
2015-08-31 17:34:06 UTC
Permalink
Post by Dmitry Gutov
- (insert "Don't output anything.\n"))
+ (insert "Don’t output anything.\n"))
I thought you were going to consider translating unpaired quotes, too?
I'm not sure I'm following. Can someone explain to me what's the issue
at play here?

And to give some background: I'm a bit worried about having too much
magic going on, so in general automatic conversion should be avoided
unless it's *really* often useful and *really* rarely problematic.


Stefan
Dmitry Gutov
2015-08-31 18:40:17 UTC
Permalink
Post by Stefan Monnier
I'm not sure I'm following. Can someone explain to me what's the issue
at play here?
IIUC your question, the issue is whether (substitute-command-keys "'")
returns "'" or "’". It does the latter now.

I'm fine with that, e.g. because it simplifies our ability to keep
straight quotes (or some other markup) in the source code and show the
curly quotes to the user.

But it seems to be too much to expect Paul to toe that line. The frog is
pretty much boiled by now.
Paul Eggert
2015-08-31 18:48:00 UTC
Permalink
Post by Stefan Monnier
+ (insert "Don’t output anything.\n"))
I thought you were going to consider translating unpaired quotes, too?
I'm not sure I'm following. Can someone explain to me what's the issue
at play here?
Currently, all apostrophes and right single quotation marks are translated in
docstrings and diagnostics, even isolated ones such as the example above.
Dmitry was wondering whether this is the case: it's something he suggested
earlier and I implemented it that way, but I guess he wasn't sure whether I'd
done it.
Post by Stefan Monnier
I'm a bit worried about having too much
magic going on, so in general automatic conversion should be avoided
unless it's *really* often useful and *really* rarely problematic.
One alternative is to go with a system that normally has no translation, where
Emacs source-code docstrings and diagnostics use curved quotes that merely stand
for themselves, and where all curved quotes are displayed/searched-for/yanked as
ASCII approximations for users who prefer the traditional style. This would
remove the need for format-message and/or substitute-command-keys doing any
quote translation. A downside is that source code docstrings and diagnostics
would need to be converted to use curved quotes.
David Kastrup
2015-09-01 07:35:59 UTC
Permalink
Post by Paul Eggert
One alternative is to go with a system that normally has no
translation, where Emacs source-code docstrings and diagnostics use
curved quotes that merely stand for themselves, and where all curved
quotes are displayed/searched-for/yanked as ASCII approximations for
users who prefer the traditional style. This would remove the need
for format-message and/or substitute-command-keys doing any quote
translation. A downside is that source code docstrings and
diagnostics would need to be converted to use curved quotes.
Well, it would save us from horribly wrong DOC strings like

quote is a special form in ‘C source code’.

(quote ARG)

Return the argument, without evaluating it. ‘(quote x)’ yields ‘x’.
Warning: ‘quote’ does not construct its return value, but just returns
the value that was pre-constructed by the Lisp reader (see info node
‘(elisp)Printed Representation’).
This means that ’(a . b) is not identical to (cons ’a ’b): the former
does not cons. Quoting should be reserved for constants that will
never be modified by side-effects, unless you like self-modifying code.
See the common pitfall in info node ‘(elisp)Rearrangement’ for an example
of unexpected results when a quoted object is modified.

[back]

Sometimes a quote is just a quote.
--
David Kastrup
Stefan Monnier
2015-08-31 17:40:52 UTC
Permalink
Post by Dmitry Gutov
- (insert "Don't output anything.\n"))
+ (insert "Don’t output anything.\n"))
I thought you were going to consider translating unpaired quotes, too?
One more thing: while I think many people find "`foo'" is visually ugly,
the number of people who find "don't" ugly is probably much smaller.

So I don't see a strong need to go through extra efforts to convert
"don't" to "don’t". I'm not even sure if "don’t" is typographically
better than "don't" (after all, last I checked the little thingy is
supposed to be an "apostrophe", not a "right single quotation mark").


Stefan
Paul Eggert
2015-08-31 18:03:08 UTC
Permalink
Post by Stefan Monnier
I'm not even sure if "don’t" is typographically
better than "don't" (after all, last I checked the little thingy is
supposed to be an "apostrophe", not a "right single quotation mark").
Typographically it's not an issue: in non-typewriter English, U+2019 RIGHT
SINGLE QUOTATION MARK is supposed to be use for elision (“don’t”), for closing a
single quotation (“He said ‘no’.”) and for grammar (“Those are my sisters’
books.”). It's the same character for all three. See, for example,
<http://www.languagegeek.com/typography/apostrophes.html>.
Post by Stefan Monnier
I don't see a strong need to go through extra efforts to convert
"don't" to "don’t".
Me neither, but most of the "don't"s are converted automatically anyway, and I
figured it's not hard to convert the few odd stragglers if only to avoid
complaints from typography obsessives down the road....
Stephen J. Turnbull
2015-09-01 01:55:43 UTC
Permalink
Post by Paul Eggert
Me neither, but most of the "don't"s are converted automatically
anyway, and I figured it's not hard to convert the few odd
stragglers if only to avoid complaints from typography obsessives
down the road....
At the cost of turning emacs-devel into a torrent of complaints from
typography obsessives now....
Stefan Monnier
2015-09-01 03:40:29 UTC
Permalink
Post by Paul Eggert
Post by Stefan Monnier
I'm not even sure if "don’t" is typographically
better than "don't" (after all, last I checked the little thingy is
supposed to be an "apostrophe", not a "right single quotation mark").
Typographically it's not an issue: in non-typewriter English, U+2019 RIGHT
SINGLE QUOTATION MARK is supposed to be use for elision (“don’t”), for
closing a single quotation (“He said ‘no’.”) and for grammar (“Those are my
sisters’ books.”). It's the same character for all three. See, for
example, <http://www.languagegeek.com/typography/apostrophes.html>.
I think in the context of Emacs, if we have to choose between ' and ’
and there's not a strong reason to prefer the non-ASCII char, we
should stick with the ASCII char.

The only thing we're trying to fix here is the ugly `...' quoting.
I don't see any need to change anything else at this stage.


Stefan
Paul Eggert
2015-09-01 06:29:50 UTC
Permalink
Post by Stefan Monnier
if we have to choose between ' and ’
and there's not a strong reason to prefer the non-ASCII char, we
should stick with the ASCII char.
The reason is that it's simpler for ‘message’ etc. to transliterate every
apostrophe than to employ more-complicated heuristics that are typically wrong
anyway, typographically speaking. But I take your point that I should stop
worrying about messages that merely say “Don't”.
Oleh Krehel
2015-09-01 10:45:06 UTC
Permalink
Post by Stefan Monnier
Post by Paul Eggert
Post by Stefan Monnier
I'm not even sure if "don’t" is typographically
better than "don't" (after all, last I checked the little thingy is
supposed to be an "apostrophe", not a "right single quotation mark").
Typographically it's not an issue: in non-typewriter English, U+2019 RIGHT
SINGLE QUOTATION MARK is supposed to be use for elision (“don’t”), for
closing a single quotation (“He said ‘no’.”) and for grammar (“Those are my
sisters’ books.”). It's the same character for all three. See, for
example, <http://www.languagegeek.com/typography/apostrophes.html>.
I think in the context of Emacs, if we have to choose between ' and ’
and there's not a strong reason to prefer the non-ASCII char, we
should stick with the ASCII char.
The only thing we're trying to fix here is the ugly `...' quoting.
I don't see any need to change anything else at this stage.
I'd like to present a data point: there are 32725 occurrences of "don't"
in the Emacs git repository, and only 10 occurrences of "don’t".

And to restate my opinion on the matter, since I haven't participated in
this discussion for a few months: Elisp code should be treated as
markup. Markup should be easy to view and enter: and since Emacs' main
language is English, the markup should be easy to enter in the most
common English keyboard layout and be easy to read in the most common
English locale.

If it were up to me, I'd revert everything until there wasn't a single
curly in the code part. Having markup that translates to curlies is
absolutely fine with me. But even that should be configurable, and I
would configure my Emacs to go without the option because I hate to see
curlies.

Also one of the most popular markup formats - Markdown
(http://daringfireball.net/projects/markdown/syntax) uses plain ASCII
for markup. One of the reasons for the change in Emacs was something
about texinfo having curlies. Well, Markdown is a competing format that
is way more popular than texinfo. And while a Markdown renderer can
translate "don't" into "don’t", and I'm pretty sure it does so by
default, the markup itself still remains ASCII and is easy to enter,
modify and view.

It's just a matter of convenience, which is one of Emacs' strengths:

- Entering "'" with a single key on my pinky is convenient.
- Entering "’" with "C-x 8" isn't.
- Grepping for "don't.*foo" is convenient.
- Grepping for "\(don’t\)\|\(don't\).*foo" isn't convenient.

Oleh
Andreas Schwab
2015-09-01 10:53:08 UTC
Permalink
Post by Oleh Krehel
- Grepping for "\(don’t\)\|\(don't\).*foo" isn't convenient.
It's also wrong. "don['’]t.*foo"

Andreas.
--
Andreas Schwab, SUSE Labs, ***@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE 1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."
David Kastrup
2015-09-01 11:22:19 UTC
Permalink
Post by Oleh Krehel
And to restate my opinion on the matter, since I haven't participated in
this discussion for a few months: Elisp code should be treated as
markup. Markup should be easy to view and enter: and since Emacs' main
language is English, the markup should be easy to enter in the most
common English keyboard layout and be easy to read in the most common
English locale.
DOC strings are only marginally cooked and contain code examples. Code
examples obviously contains ' and ` in their Lisp meaning. Code
examples are copied&pasted into actual code.

So if ` and ' are supposed to be "markup" for ‘ and ’, we obviously need
a markup variant for either code passages or unmolested ` and '.

Has anything like that been proposed? I repeat the documentation help
from the `quote' macro:

quote is a special form in ‘C source code’.

(quote ARG)

Return the argument, without evaluating it. ‘(quote x)’ yields ‘x’.
Warning: ‘quote’ does not construct its return value, but just returns
the value that was pre-constructed by the Lisp reader (see info node
‘(elisp)Printed Representation’).
This means that ’(a . b) is not identical to (cons ’a ’b): the former
does not cons. Quoting should be reserved for constants that will
never be modified by side-effects, unless you like self-modifying code.
See the common pitfall in info node ‘(elisp)Rearrangement’ for an example
of unexpected results when a quoted object is modified.

It contains both quote marks as well as Lisp quote characters.
Executing the given examples yields "void variable ’"&"Trailing garbage
following expression" and "void variable ’a" respectively.

Info does not have this problem because Texinfo markup marks code
passages separately, and for those, ` and ' are not substituted.

So this just can't work in DOC strings until we have decided on separate
markup for either ` and ' or code in general.
--
David Kastrup
Oleh Krehel
2015-09-01 11:40:10 UTC
Permalink
Post by David Kastrup
Has anything like that been proposed? I repeat the documentation help
quote is a special form in ‘C source code’.
(quote ARG)
Return the argument, without evaluating it. ‘(quote x)’ yields ‘x’.
Warning: ‘quote’ does not construct its return value, but just returns
the value that was pre-constructed by the Lisp reader (see info node
‘(elisp)Printed Representation’).
This means that ’(a . b) is not identical to (cons ’a ’b): the former
does not cons. Quoting should be reserved for constants that will
never be modified by side-effects, unless you like self-modifying code.
See the common pitfall in info node ‘(elisp)Rearrangement’ for an example
of unexpected results when a quoted object is modified.
It contains both quote marks as well as Lisp quote characters.
Executing the given examples yields "void variable ’"&"Trailing garbage
following expression" and "void variable ’a" respectively.
Info does not have this problem because Texinfo markup marks code
passages separately, and for those, ` and ' are not substituted.
So this just can't work in DOC strings until we have decided on separate
markup for either ` and ' or code in general.
This could be solved in a variety of ways while keeping to ASCII. For
instance, either "''" or "\'" could translate into "'" unconditionally.

I would prefer the way Markdown does it: `(cons 'a 'b)` translates into
<code>(cons 'a 'b)</code>. I've been using a similar style for org-mode,
only with different escape chars:

- =(cons 'a 'b)= to denote code
- ~C-a C-k~ to denote keyboard sequences
Dmitry Gutov
2015-09-01 11:42:03 UTC
Permalink
Post by David Kastrup
So if ` and ' are supposed to be "markup" for ‘ and ’, we obviously need
a markup variant for either code passages or unmolested ` and '.
Has anything like that been proposed?
We have \\= escaping syntax, see `substitute-command-keys'.
David Kastrup
2015-09-01 12:06:34 UTC
Permalink
Post by Dmitry Gutov
Post by David Kastrup
So if ` and ' are supposed to be "markup" for ‘ and ’, we obviously need
a markup variant for either code passages or unmolested ` and '.
Has anything like that been proposed?
We have \\= escaping syntax, see `substitute-command-keys'.
Spells more or less death for cut&paste from some help buffer into the
_source_ of a DOC string, doesn't it? Sure, backslashes already have
that effect, but at least this is due to string syntax rather than some
obscure markup processor.
--
David Kastrup
Dmitry Gutov
2015-09-01 14:20:31 UTC
Permalink
Post by David Kastrup
Post by Dmitry Gutov
We have \\= escaping syntax, see `substitute-command-keys'.
Spells more or less death for cut&paste from some help buffer into the
_source_ of a DOC string, doesn't it? Sure, backslashes already have
that effect, but at least this is due to string syntax rather than some
obscure markup processor.
Like you said, any escaping syntax spells death for cut&paste.

Due to how Elisp reader works, we simply can't use backslashes in the
docstrings. Or we'll need a lot of them.
Oleh Krehel
2015-09-03 10:16:49 UTC
Permalink
Post by Dmitry Gutov
Post by David Kastrup
Post by Dmitry Gutov
We have \\= escaping syntax, see `substitute-command-keys'.
Spells more or less death for cut&paste from some help buffer into the
_source_ of a DOC string, doesn't it? Sure, backslashes already have
that effect, but at least this is due to string syntax rather than some
obscure markup processor.
Like you said, any escaping syntax spells death for cut&paste.
Cut and paste can still work: just add a `quote-last-yank' command and/or
`quote-region' command. I've been using similar commands for posting
copy-pasted code to Stack websites. Here's a snippet I use for quoting
pasted code in Markdown:

(defun ora-markdown-stack-block (beg end)
(interactive "r")
(let ((str (buffer-substring-no-properties beg end)))
(delete-region beg end)
(insert
"<!-- language: lang-cl -->\n\n "
(mapconcat
#'identity
(split-string str "\n" t)
"\n "))))

An issue that I have with \\= escaping syntax is that it's ugly. One
reason for success of Markdown (also Org-mode) is that it looks good
enough even in source form, i.e. not exported or rendered. Therefore, I
propose we move from this:

(defcustom auto-insert 'not-modified
...
This variable is used when the function `auto-insert' is called, e.g.
when you do (add-hook \\='find-file-hook \\='auto-insert).

to this:

This variable is used when the function `auto-insert' is called, e.g.
when you do ``(add-hook 'find-file-hook 'auto-insert)''.

Note how ``(add-hook 'find-file-hook 'auto-insert)'' looks good enough
even in plain text form, with no extra highlighting. Much better than
(add-hook \\='find-file-hook \\='auto-insert). And it's easy to copy
paste and quote with a simple command that just adds 4 chars around a
region.

Also, it would be very easy to modify font-lock to add extra
highlighting for ``...'' blocks, since they're so easy to parse.

In the unlikely case when someone wants a code block with two
consecutive apostrophes, the old \\=' approach can be used. The quoting
function could even do this automatically, i.e. quote any apostrophes in
the region appropriately.

For code blocks, we could use an empty line followed by 4 spaces indent.

I think there's value in having asymmetric delimiters, since that eases
the job of font-lock by a lot. The current `markdown-mode' breaks
highlighting very often because of symmetric delimiters.

Oleh
Dmitry Gutov
2015-09-03 11:22:15 UTC
Permalink
Post by Oleh Krehel
Post by Dmitry Gutov
Like you said, any escaping syntax spells death for cut&paste.
Cut and paste can still work: just add a `quote-last-yank' command and/or
`quote-region' command.
But it's not always that you'll want to quote the pasted string, is it?
Post by Oleh Krehel
An issue that I have with \\= escaping syntax is that it's ugly.
It looks a bit odd, but we're unlikely to get rid of it, since it's been
supported for ages.
Post by Oleh Krehel
This variable is used when the function `auto-insert' is called, e.g.
when you do ``(add-hook 'find-file-hook 'auto-insert)''.
Looks fine to me.
Post by Oleh Krehel
Note how ``(add-hook 'find-file-hook 'auto-insert)'' looks good enough
even in plain text form, with no extra highlighting. Much better than
(add-hook \\='find-file-hook \\='auto-insert).
I think both options looks readable enough, but let's have two syntaxes
if people find it that easier.
Post by Oleh Krehel
For code blocks, we could use an empty line followed by 4 spaces indent.
Yup. Although we might catch some false positives that way.
Post by Oleh Krehel
I think there's value in having asymmetric delimiters, since that eases
the job of font-lock by a lot.
Either way, it would be weird to quote symbol references with ` ', but
use `` `` for code expressions.
Stefan Monnier
2015-09-03 14:50:49 UTC
Permalink
Post by Dmitry Gutov
Post by Oleh Krehel
Cut and paste can still work: just add a `quote-last-yank' command and/or
`quote-region' command.
But it's not always that you'll want to quote the pasted string, is it?
That's why he's recommending a command. You'd first yank and then (if
you needed) run the quote command, which quotes what you just yanked.
That's would be kind of like a "postfix argument".
Post by Dmitry Gutov
Post by Oleh Krehel
An issue that I have with \\= escaping syntax is that it's ugly.
It looks a bit odd, but we're unlikely to get rid of it, since it's been
supported for ages.
It's been supported for ages, yes, but until recently it was *very*
rarely needed. IOW the need to write

(add-hook \\='find-file-hook \\='auto-insert)

is brand new in Emacs-25, and it sucks.

I don't intend to get rid of the \= escaping syntax (tho I do find it
hideous), but I don't want to have to use it, except for those very
limited use cases that are as old as the \= syntax itself.
Post by Dmitry Gutov
Post by Oleh Krehel
This variable is used when the function `auto-insert' is called, e.g.
when you do ``(add-hook 'find-file-hook 'auto-insert)''.
Looks fine to me.
Yes, I could live with it (and I could accept the use of "'\\='" for
those very rare cases where we need to have "''" inside the "...").

BTW, re-using existing quoting syntaxes from other systems (e.g.
markdown/org) is a good idea, when applicable. E.g. it would be
desirable to be able to take a docstring and easily convert it to
a valid org/markdown document. Of course, that needs to be balanced
with the needs specific to docstrings (among other things, to
accommodate pre-existing practice).
Post by Dmitry Gutov
Either way, it would be weird to quote symbol references with ` ', but use
`` `` for code expressions.
I don't see why.


Stefan
Dmitry Gutov
2015-09-03 15:04:42 UTC
Permalink
Post by Stefan Monnier
That's why he's recommending a command. You'd first yank and then (if
you needed) run the quote command, which quotes what you just yanked.
That's would be kind of like a "postfix argument".
Ok.
Post by Stefan Monnier
It's been supported for ages, yes, but until recently it was *very*
rarely needed. IOW the need to write
(add-hook \\='find-file-hook \\='auto-insert)
is brand new in Emacs-25, and it sucks.
Note that you also wouldn't need it here if quote-matching code uses
sorward-sexp.
Post by Stefan Monnier
BTW, re-using existing quoting syntaxes from other systems (e.g.
markdown/org) is a good idea, when applicable. E.g. it would be
desirable to be able to take a docstring and easily convert it to
a valid org/markdown document.
True.
Post by Stefan Monnier
Post by Dmitry Gutov
Either way, it would be weird to quote symbol references with ` ', but use
`` `` for code expressions.
I don't see why.
For consistency, I'd say. Otherwise we probably risk more typos.
Admittedly, I'm just guessing, but `` '' also looks a bit nicer to me.
Paul Eggert
2015-09-01 13:31:06 UTC
Permalink
Post by David Kastrup
I repeat the documentation help
That was a typo, which I fixed in master commit
a3c31adea4970b8a7fc7f495e6a6a6d4a93e69ce by escaping the apostrophe. Thanks for
reporting it.
David Kastrup
2015-09-01 14:15:28 UTC
Permalink
Post by Paul Eggert
Post by David Kastrup
I repeat the documentation help
That was a typo, which I fixed in master commit
a3c31adea4970b8a7fc7f495e6a6a6d4a93e69ce by escaping the apostrophe.
Thanks for reporting it.
Not as much a typo as an oversight. That commit fixes 48 such
oversights and I think that everybody should read the accompanying diff
and ask himself whether he likes the results.

The respective necessary changes are a nuisance to read and a nuisance
to write.

I think this would be a better sell if the DOC strings got some general
markup for code/example that would then be output in an (unmolested)
typewriter font, with the source code inside of that markup again being
unmolested. It would also be nicer in case people wanted to convert DOC
strings into Texinfo or HTML or other output formats where offsetting
code is a good possibility.

I very much should think that people would be more amenable to offset
code passages in some manner rather than mangle every quote character.

It's also a better sell to teach people to properly offset code passages
in mailing lists/discussion groups "for best results" rather than teach
the quote mangling.

That means coming up with a nice form of entering code, both inline and
as block, and then walk through all the doc strings (naturally, this
concerns even material not containing any quote characters).

It's probably a larger task than what has been done so far. But I think
that the end result would be much more satisfactory and offer
_independent_ benefits. And of course it would still allow selective
turning off all quote treatment reasonably easily.
--
David Kastrup
Stefan Monnier
2015-09-01 15:39:53 UTC
Permalink
Post by Oleh Krehel
And to restate my opinion on the matter, since I haven't participated in
this discussion for a few months: Elisp code should be treated as
markup. Markup should be easy to view and enter: and since Emacs' main
language is English, the markup should be easy to enter in the most
common English keyboard layout and be easy to read in the most common
English locale.
I generally agree. And to restate what I said earlier in more details,
what I'd like to see fixed is:
- `...' quoting is ugly. This should be fixed in "end user display"
mostly, tho I don't mind if it's also fixed in the source code.
- The `...' markup (and it is markup) is ambiguous.

So I thought we were going to replace the `...' markup with ‘...’ markup
(which fixes both points at the same time if we assume that we keep
sticking to ASCII quotes for the rest, tho at the cost of using
non-ASCII markup).

But if we start using curly quotes everywhere, then we're back with the
ambiguity, so that's not a good solution.

So maybe a better option is to refine the `...' markup to get rid of
the ambiguity. E.g.:
- `...' is only considered valid markup if ... doesn't contain any
whitespace (or some such restriction: it should be a simple rule that
still accepts most existing uses, especially those where we want to
place a hyperlink).
- All other occurrences of ` and ' are treated a standalone ASCII chars
rather than as part of some markup.
So `C-x C-f' is not valid markup any more (and won't be prettified).
- Introduce some other markup for the more general case. Maybe this
should be specific to docstrings, so it can be "somewhat verbose" and
fairly rich/extensible.

At that point we could imagine rendering docstrings in more refined way
(e.g. using faces rather than curly quotes).


Stefan
Alan Mackenzie
2015-09-01 19:00:14 UTC
Permalink
Hello, Stefan.
Post by Stefan Monnier
Post by Oleh Krehel
And to restate my opinion on the matter, since I haven't participated in
this discussion for a few months: Elisp code should be treated as
markup. Markup should be easy to view and enter: and since Emacs' main
language is English, the markup should be easy to enter in the most
common English keyboard layout and be easy to read in the most common
English locale.
I generally agree. And to restate what I said earlier in more details,
- `...' quoting is ugly. This should be fixed in "end user display"
mostly, tho I don't mind if it's also fixed in the source code.
Just to emphasize that `...' quoting is not at all ugly on my terminal -
in fact, it's rather elegant. However, using curly quotes is
problematic. I run on a Linux virtual terminal.

So, PLEASE can we have adequate configurability, so that the user can
decide for herself what's ugly, and whether it needs "fixing".
Post by Stefan Monnier
- The `...' markup (and it is markup) is ambiguous.
So I thought we were going to replace the `...' markup with ‘...’ markup
(which fixes both points at the same time if we assume that we keep
sticking to ASCII quotes for the rest, tho at the cost of using
non-ASCII markup).
Yet again, can we please have any such transformations user
configurable?

[ .... ]
Post by Stefan Monnier
Stefan
--
Alan Mackenzie (Nuremberg, Germany).
Stefan Monnier
2015-09-02 04:07:03 UTC
Permalink
Post by Alan Mackenzie
Just to emphasize that `...' quoting is not at all ugly on my terminal -
in fact, it's rather elegant.
Indeed, the font I see in my Linux console renders them OK
(pre-XFree86-4 style), but I think you're sadly in a minority.
Post by Alan Mackenzie
However, using curly quotes is problematic. I run on a Linux
virtual terminal.
Curly quotes render just fine in my Linux console. So it looks like
you're in an even smaller minority.
Post by Alan Mackenzie
So, PLEASE can we have adequate configurability, so that the user can
decide for herself what's ugly, and whether it needs "fixing".
My request here is to figure out what *kind* of configurability is best.
Not whether configurability is desired. But you're not very forthcoming
with information about the concrete problems you see with curly quotes,
so we're likely not going to be able to provide the best kind of
customizability for you.


Stefan
David Kastrup
2015-09-02 05:28:11 UTC
Permalink
Post by Stefan Monnier
Post by Alan Mackenzie
Just to emphasize that `...' quoting is not at all ugly on my terminal -
in fact, it's rather elegant.
Indeed, the font I see in my Linux console renders them OK
(pre-XFree86-4 style), but I think you're sadly in a minority.
Post by Alan Mackenzie
However, using curly quotes is problematic. I run on a Linux
virtual terminal.
Curly quotes render just fine in my Linux console. So it looks like
you're in an even smaller minority.
When assuming that the world only consists of Alan and Stefan, the word
"minority" does not make a lot of sense. Assuming that "$x works for
Stefan's setup and $y doesn't" means that "$x doesn't work for $u but $y
does." is impossible for all values of u is a bit self-centric.
--
David Kastrup
Alan Mackenzie
2015-09-02 10:02:52 UTC
Permalink
Hello, Stefan.
Post by Stefan Monnier
Post by Alan Mackenzie
Just to emphasize that `...' quoting is not at all ugly on my terminal -
in fact, it's rather elegant.
Indeed, the font I see in my Linux console renders them OK
(pre-XFree86-4 style), but I think you're sadly in a minority.
There's nothing sad about being in a minority. Anybody who runs Emacs
with her own .emacs is in a minority of one. Anybody who runs Emacs on
a platform that isn't GNU/Linux or Microsoft Windows or an Apple Mac is
also in a minority. For that matter, anybody running Emacs at all is in
a minority.
Post by Stefan Monnier
Post by Alan Mackenzie
However, using curly quotes is problematic. I run on a Linux
virtual terminal.
Curly quotes render just fine in my Linux console. So it looks like
you're in an even smaller minority.
Using my standard font, lat1-16, the curly quotes use the same glyphs as
` and ', hence are visibly indistinguishable from them. I tried
creating my own glyphs for the curlies, and put them into a font,
discarding two French-language glyphs to make room. They're ugly, but
more importantly, my eye can't reliably distinguish a standard quote
glyph from one of my new curly ones unless there's already a known quote
on the screen to compare it with.

But the ordinary user of a console is not going to have the time or
inclination to go mucking around with fonts.
Post by Stefan Monnier
Post by Alan Mackenzie
So, PLEASE can we have adequate configurability, so that the user can
decide for herself what's ugly, and whether it needs "fixing".
My request here is to figure out what *kind* of configurability is best.
Not whether configurability is desired. But you're not very forthcoming
with information about the concrete problems you see with curly quotes,
so we're likely not going to be able to provide the best kind of
customizability for you.
All of what I write above I've written before. In addition, the
necessity to type a C-x 8 combination to type a curly quote is a serious
impediment. (For me, remapping ` and ' to things which aren't
self-insert-command (or an electric command) is so inelegant as not to
come into consideration).

The sort of customisability I'm asking for is that in which the user
decides whether ASCII or curly quoting characters are used in *Help*,
messages, etc.
Post by Stefan Monnier
Stefan
--
Alan Mackenzie (Nuremberg, Germany).
Dmitry Gutov
2015-09-02 11:22:43 UTC
Permalink
Hi Alan,
Post by Alan Mackenzie
All of what I write above I've written before. In addition, the
necessity to type a C-x 8 combination to type a curly quote is a serious
impediment. (For me, remapping ` and ' to things which aren't
self-insert-command (or an electric command) is so inelegant as not to
come into consideration).
Is that a real problem?

As long as curly quotes are relegated to displayed messages and Help
buffers, you'll never need to type them as input for external tools.

And as for isearch, in the rare cases where looking for a beginning of a
symbol reference is important, you could input \_< or \_> instead.

That may be a bit worse than just typing `, but if we do highlighting
with faces (which I think is a good idea to transition to), searching
for ` won't work either.
Richard Stallman
2015-09-02 15:41:46 UTC
Permalink
[[[ 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. ]]]
Post by Dmitry Gutov
As long as curly quotes are relegated to displayed messages and Help
buffers, you'll never need to type them as input for external tools.
And as for isearch, in the rare cases where looking for a beginning of a
symbol reference is important, you could input \_< or \_> instead.
I think you're right -- but that's not how it seems things are.
We were informed today that there are over
900 curly quotes in the Emacs sources now.
Why are they in the sources?
--
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.
Dmitry Gutov
2015-09-02 15:53:58 UTC
Permalink
Post by Richard Stallman
I think you're right -- but that's not how it seems things are.
We were informed today that there are over
900 curly quotes in the Emacs sources now.
Why are they in the sources?
Because Paul put them there, even though objections were raised.
Paul Eggert
2015-09-02 16:38:30 UTC
Permalink
Post by Richard Stallman
Why are they in the sources?
I discussed this in my email to you (cc: emacs-***@gnu.org) dated yesterday
with subject line "Re: [Emacs-diffs] master b533552 2/5: Documentation fixes re
quotes". It's archived here:

http://lists.gnu.org/archive/html/emacs-devel/2015-09/msg00072.html
Richard Stallman
2015-09-03 15:37:11 UTC
Permalink
[[[ 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. ]]]
Post by Paul Eggert
Post by Richard Stallman
Why are they in the sources?
with subject line "Re: [Emacs-diffs] master b533552 2/5: Documentation fixes re
There were quite a few messages with precisely that subject,
but I eventually found yours.

Are you saying that curly quotes are current present only in those
.texi files?
--
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.
Paul Eggert
2015-09-03 17:26:32 UTC
Permalink
Post by Richard Stallman
Are you saying that curly quotes are current present only in those
.texi files?
I do not know which .texi files you are referring to, but no, I am not saying
that. Curved single quotes are present in .texi files, in .el files, .c files,
an .h file, ChangeLog files, etc/NEWS, etc/PROBLEMS, a tutorial file, and an
HTML file. You can list source files containing curved quotes by running the
following shell command:

grep -l '[‘’]' $(git ls-files | sort)
Paul Eggert
2015-09-02 16:32:42 UTC
Permalink
Post by Alan Mackenzie
Using my standard font, lat1-16, the curly quotes use the same glyphs as
` and ', hence are visibly indistinguishable from them.
That's no longer true as of yesterday's master commit
1a3518e7c361a9ceaa017c1334a83d14e0651a4e. On a terminal that cannot display
curved quotes, Emacs master now uses different glyphs for the quotes’ ASCII
replacements, because the replacements are shadowed. The shadowed glyphs are
easily distinguishable on my Linux console. Users shouldn’t need to configure
Emacs specially, or their Linux console specially, to get this behavior. So
this objection no longer applies.
Alan Mackenzie
2015-09-02 17:23:45 UTC
Permalink
Hello, Paul.
Post by Paul Eggert
Post by Alan Mackenzie
Using my standard font, lat1-16, the curly quotes use the same glyphs as
` and ', hence are visibly indistinguishable from them.
That's no longer true as of yesterday's master commit
1a3518e7c361a9ceaa017c1334a83d14e0651a4e.
I'm afraid it is still true. After doing a C-h f c-mode, apparent
quotes were in the buffer. Checking them with C-u C-x =, they were
indeed curly quotes, but were displayed the same as ASCII quotes.
Post by Paul Eggert
On a terminal that cannot display curved quotes, ...
Currently, my terminal is not such a one. It _can_ display curly
quotes, but only identically to ASCII quotes. `char-displayable-p'
returns 'unicode for them.

The issue is not so much whether a terminal can display curly quotes,
rather it's whether a user wants them to be used or not.
Post by Paul Eggert
.... Emacs master now uses different glyphs for the quotes’ ASCII
replacements, because the replacements are shadowed. The shadowed
glyphs are easily distinguishable on my Linux console. Users
shouldn’t need to configure Emacs specially, or their Linux console
specially, to get this behavior. So this objection no longer applies.
--
Alan Mackenzie (Nuremberg, Germany).
David Kastrup
2015-09-02 17:43:19 UTC
Permalink
Post by Alan Mackenzie
Hello, Paul.
Post by Paul Eggert
Post by Alan Mackenzie
Using my standard font, lat1-16, the curly quotes use the same glyphs as
` and ', hence are visibly indistinguishable from them.
That's no longer true as of yesterday's master commit
1a3518e7c361a9ceaa017c1334a83d14e0651a4e.
I'm afraid it is still true. After doing a C-h f c-mode, apparent
quotes were in the buffer. Checking them with C-u C-x =, they were
indeed curly quotes, but were displayed the same as ASCII quotes.
Man, this is like a renaissance of the Emacs 18 backspace/C-h
controversy. "your terminal should"/"no, it doesn't"/"any sane terminal
described by termcap/terminfo/ADM3A compatibility"/"no, it doesn't".

This change is _not_ going to buy us any new users. Reliability wins
over aesthetics (which can be ameliorated by font choices if you are
bothered) hands down, every time.

By the way, ' is an _apostrophe_. Changing it to an open single quote
mark in words like "don't" is utterly wrong, having to write \\=' for
every word with an apostrophe is not a reasonable option. Telling
apostrophes from right single quote marks is reasonably easy by looking
at the surrounding characters, but "reasonably easy" does not make for
an idiot-proof and idiot-rememberable rule. So we are buying into some
"do what I mean" territory here, and advanced word processor users will
love to tell you how much they love "autocorrecting" quotes.

I really don't see any sane way around defining some satisfactorily
natural markup sequences for quoting literal material inline and in
blocks.
--
David Kastrup
Paul Eggert
2015-09-02 22:25:49 UTC
Permalink
' is an_apostrophe_. Changing it to an open single quote
mark in words like "don't" is utterly wrong
I assume you meant “close single quote” not “open single quote”. (It
would indeed be utterly wrong to transliterate apostrophe to open single
quote, but Emacs doesn’t do that.)

The initial version of the quote-tranformation code behaved as you
suggested, and left isolated apostrophes alone. But Dmitry pointed out
that apostrophe in English is represented by right single quotation mark
as standard typographic practice in fonts with directed quotes, so I
changed Emacs to translate all non-escaped apostrophes. In practice
most isolated apostrophes in docstrings and diagnostics are intended to
be English apostrophes, so it seemed appropriate to transliterate them
as in English, of course with an escape hatch for those intended to be
Elisp apostrophes.

For more about common practice with apostrophes in natural-language
text, please see <http://www.languagegeek.com/typography/apostrophes.html>.
David Kastrup
2015-09-03 10:48:47 UTC
Permalink
Post by Paul Eggert
' is an_apostrophe_. Changing it to an open single quote
mark in words like "don't" is utterly wrong
I assume you meant “close single quote” not “open single quote”. (It
would indeed be utterly wrong to transliterate apostrophe to open
single quote, but Emacs doesn’t do that.)
The initial version of the quote-tranformation code behaved as you
suggested, and left isolated apostrophes alone. But Dmitry pointed
out that apostrophe in English is represented by right single
quotation mark as standard typographic practice in fonts with directed
quotes, so I changed Emacs to translate all non-escaped apostrophes.
In practice most isolated apostrophes in docstrings and diagnostics
are intended to be English apostrophes, so it seemed appropriate to
transliterate them as in English, of course with an escape hatch for
those intended to be Elisp apostrophes.
For more about common practice with apostrophes in natural-language
text, please see
<http://www.languagegeek.com/typography/apostrophes.html>.
Hardly a reputable source, and they mix up encoding with representation
awfully.

Looking up what the Unicode Consortium itself has to say about the issue
<URL:http://www.unicode.org/versions/Unicode8.0.0/ch06.pdf> tells us on
page 274:

Punctuation Apostrophe. U+2019 right single quotation mark is
preferred where the character is to represent a punctuation mark, as
for contractions: \u201cWe\u2019ve been here before.\u201d In this
latter case, U+2019 is also referred to as a punctuation apostrophe.

(by the way: is there any way to make Emacs stop this \u201c pasting
abomination when using C-y on an X Window selection?). Well, the whole
world appears to have gone mad. Why would they prefer a character
_explicitly_ called a right quote to a character called apostrophe when
writing an apostrophe?

But with regard to text processing (such as Word for Windows would do),
you clearly have the character set authorities on your side. With most
of my (monospaced) work fonts, that is a clearly inferior choice since
the glyph disrupts the flow of words.
--
David Kastrup
Andreas Schwab
2015-09-03 12:45:22 UTC
Permalink
Post by David Kastrup
(by the way: is there any way to make Emacs stop this \u201c pasting
abomination when using C-y on an X Window selection?).
Worksforme.

Andreas.
--
Andreas Schwab, SUSE Labs, ***@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE 1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."
Eli Zaretskii
2015-09-03 14:46:18 UTC
Permalink
Date: Thu, 03 Sep 2015 12:48:47 +0200
(by the way: is there any way to make Emacs stop this \u201c pasting
abomination when using C-y on an X Window selection?).
Is this in a GUI session? If so, I think last time this came up,
there was some setting or software outside Emacs that caused that.
Paul Eggert
2015-09-02 22:13:49 UTC
Permalink
Post by Alan Mackenzie
Checking them with C-u C-x =, they were
indeed curly quotes, but were displayed the same as ASCII quotes.
After fooling around with it on my Linux console, I came up with a
scenario that had the behavior you describe. In this scenario I set the
LC_ALL environment variable to en_US.UTF-8 even though the Linux console
could display only a few non-ASCII characters (so in some sense this is
a misconfiguration). And I put (setq text-quoting-style 'grave) into my
~/.emacs file, indicating that I wanted traditional ASCII quoting.
Emacs didn't look at the text-quoting-style setting when configuring the
display table at startup, which seems wrong, so I patched master to fix
that. Please do a git pull and give it a try. If it still doesn't work
for you, please send the output of the shell command ‘locale’ just
before invoking Emacs, and the output of the command ‘echo $TERM’, and a
copy of the Lisp code that sets text-quoting-style in your ~/.emacs
file. Thanks.
Alan Mackenzie
2015-09-03 12:22:09 UTC
Permalink
Hello, Paul.
Post by Paul Eggert
Post by Alan Mackenzie
Checking them with C-u C-x =, they were
indeed curly quotes, but were displayed the same as ASCII quotes.
After fooling around with it on my Linux console, I came up with a
scenario that had the behavior you describe. In this scenario I set the
LC_ALL environment variable to en_US.UTF-8 even though the Linux console
could display only a few non-ASCII characters (so in some sense this is
a misconfiguration). And I put (setq text-quoting-style 'grave) into my
~/.emacs file, indicating that I wanted traditional ASCII quoting.
Emacs didn't look at the text-quoting-style setting when configuring the
display table at startup, which seems wrong, so I patched master to fix
that. Please do a git pull and give it a try. If it still doesn't work
for you, please send the output of the shell command ‘locale’ just
before invoking Emacs, and the output of the command ‘echo $TERM’, and a
copy of the Lisp code that sets text-quoting-style in your ~/.emacs
file. Thanks.
You've cut so much context, left so many dangling prepositions, you've
left me confused as to what we're discussing. I suspect you've become
confused, too - the original scenario had nothing to do with
`text-quoting-style'.

Maybe later today, I'll try and reassemble the context and answer you.
But it really would be helpful if you would be less obfuscatory.
--
Alan Mackenzie (Nuremberg, Germany).
Paul Eggert
2015-09-03 14:56:05 UTC
Permalink
Post by Alan Mackenzie
the original scenario had nothing to do with
`text-quoting-style'.
There seemed little point to having two variables to control text quoting
behavior, one for initial inference of display quoting and one for translation
of help strings and diagnostics. So I used the same variable for all three.
Post by Alan Mackenzie
You've cut so much context
To help move things forward, here's a complete copy of the message I replied to,
along with a copy of my reply inserted at the appropriate spot, so that you can
see the complete context.
Post by Alan Mackenzie
Post by Alan Mackenzie
Hello, Paul.
Post by Paul Eggert
Post by Alan Mackenzie
Using my standard font, lat1-16, the curly quotes use the same glyphs as
` and ', hence are visibly indistinguishable from them.
That's no longer true as of yesterday's master commit
1a3518e7c361a9ceaa017c1334a83d14e0651a4e.
I'm afraid it is still true. After doing a C-h f c-mode, apparent
quotes were in the buffer. Checking them with C-u C-x =, they were
indeed curly quotes, but were displayed the same as ASCII quotes.
After fooling around with it on my Linux console, I came up with a scenario that had the behavior you describe. In this scenario I set the LC_ALL environment variable to en_US.UTF-8 even though the Linux console could display only a few non-ASCII characters (so in some sense this is a misconfiguration). And I put (setq text-quoting-style 'grave) into my ~/.emacs file, indicating that I wanted traditional ASCII quoting. Emacs didn't look at the text-quoting-style setting when configuring the display table at startup, which seems wrong, so I patched master to fix that. Please do a git pull and give it a try. If it still doesn't work for you, please send the output of the shell command ‘locale’ just before invoking Emacs, and the output of the command ‘echo $TERM’, and a copy of the Lisp code that sets text-quoting-style in your ~/.emacs file. Thanks.
Post by Alan Mackenzie
Post by Paul Eggert
On a terminal that cannot display curved quotes, ...
Currently, my terminal is not such a one. It _can_ display curly
quotes, but only identically to ASCII quotes. `char-displayable-p'
returns 'unicode for them.
The issue is not so much whether a terminal can display curly quotes,
rather it's whether a user wants them to be used or not.
Post by Paul Eggert
.... Emacs master now uses different glyphs for the quotes’ ASCII
replacements, because the replacements are shadowed. The shadowed
glyphs are easily distinguishable on my Linux console. Users
shouldn’t need to configure Emacs specially, or their Linux console
specially, to get this behavior. So this objection no longer applies.
Alan Mackenzie
2015-09-04 13:22:28 UTC
Permalink
Hello, Paul.
Post by Paul Eggert
Post by Alan Mackenzie
the original scenario had nothing to do with
`text-quoting-style'.
There seemed little point to having two variables to control text quoting
behavior, one for initial inference of display quoting and one for translation
of help strings and diagnostics. So I used the same variable for all three.
At the initial setup, there aren't yet configuration variables, are
there? .emacs hasn't yet been read.
Post by Paul Eggert
Post by Alan Mackenzie
You've cut so much context
To help move things forward, here's a complete copy of the message I replied to,
along with a copy of my reply inserted at the appropriate spot, so that you can
see the complete context.
Thanks for that. Yesterday wasn't a good day.
Post by Paul Eggert
Post by Alan Mackenzie
Post by Alan Mackenzie
Post by Paul Eggert
Post by Alan Mackenzie
Using my standard font, lat1-16, the curly quotes use the same glyphs as
` and ', hence are visibly indistinguishable from them.
That's no longer true as of yesterday's master commit
1a3518e7c361a9ceaa017c1334a83d14e0651a4e.
I'm afraid it is still true. After doing a C-h f c-mode, apparent
quotes were in the buffer. Checking them with C-u C-x =, they were
indeed curly quotes, but were displayed the same as ASCII quotes.
I've just updated my git-master Emacs again, and the situation still
holds: With emacs -Q, C-h f c-mode displays a buffer containing curly
quotes, these curly quotes being visibly indistinguishable from ASCII
quotes.

In particular, I've not seen any shadowed quotes on my screen no matter
what I've done.
Post by Paul Eggert
Post by Alan Mackenzie
After fooling around with it on my Linux console, I came up with a
scenario that had the behavior you describe. In this scenario I set
the LC_ALL environment variable to en_US.UTF-8 even though the Linux
console could display only a few non-ASCII characters (so in some
sense this is a misconfiguration). And I put (setq
text-quoting-style 'grave) into my ~/.emacs file, indicating that I
wanted traditional ASCII quoting.
After I execute M-: (setq text-quoting-style 'grave), my next C-h f does
indeed use ASCII quotes.
Post by Paul Eggert
Post by Alan Mackenzie
Emacs didn't look at the text-quoting-style setting when configuring
the display table at startup, which seems wrong, so I patched master
to fix that. Please do a git pull and give it a try.
Done. See above. But isn't startup done before processing .emacs?
Post by Paul Eggert
Post by Alan Mackenzie
If it still doesn't work for you, please send the output of the shell
command ‘locale’ just before invoking Emacs, and the output of the
command ‘echo $TERM’, and a copy of the Lisp code that sets
text-quoting-style in your ~/.emacs file. Thanks.
Just for completeness's sake, I have $TERM=linux, no LC_.. variable is
set, and I don't yet have `text-quoting-style' in my .emacs, but will
probably write (setq text-quoting-style 'grave) into it at some stage.
Post by Paul Eggert
Post by Alan Mackenzie
Post by Alan Mackenzie
Post by Paul Eggert
On a terminal that cannot display curved quotes, ...
Incidentally, I just tried running Emacs under X Windows, and there I
found the two curly quotes visibly indistinguishable from each other,
except with a lot of effort, and they were both indistinguishable from
the ASCII apostrophe, unless there was one nearby on the screen to
compare with.
Post by Paul Eggert
Post by Alan Mackenzie
Post by Alan Mackenzie
Currently, my terminal is not such a one. It _can_ display curly
quotes, but only identically to ASCII quotes. `char-displayable-p'
returns 'unicode for them.
`char-displayable-p' isn't very useful here. It does not check whether a
glyph is assigned to a character code, and I don't even think Linux
offers a suitable interface for this.
Post by Paul Eggert
Post by Alan Mackenzie
Post by Alan Mackenzie
The issue is not so much whether a terminal can display curly quotes,
rather it's whether a user wants them to be used or not.
Post by Paul Eggert
.... Emacs master now uses different glyphs for the quotes’ ASCII
replacements, because the replacements are shadowed. The shadowed
glyphs are easily distinguishable on my Linux console. Users
shouldn’t need to configure Emacs specially, or their Linux console
specially, to get this behavior. So this objection no longer applies.
--
Alan Mackenzie (Nuremberg, Germany).
Stefan Monnier
2015-09-02 20:14:38 UTC
Permalink
Post by Alan Mackenzie
Using my standard font, lat1-16, the curly quotes use the same glyphs as
` and ', hence are visibly indistinguishable from them.
So they're just as pretty. Looks like a non-issue, then.
Post by Alan Mackenzie
All of what I write above I've written before. In addition, the
necessity to type a C-x 8 combination to type a curly quote is a serious
impediment.
So you don't want to type them. I don't either, so we're in agreement.

Any other issue?


Stefan
Paul Eggert
2015-09-01 19:25:28 UTC
Permalink
Post by Stefan Monnier
- The `...' markup (and it is markup) is ambiguous.
It certainly is (and always has been, alas), but before jumping into
improving it, could you explain what ambiguities you'd like to resolve
with an improved markup?

Currently `...' markup in docstrings is used for:

* Symbols, e.g., `load-file'

* Info nodes, e.g., `(emacs)Lisp Libraries'.

* URLs, e.g., `http://bama.ua.edu/cgi-bin/man-cgi?lp'

* Characters, e.g., `&', ` '.

* Key sequences, e.g., `C-x ESC O P'.

* Strings, e.g., `69'.

* Regular expressions, e.g., `\\(_P\\|_PROTO\\)'.

* English phrases, e.g., `close in spirit', `things'.

* Lisp patterns, e.g., `(ATOM . ELLIPSIS)'.

* Lisp code, e.g., `(thai nil nil (mark))'.

* Non-Lisp code, e.g., `ls -lR'.

* Probably some other stuff I’ve missed.

Most of these items are sometimes put in block quotations rather than in
quote symbols, if they are long enough.

So, when removing ambiguity, how many categories would you like to put
the above examples in? And how should the different categories be
rendered on plain-text consoles and on graphical displays? I sort of
have the impression that by “markup” you mean “things that should turn
into links”, but maybe you mean “things that should be rendered in
fixed-width font if we have a nice display”, or maybe there are two or
even more kinds of markup that you have in mind.
Richard Stallman
2015-09-07 01:28:17 UTC
Permalink
[[[ 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. ]]]
Post by Paul Eggert
* English phrases, e.g., `close in spirit', `things'.
English quotations should use doublequotes.
We use singlequotes only to present strings of example text
to be processed in a program somehow. In the case of Emacs,
they are for text that gets manipulated inside Emacs.
Post by Paul Eggert
* Key sequences, e.g., `C-x ESC O P'.
Key sequences (which only go through the keyboard) shouldn't be
quoted with singlequotes, or any kind of quotes.

* Lisp patterns, e.g., `(ATOM . ELLIPSIS)'.

* Lisp code, e.g., `(thai nil nil (mark))'.

These two cases (which are really the same case, since you can put a
metasyntactic variable into anything) are not supposed to be quoted
with singlequotes.

The following cases do get quoted with singlequotes:

* Symbols, e.g., `load-file'

* Info nodes, e.g., `(emacs)Lisp Libraries'.

* URLs, e.g., `http://bama.ua.edu/cgi-bin/man-cgi?lp'

* Characters, e.g., `&', ` '.

* Strings, e.g., `69'.

* Regular expressions, e.g., `\\(_P\\|_PROTO\\)'.

* Non-Lisp code, e.g., `ls -lR'.

It could conceivably be useful to use multiple kinds of quotation to
distinguish among these cases. But we can't have enough kinds of
quotation marks to give each of these its own kind. One would
need to use quoting style A for some of then, style B for some others,
style C for some others, etc.

It would take careful thought to figure out how to distribute (say)
three styles of showing quotes among those different uses.

I am not sure it is worth doing anything about.
--
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.
Dmitry Gutov
2015-09-01 19:33:13 UTC
Permalink
Post by Stefan Monnier
So I thought we were going to replace the `...' markup with ‘...’ markup
(which fixes both points at the same time if we assume that we keep
sticking to ASCII quotes for the rest, tho at the cost of using
non-ASCII markup).
That would undermine another stated goal (by Paul): improve the
typography in Emacs.
Post by Stefan Monnier
But if we start using curly quotes everywhere, then we're back with the
ambiguity, so that's not a good solution.
So what's the exact ambiguity that you have in mind? Code references or
snippets vs. everything else like key sequences?

Then I definitely misunderstood you a while back.
Post by Stefan Monnier
So maybe a better option is to refine the `...' markup to get rid of
- `...' is only considered valid markup if ... doesn't contain any
whitespace (or some such restriction: it should be a simple rule that
still accepts most existing uses, especially those where we want to
place a hyperlink).
We might also want to support code snippets like `(progn (foo bar
foo))'. At least, elisp-completion-at-point relies on snippets being
quoted that way now. We can detect these using paired parens.
Post by Stefan Monnier
- All other occurrences of ` and ' are treated a standalone ASCII chars
rather than as part of some markup.
So `C-x C-f' is not valid markup any more (and won't be prettified).
If you like (though I'd rather keep prettifying them until we introduce
a better way to emphasize them as key sequences: there's no apparent
value in not making them pretty).
Stefan Monnier
2015-09-02 02:34:11 UTC
Permalink
That would undermine another stated goal (by Paul): improve the typography
in Emacs.
I think this goal should have very low priority.
Post by Stefan Monnier
But if we start using curly quotes everywhere, then we're back with the
ambiguity, so that's not a good solution.
So what's the exact ambiguity that you have in mind? Code references or
snippets vs. everything else like key sequences?
Then I definitely misunderstood you a while back.
W.r.t ambiguity, the main problem I see is that we currently can never
be sure that when we see a ` followed by a ' the two actually form a pair.
A human usually can tell, but a program can't get it right 100% of the time.
We might also want to support code snippets like `(progn (foo bar foo))'.
At least, elisp-completion-at-point relies on snippets being quoted
that way now. We can detect these using paired parens.
Not sure I want to go down that road. What about `(foo 'a 'b)' ?
AFAIK it's not very common (yet?) to quote code that way, and I'm not
sure we want to get into the habit of quoting it that way. I could see
the need/advantage of quoting code reliably, but I don't think `...' is
a good way to do it.


Stefan
David Kastrup
2015-09-02 05:23:33 UTC
Permalink
Post by Stefan Monnier
That would undermine another stated goal (by Paul): improve the typography
in Emacs.
I think this goal should have very low priority.
Post by Stefan Monnier
But if we start using curly quotes everywhere, then we're back with the
ambiguity, so that's not a good solution.
So what's the exact ambiguity that you have in mind? Code references or
snippets vs. everything else like key sequences?
Then I definitely misunderstood you a while back.
W.r.t ambiguity, the main problem I see is that we currently can never
be sure that when we see a ` followed by a ' the two actually form a pair.
A human usually can tell, but a program can't get it right 100% of the time.
We might also want to support code snippets like `(progn (foo bar foo))'.
At least, elisp-completion-at-point relies on snippets being quoted
that way now. We can detect these using paired parens.
Not sure I want to go down that road. What about `(foo 'a 'b)' ?
Appears to work fine using paired parens when parsed from the start.
--
David Kastrup
Dmitry Gutov
2015-09-02 11:16:28 UTC
Permalink
Post by Stefan Monnier
W.r.t ambiguity, the main problem I see is that we currently can never
be sure that when we see a ` followed by a ' the two actually form a pair.
A human usually can tell, but a program can't get it right 100% of the time.
Okay. But then, there's no problem in using the same quoting for key
sequences, aside from the quote-matching algorithm.
Post by Stefan Monnier
We might also want to support code snippets like `(progn (foo bar foo))'.
At least, elisp-completion-at-point relies on snippets being quoted
that way now. We can detect these using paired parens.
Not sure I want to go down that road. What about `(foo 'a 'b)' ?
That, too. At least if this quote-matching logic is implemented in
Elisp, forward-sexp can take care of skipping the spaces.
Post by Stefan Monnier
AFAIK it's not very common (yet?) to quote code that way, and I'm not
sure we want to get into the habit of quoting it that way. I could see
the need/advantage of quoting code reliably, but I don't think `...' is
a good way to do it.
If we take after Markdown (because why not?), it has two methods of
quoting code: one for inline code (also used for references), and one
for code blocks (on separate lines).

It might be a good idea to also have just one quoting method for inline
code. But if you have a better idea for quoting code, that's fine, too.
David Kastrup
2015-09-02 11:52:22 UTC
Permalink
Post by Dmitry Gutov
Post by Stefan Monnier
W.r.t ambiguity, the main problem I see is that we currently can never
be sure that when we see a ` followed by a ' the two actually form a pair.
A human usually can tell, but a program can't get it right 100% of the time.
Okay. But then, there's no problem in using the same quoting for key
sequences, aside from the quote-matching algorithm.
Moving passages into some sort of string container or else needing some
sort of specific quotation style in order to preserve literal content
seems like a frequent problem.

How about defining some prefix to be used right before C-w or C-y and
related commands that will then strip/interpret the respective suspected
quote sequences going into the kill buffer, and add them when going out?

It would likely need some well-defined mode-specific hooks providing the
string-packing and unpacking, defaulting to something working reasonably
sanely with the union of C and Elisp strings but hopefully taken up by
most mode providers eventually.

Having a standardized mode-specific view into stringizing and
unstringifying passages (prefix arg for specifying the particular quote
style defaulting to " (2) in most modes? Something like an input method
selector for that?) might be useful for other generic functionality and
keybindings. But at the very least a standard for "-quoted strings
seems like a good idea.
--
David Kastrup
Stefan Monnier
2015-09-03 14:34:25 UTC
Permalink
Post by Stefan Monnier
W.r.t ambiguity, the main problem I see is that we currently can never
be sure that when we see a ` followed by a ' the two actually form a pair.
A human usually can tell, but a program can't get it right 100% of the time.
Okay. But then, there's no problem in using the same quoting for key
sequences, aside from the quote-matching algorithm.
I'm not fundamentally opposed to it, but I'd like the rule to be *simple*.

If we try and accommodate key sequences, I'm afraid the rule will become
too complex, and we'll bump into corner cases like how to
quote key sequences like C-x ' or M-`. In most cases, there shouldn't
be key sequences in docstrings anyway since we should use \\[...]
instead, so there's no strong need to accommodate quoting of key sequences.
Post by Stefan Monnier
Not sure I want to go down that road. What about `(foo 'a 'b)' ?
That, too. At least if this quote-matching logic is implemented in Elisp,
forward-sexp can take care of skipping the spaces.
Yes, again it can be made to work. But what it boils down to is this:
- `...' can't handle all cases without breaking existing uses, so we'll
need another quoting mechanism anyway.
- in most cases, I don't see a strong need to quote code like (foo a b).
Maybe at some point we'll start doing things like "prettifying" the
code in docstrings, at which point we'll need it to be quoted, but
until that happens, the cost/benefit tradeoff is in favor of keeping
the code unquoted.
- so I don't see a strong need to accommodate quoting like `(foo a b)'.
If the simple rule we devise happens to allow it, that's fine,
of course.


Stefan
Richard Stallman
2015-09-01 22:57:33 UTC
Permalink
[[[ 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. ]]]
Post by Oleh Krehel
And to restate my opinion on the matter, since I haven't participated in
this discussion for a few months: Elisp code should be treated as
markup.
That's a very clear expression of what I too think.
Post by Oleh Krehel
If it were up to me, I'd revert everything until there wasn't a single
curly in the code part. Having markup that translates to curlies is
absolutely fine with me.
Indeed.
--
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.
Richard Stallman
2015-09-01 00:03:56 UTC
Permalink
[[[ 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. ]]]
- (insert "Don't output anything.\n"))
+ (insert "Don’t output anything.\n"))
I think that is erroneous because it makes the curly quote unconditional.
That should be conditional.

However, since ccl-dump is meant for debugging, there is no reason to
bother with curly quotes 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.
Paul Eggert
2015-09-01 01:20:16 UTC
Permalink
Post by Richard Stallman
That should be conditional.
Yes, this was fixed by making it conditional in master commit
6514fe88904e658c527deae5be9a3f6ac539653f.
Paul Eggert
2015-08-31 06:39:50 UTC
Permalink
Post by Dmitry Gutov
Who said the source code examples should looks the same as a output?
It's better for beginners to have examples where (print "FOO") outputs FOO
rather than some other string.
Dmitry Gutov
2015-08-31 06:47:38 UTC
Permalink
Post by Paul Eggert
It's better for beginners to have examples where (print "FOO") outputs
FOO rather than some other string.
No, it isn't. That doesn't impact understanding of the snippet at all.

If anything, the sooner they encounter the convoluted results of your
choices WRT quotes, the better.

Writing example docstrings with curly quotes for the stated reason
doesn't hold water either.
Paul Eggert
2015-08-31 06:53:11 UTC
Permalink
Post by Dmitry Gutov
That doesn't impact understanding of the snippet at all.
Those snippets are not about quote translation; they are about other topics. We
shouldn't introduce the rather specialized topic of quote translation in the
tutorial, as that's a topic needed only by advanced users and would be a
distraction in tutorial examples. We should simply use strings that users will
normally see as themselves, as that's the most intuitive and won't get in the
way of the real topics there.
Dmitry Gutov
2015-08-31 07:00:32 UTC
Permalink
Post by Paul Eggert
Those snippets are not about quote translation; they are about other
topics.
Then the quote translation won't have any meaningful impact on the
observed behavior one way or the other.

But if it's such a problem, don't use quotes in the examples.
Post by Paul Eggert
We should simply
use strings that users will normally see as themselves, as that's the
most intuitive and won't get in the way of the real topics there.
If you think the translation behavior is hard for a user to understand,
why not revert the whole rigamarole? It doesn't add *that* much value.
Paul Eggert
2015-08-31 07:13:56 UTC
Permalink
Post by Dmitry Gutov
But if it's such a problem
It's not a problem. Tutorial readers will see quotes that stand for themselves.
Post by Dmitry Gutov
If you think the translation behavior is hard for a user to understand
I don't.
Richard Stallman
2015-09-01 00:03:57 UTC
Permalink
[[[ 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 think this change is misconceived.
diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index f1480a4..a27a969 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -3862,10 +3862,10 @@ tiger!} will be printed; otherwise, @code{nil} will be returned.
@group
(defun type-of-animal (characteristic)
"Print message in echo area depending on CHARACTERISTIC.
-If the CHARACTERISTIC is the symbol `fierce',
+If the CHARACTERISTIC is the symbol ?fierce?,
then warn of a tiger."
(if (equal characteristic 'fierce)
- (message "It's a tiger!")))
+ (message "It?s a tiger!")))
@end group
@end smallexample
This is not an example of what appears in a Help buffer.
It is an example of source code. Doc strings should be written
with straight quotes, so the example should show straight quotes.

Likewise, the call to message should use a straight quote.
It will usually typically _output_ a curly quote if it uses 'format-message',
but this example shows the source code, not the output.
It's correct because it shows the output. However, the text should
explain (without the full detail) the difference in quotes. Perhaps

On terminals that can display curly quotes, 'message' changes ASCII
quotes to curly ones.
--
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.
Paul Eggert
2015-09-02 01:05:15 UTC
Permalink
Post by Richard Stallman
Doc strings should be written
with straight quotes, so the example should show straight quotes.
That example came very early in the tutorial, where it's inappropriate to be
burdening the novice reader with low-priority detail like quoting, so I rewrote
it to use neither curved nor grave quotes, thus sidestepping the issue in that
example.

I also reverted the changes that curved the quotes in the the bulk of the
examples, which were taken from Emacs 22, so they now quote `like this' as before.
Post by Richard Stallman
However, the text should
explain (without the full detail) the difference in quotes.
I added text to do that as well.

All the above is in master commit afe1cf00713847c1d8f3a9d95d4980d705ec39f1.

More generally, though, I did not remove every single curved quote from the
tutorial. That is because it's fine if some programmers want to use curved
quotes in docstrings and diagnostics. These quotes have worked for many years,
and they now work even a bit better than they did before, in the sense that
they're now markup that is automatically converted to grave quotes for
old-fashioned users who prefer the grave style. Using curved quotes in the
source has technical advantages, as the programmer sees the same quotes that
typical users will see in the next version of Emacs, which is a clear win. Of
course it also has technical disadvantages, for developers who have trouble
dealing with non-ASCII characters or who want to have code that generates
diagnostics or help buffers that quote `like this' in older Emacs versions, but
overall in many cases the benefits exceed the costs and it is a win, and it's OK
for the Emacs documentation to cover this alternative.

As far as the Emacs source code goes, because the master for a while had an
approach that required the use of curved quotes for proper markup, and because I
was using Electric Quote mode where it's easier to type curved than straight
quotes, I converted some diagnostics and documentation source to use curved
quotes. Most (though not all) of these curved quotes can now be converted back
to grave quotes if someone who hates, Hates, HATES curved quotes wants to take
the trouble to do that. However, I doubt whether it's worth the effort, as the
curved quotes work fine in practice in the source, and really, why not give them
a try? In practice they might not be as bad as all that.
David Kastrup
2015-09-02 01:27:14 UTC
Permalink
Post by Paul Eggert
Post by Richard Stallman
Doc strings should be written
with straight quotes, so the example should show straight quotes.
That example came very early in the tutorial, where it's inappropriate
to be burdening the novice reader with low-priority detail like
quoting,
It stops being a low-priority detail when it is not possible to write
basic Lisp expressions without employing \\= liberally.

In fact, in many DOC strings writing 'xxx as an isolated expression you
have instead substituted `xxx' instead. Switching from a version the
Lisp interpreter will accept to a version that requires quoting by the
user is not a mere cosmetic change.

If we change Emacs to a system that treats "novice readers" with
contempt, not worth teaching correct code and documentation, that is a
solid step backwards from hacker ethics.
--
David Kastrup
Paul Eggert
2015-09-02 01:30:55 UTC
Permalink
Post by David Kastrup
In fact, in many DOC strings writing 'xxx as an isolated expression you
have instead substituted `xxx' instead.
I did that only when the 'xxx appeared to be a not-properly-quoted value, not an
isolated source-code expression. In cases where it was an expression I escaped
the apostrophe. Admittedly there are some gray areas, and in areas where I
misinterpreted please feel free to change it back.
David Kastrup
2015-09-02 05:19:03 UTC
Permalink
Post by Paul Eggert
Post by David Kastrup
In fact, in many DOC strings writing 'xxx as an isolated expression you
have instead substituted `xxx' instead.
I did that only when the 'xxx appeared to be a not-properly-quoted
value, not an isolated source-code expression.
Are you seriously suggesting that people wrote things like 'safe for a
symbol value because they forgot a closing quote character?

Let's see a few examples from the most recent quote-changing diff:

ID-FORMAT specifies the preferred format of attributes uid and gid (see
-below) - valid values are 'string and 'integer. The latter is the
+below) - valid values are `string' and `integer'. The latter is the
default, but we plan to change that, so you should specify a non-nil value

doc: /* List of potentially supported image types.
-Each element of the list is a symbol for an image type, like 'jpeg or 'png.
+Each element of the list is a symbol for an image type, like `jpeg' or `png'.
To check whether it is really supported, use `image-type-available-p'. */);

DEFUN ("set-message-beep", Fset_message_beep, Sset_message_beep, 1, 1, 0,
doc: /* Set the sound generated when the bell is rung.
-SOUND is 'asterisk, 'exclamation, 'hand, 'question, 'ok, or 'silent
-to use the corresponding system sound for the bell. The 'silent sound
+SOUND is `asterisk', `exclamation', `hand', `question', `ok', or `silent'
+to use the corresponding system sound for the bell. The `silent' sound
prevents Emacs from making any sound at all.
Post by Paul Eggert
In cases where it was an expression I escaped the apostrophe.
Admittedly there are some gray areas, and in areas where I
misinterpreted please feel free to change it back.
How is one supposed to resolve anything in discussion when you
constantly and habitually spin the facts and play word games and play
dumb?
--
David Kastrup
Paul Eggert
2015-09-02 05:30:58 UTC
Permalink
Post by David Kastrup
ID-FORMAT specifies the preferred format of attributes uid and gid (see
-below) - valid values are 'string and 'integer. The latter is the
+below) - valid values are `string' and `integer'. The latter is the
Yes, that's where the documentation was technically incorrect to write
“'integer”. The valid value is not ‘'integer’, i.e., ‘(quote integer)’; the
valid value is just the symbol ‘integer’. Similarly for the other examples you
gave. This is a minor technical documentation error that is not likely to
confuse many people, but I figured I might as well get it right while fixing
things in the neighborhood.
Richard Stallman
2015-09-02 15:40:18 UTC
Permalink
[[[ 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. ]]]
Post by David Kastrup
DEFUN ("set-message-beep", Fset_message_beep, Sset_message_beep, 1, 1, 0,
doc: /* Set the sound generated when the bell is rung.
-SOUND is 'asterisk, 'exclamation, 'hand, 'question, 'ok, or 'silent
-to use the corresponding system sound for the bell. The 'silent sound
+SOUND is `asterisk', `exclamation', `hand', `question', `ok', or `silent'
+to use the corresponding system sound for the bell. The `silent' sound
prevents Emacs from making any sound at all.
These changes are necessary in any case; the old text violates
Emacs documentation conventions. It is incorrect to indicate
a symbol in text by writing a singlequote before it.
The correct way is to write quotes around it (except for t and nil).
--
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.
David Kastrup
2015-09-02 16:32:45 UTC
Permalink
Post by 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. ]]]
Post by David Kastrup
DEFUN ("set-message-beep", Fset_message_beep, Sset_message_beep, 1, 1, 0,
doc: /* Set the sound generated when the bell is rung.
-SOUND is 'asterisk, 'exclamation, 'hand, 'question, 'ok, or 'silent
-to use the corresponding system sound for the bell. The 'silent sound
+SOUND is `asterisk', `exclamation', `hand', `question', `ok', or `silent'
+to use the corresponding system sound for the bell. The `silent' sound
prevents Emacs from making any sound at all.
These changes are necessary in any case; the old text violates
Emacs documentation conventions. It is incorrect to indicate
a symbol in text by writing a singlequote before it.
The correct way is to write quotes around it (except for t and nil).
Thanks.

My actual point of annoyance was the total inability to get any useful
feedback concerning such changes because of semantic gameplay.
--
David Kastrup
Dmitry Gutov
2015-09-03 15:38:11 UTC
Permalink
Post by Paul Eggert
More generally, though, I did not remove every single curved quote from
the tutorial. That is because it's fine if some programmers want to use
curved quotes in docstrings and diagnostics. These quotes have worked
for many years, and they now work even a bit better than they did
before, in the sense that they're now markup that is automatically
converted to grave quotes for old-fashioned users who prefer the grave
style.
They aren't markup, because you insist that they "stand for themselves",
which is as far from the concept of markup as it could be.
Post by Paul Eggert
Using curved quotes in the source has technical advantages, as
the programmer sees the same quotes that typical users will see in the
next version of Emacs, which is a clear win.
Nothing clear about that. Programmers are used to even larger levels of
abstraction than quote translation. Which is relatively trivial.
Post by Paul Eggert
or help buffers that quote `like this' in older Emacs versions, but
overall in many cases the benefits exceed the costs and it is a win
[citation needed]
Post by Paul Eggert
As far as the Emacs source code goes, because the master for a while had
an approach that required the use of curved quotes for proper markup,
and because I was using Electric Quote mode where it's easier to type
curved than straight quotes, I converted some diagnostics and
documentation source to use curved quotes.
Even though you've been specifically asked not to.
Post by Paul Eggert
Most (though not all) of
these curved quotes can now be converted back to grave quotes if someone
who hates, Hates, HATES curved quotes wants to take the trouble to do
that.
Well, that's nice. Thank you for that chunk of pointless work that I (or
someone else) will have to do. I take it there are no other things you'd
prefer me to spend time on instead.
Post by Paul Eggert
However, I doubt whether it's worth the effort, as the curved
quotes work fine in practice in the source, and really, why not give
them a try? In practice they might not be as bad as all that.
The "work fine in practice" argument is weak. A vast number of
approaches will work well enough if you don't care about increased
complexity (something that Alan brought up), or further improvements
that might be built on top of docstring markup.
Paul Eggert
2015-09-03 17:42:56 UTC
Permalink
Post by Dmitry Gutov
They aren't markup, because you insist that they "stand for themselves"
They’re both. They’re markup that typically stand for themselves when
generating text, and that’s a win over markup that doesn’t do that. It’s like
Markdown’s syntax for URLs: you just type http://example.com and it just works.
(Emacs docstrings would do well to support that idea too, but I’m digressing....)
Dmitry Gutov
2015-09-03 18:49:20 UTC
Permalink
Post by Paul Eggert
They’re both. They’re markup that typically stand for themselves when
You can just as well call the letters of the alphabet "markup that
stands for itself". Or, less contrivedly, programming language keywords
or words with typos (which flyspell will highlight).
Post by Paul Eggert
generating text, and that’s a win over markup that doesn’t do that.
Not at all. It's more error prone:

If the programmer types `foo`, they can look at the output and see that
the quotes were not recognized as a matching pair (don't render as
expected).

If the programmer types ‘foo‘, they can easily miss the non-matching
quotes if they expect the output to look the same as input. Everyone who
configured Emacs to render quotes differently will bear the pain of that
mistake, but not the author.
Post by Paul Eggert
It’s like Markdown’s syntax for URLs: you just type http://example.com
and it just works. (Emacs docstrings would do well to support that idea
too, but I’m digressing....)
It's no syntax, just auto-linkification in the renderer. And it's
notoriously error-prone; the types of URLs that get broken during
auto-linkification change from program to program.
Paul Eggert
2015-09-03 21:50:26 UTC
Permalink
If the programmer types `foo`, they can look at the output and see that the
quotes were not recognized as a matching pair (don't render as expected).
If the programmer types ‘foo‘, they can easily miss the non-matching quotes
First, the two scenarios are the same in the typical text-quoting-style case,
because the output looks like ‘foo‘ either way, and whatever method works for
detecting input `foo` will work equally well for detecting input ‘foo‘.

Second and more important, it’s more efficient to detect and fix this issue
immediately while typing, as the highlighting around the foo won’t be as
expected and a programmer can see that easily right away and just backspace and
fix the bad quote while it’s fresh. It’d be considerably more awkward and
error-prone to detect the problem only when it’s rendered into a *Help* buffer.
Dmitry Gutov
2015-09-03 22:08:49 UTC
Permalink
Post by Paul Eggert
If the programmer types ‘foo‘, they can easily miss the non-matching quotes
First, the two scenarios are the same in the typical text-quoting-style
case, because the output looks like ‘foo‘ either way,
Not if the translation logic checks for pairing. This is not true of the
current code (IIUC), but it was true not too long ago, and that's what
Stefan's asking for as well.
Post by Paul Eggert
and whatever
method works for detecting input `foo` will work equally well for
detecting input ‘foo‘.
What method are you thinking of? Lint-like highlighting in red is only
feasible if the syntax is strict.
Post by Paul Eggert
Second and more important, it’s more efficient to detect and fix this
issue immediately while typing, as the highlighting around the foo won’t
be as expected and a programmer can see that easily right away and just
backspace and fix the bad quote while it’s fresh.
Checking highlighting is good, but it only works when we're quoting
simple symbols. Not Lisp expressions, key sequences or anything else
like that.

Also, please recall that highlighting is performed in Lisp. Since you've
opted to do translation in C, font-lock cannot accurately handle the
quoting syntax, with escapes and etc.
Post by Paul Eggert
It’d be considerably
more awkward and error-prone to detect the problem only when it’s
rendered into a *Help* buffer.
Checking that the output looks right is a natural urge either way.

My main point is, in general, non-translating "markup" invites typos.

Emacs is powerful enough to paper over many problems, but maybe one
should take a hint earlier and spend effort where it really matters.
Paul Eggert
2015-09-03 22:47:34 UTC
Permalink
Post by Dmitry Gutov
Post by Paul Eggert
If the programmer types ‘foo‘, they can easily miss the non-matching quotes
First, the two scenarios are the same in the typical text-quoting-style
case, because the output looks like ‘foo‘ either way,
Not if the translation logic checks for pairing.
Ah, sorry, I thought the context was the current Emacs master, not Emacs after
some further changes are applied to it. In the current master most of the
problems you mentioned are not a big deal in practice, as typically there's
immediate visual feedback when one types the wrong quote. It is true that in
some more-complicated cases this breaks down, but this is a nearly inevitable
consequence of any markup syntax that uses quotes to represent so many different
concepts, regardless of whether the syntax uses ASCII or curved quotes.

You are correct in that if we came up with a different markup syntax that was
more systematic and organized, many of these more-complicated cases would work
better.
Dmitry Gutov
2015-09-03 22:59:28 UTC
Permalink
Post by Paul Eggert
Ah, sorry, I thought the context was the current Emacs master, not Emacs
after some further changes are applied to it.
The context is what Emacs master had been not too long ago, as well as
what it'll most likely be in the future.
Post by Paul Eggert
In the current master
most of the problems you mentioned are not a big deal in practice, as
typically there's immediate visual feedback when one types the wrong
quote.
You keep saying "not a big deal in practice". The original problem
(straight quotes) never was a "big deal in practice", yet you saw fit to
introduce many changes to fix it. Fixing it while keeping many known
(and new) shortcomings doesn't make sense.
Post by Paul Eggert
It is true that in some more-complicated cases this breaks down,
but this is a nearly inevitable consequence of any markup syntax that
uses quotes to represent so many different concepts, regardless of
whether the syntax uses ASCII or curved quotes.
Not if the programmer looks at the output (a Help buffer, for example).
The output will necessarily be "correct". However, like I wrote, if the
output is the same as input by default, looking at the output won't help
you find problems.
Post by Paul Eggert
You are correct in that if we came up with a different markup syntax
that was more systematic and organized, many of these more-complicated
cases would work better.
Doing everything better is not a necessary condition. Doing only some of
the things better might suffice.
Richard Stallman
2015-09-07 01:28:18 UTC
Permalink
[[[ 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. ]]]
Post by Paul Eggert
More generally, though, I did not remove every single curved quote from the
tutorial. That is because it's fine if some programmers want to use curved
quotes in docstrings and diagnostics.
They can write anything they like in their own programs, but it's not "fine".
They are not supposed to do this in the Emacs sources.

The Lisp Intro should show recommended practice, not complicate
matters with other ways. So please remove the curly quotes from the
Lisp Intro (and any other manuals).
--
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.
Loading...