bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Drew Adams]

Emacs Info manuals have long used double-quotes for two things:

* Setting off terms that are defined (e.g., glossary terms).
  (This is presumably the case for the occurrence of "codepages"
  in this same node.)

* Programming strings - e.g. Lisp strings (including file-name strings).

In (emacs) `Coding Sytems', at least, it seems that Curly-Quote Mania
has struck another nasty blow:

   In addition to converting various representations of non-ASCII
 characters, a coding system can perform end-of-line conversion.  Emacs
 handles three different conventions for how to separate lines in a file:
 newline ("unix"), carriage-return linefeed ("dos"), and just
 carriage-return ("mac").

Why curly double-quotes here?  Either those quoted names are supposed
to be Lisp strings or they are proper names.  In the latter case they
should not be quoted at all, and they should be properly capitalized.
In the former case (which is what I'm guessing is meant), plain ASCII
double-quote chars should be used.

Please don't confuse users this way, and make them guess what is meant.
Get it straight, please.

Plain ASCII double-quote chars should always be used for strings.

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-08-16 on LEG570
Bzr revision: f7ee23e587b01f179284b5554c67d579a2def676
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=3Di686-pc-mingw32 --enable-checking=3Dyes,glyphs'

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Eli Zaretskii]

> Date: Sun, 13 Sep 2015 08:45:01 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
>    In addition to converting various representations of non-ASCII
>  characters, a coding system can perform end-of-line conversion.  Emacs
>  handles three different conventions for how to separate lines in a file:
>  newline ("unix"), carriage-return linefeed ("dos"), and just
>  carriage-return ("mac").
> 
> Why curly double-quotes here?

These are literal strings, so they are quoted.

> Either those quoted names are supposed
> to be Lisp strings or they are proper names.  In the latter case they
> should not be quoted at all, and they should be properly capitalized.
> In the former case (which is what I'm guessing is meant), plain ASCII
> double-quote chars should be used.

Latest versions of makeinfo convert ``...'' into “...”.  That's life,
you should get used to it.  It won't go away, no matter how many "bug
reports" you will file for that.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Drew Adams]

> >    In addition to converting various representations of non-ASCII
> >  characters, a coding system can perform end-of-line conversion.  Emacs
> >  handles three different conventions for how to separate lines in a
> >  file:  newline ("unix"), carriage-return linefeed ("dos"), and just
> >  carriage-return ("mac").
> >
> > Why curly double-quotes here?
> 
> These are literal strings, so they are quoted.

Literal for what purpose?  What is being quoted?  None of those
"strings" of text is used normally without capitalization.

And if they are in fact supposed to be "strings" in the
programming sense then straight ASCII double-quotes are what
we use (in the rest of the manual).

Search for such curly double quotes, and you will not, I think,
find other such occurrences.  The other occurrences are of
terms that we introduce (e.g., define).

This is *not* a general problem.  It is not about the use of
curly double-quotes in, for example, the copyright statement
(e.g.,  “You have the freedom to copy and modify this GNU manual.
Buying copies from the FSF supports it in developing GNU and
promoting software freedom.”).

> > Either those quoted names are supposed
> > to be Lisp strings or they are proper names.  In the latter case they
> > should not be quoted at all, and they should be properly capitalized.
> > In the former case (which is what I'm guessing is meant), plain ASCII
> > double-quote chars should be used.
> 
> Latest versions of makeinfo convert ``...'' into “...”.

So these particular occurrences of ``...'' were also incorrect
previously.

> That's life, you should get used to it.  It won't go away,
> no matter how many "bug reports" you will file for that.

You are apparently fighting a phantom.  I've even modified
my own Info enhancements so they fontify the text between
such curly double-quotes.  In a separate face, because the
quoted text does not have the same meaning as that enclosed
in straight ASCII double-quotes (a string) or that enclosed
between curly single-quotes (what was formerly `...').

The point of this bug is that those *particular* terms do
not belong between curly double-quotes (IMHO).  If they were
ordinary text being quoted then they would be (should be)
capitalized - "unix", "dos", etc. are written incorrectly
for such a usage.

This bug is not about other curly double-quoted text in the
manual.  It is specific to these terms.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Eli Zaretskii]

> Date: Sun, 13 Sep 2015 14:11:06 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 21472-done@debbugs.gnu.org
> 
> The point of this bug is that those *particular* terms do
> not belong between curly double-quotes (IMHO).

Yes, they do.

> If they were ordinary text being quoted then they would be (should
> be) capitalized - "unix", "dos", etc. are written incorrectly for
> such a usage.

Quoted text in Info manuals ends up with curly quotes when you use
Texinfo 5.x and later.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Drew Adams]

> > The point of this bug is that those *particular* terms do
> > not belong between curly double-quotes (IMHO).
> 
> Yes, they do.

Why?  Why are we quoting "unix" and "dos"?  Why not quote "UNIX"
and "DOS"?  What is the reasoning behind this?  Apparently these
are not literal programming strings - or if they are, it's not
clear how they are used as strings.

> > If they were ordinary text being quoted then they would be (should
> > be) capitalized - "unix", "dos", etc. are written incorrectly for
> > such a usage.
> 
> Quoted text in Info manuals ends up with curly quotes when you use
> Texinfo 5.x and later.

How does that respond to the cited sentence it follows?

Quoted text might end up with curly quotes.  The question is
why these words should be quoted (using ordinary text quotes),
and if they should (no reason given so far) then why they
should be lowercase.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

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

  > Emacs Info manuals have long used double-quotes for two things:

  > * Setting off terms that are defined (e.g., glossary terms).
  >   (This is presumably the case for the occurrence of "codepages"
  >   in this same node.)

Those are English quotation marks.

  > * Programming strings - e.g. Lisp strings (including file-name strings).

We write Lisp strings in Lisp syntax, which includes ASCII doublequote
characters.

  >   Emacs
  >  handles three different conventions for how to separate lines in a file:
  >  newline ("unix"), carriage-return linefeed ("dos"), and just
  >  carriage-return ("mac").

  > Why curly double-quotes here?  Either those quoted names are supposed
  > to be Lisp strings or they are proper names.

I don't think they are Lisp strings.  Those are informal aliases, not
proper names, hence call for English quotation marks.

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

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

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

  > Why?  Why are we quoting "unix" and "dos"?  Why not quote "UNIX"
  > and "DOS"?

We write them in quotes in that passage because we are saying they are
the names of certain things.

Compare:

  Humans' pets are mostly of the effusively friendly kind (the "dog")
  or the aloof kind (the "cat").



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

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Paul Eggert]

Although the manual was correct as it was, it could be written to avoid the need 
for the quotes, and this should help avoid confusion like the problem Drew 
reported.  I went through the Emacs, Elisp, and Elisp intro manuals looking for 
this sort of problem and fixed the ones that I found in commit 
ef7dbdf5873bf0a1f3f0e64e5d019e74d5b15b9e.  The sentence Drew mentioned now looks 
like this:

Emacs handles three different conventions for how to separate lines in a file: 
newline (Unix), carriage-return linefeed (DOS), and just carriage-return (Mac).

which avoids the quoting issue entirely.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Eli Zaretskii]

> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Tue, 15 Sep 2015 08:57:19 -0700
> 
> Although the manual was correct as it was, it could be written to avoid the need 
> for the quotes, and this should help avoid confusion like the problem Drew 
> reported.  I went through the Emacs, Elisp, and Elisp intro manuals looking for 
> this sort of problem and fixed the ones that I found in commit 
> ef7dbdf5873bf0a1f3f0e64e5d019e74d5b15b9e.  The sentence Drew mentioned now looks 
> like this:
> 
> Emacs handles three different conventions for how to separate lines in a file: 
> newline (Unix), carriage-return linefeed (DOS), and just carriage-return (Mac).
> 
> which avoids the quoting issue entirely.

If this means that we should avoid quoting text just because Drew
doesn't like a certain type of quotes, then I object.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Paul Eggert]

Eli Zaretskii wrote:
> If this means that we should avoid quoting text just because Drew
> doesn't like a certain type of quotes

No, it doesn't mean that.  There are still thousands of places in the manual 
that still quote text using `` and '', so the corresponding info files still 
quote “like this” with curved double quotes in thousands of places.  The 
particular place Drew objected to was confusing, though, and it's one of the 
hundreds of places where I toned down the quoting.  The manuals were using 
quotes too often, and this was independent of the issue of what quoting 
characters to use on display.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Eli Zaretskii]

> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Tue, 15 Sep 2015 08:57:19 -0700
> 
> Although the manual was correct as it was, it could be written to avoid the need 
> for the quotes, and this should help avoid confusion like the problem Drew 
> reported.  I went through the Emacs, Elisp, and Elisp intro manuals looking for 
> this sort of problem and fixed the ones that I found in commit 
> ef7dbdf5873bf0a1f3f0e64e5d019e74d5b15b9e.

After looking through these changes, I must say I don't like too many
of them.  Phrases like "foo (or “bar”)" now lost their quotes, which
makes them less correct English-wise, AFAIK.  Even worse, we lost
quotes in phrases like "foo (a.k.a. “bar”).  This sentence:

  On a decentralized version control system, push changes from the
  current branch to another location.

where "push" was quoted, is now reads like incorrect English ("push"
is not a noun here).  Likewise here:

  The external border is normally not shown on fullboth and mazimized
  frames.

Previously, "fullboth", which is not a word, was quoted to indicate
that it's not a real word.

Many places have a quoted text replaced by @dfn, although there's no
terminology here that we describe or index.

Etc., etc. -- I think a large portion of these changes goes too far,
and replaces perfectly correct English with less correct one.

I think most of these changes should be reverted.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Paul Eggert]

Eli Zaretskii wrote:

> This sentence:
>    On a decentralized version control system, push changes from the
>    current branch to another location.
>
> where "push" was quoted, is now reads like incorrect English

Why?  It's idiomatic English to talk about pushing changes in a dVCS.  See, for 
example, 
<http://docs.telerik.com/platform/appbuilder/version-control/third-party-vc/push-changes>, 
which says “You push changes from your local AppBuilder repository to your 
remote Git repository.”

>    The external border is normally not shown on fullboth and mazimized
>    frames.
>
> Previously, "fullboth", which is not a word, was quoted to indicate
> that it's not a real word.

As I understand it the section is intended to define “fullboth” as an invented 
English word, which is fine: the invented word should be defined with @dfn 
(which quotes the word in info files), and other uses of the word should appear 
unquoted just like any other word.  This is standard English style.  The manual 
should not quote every use of a neologism, as scare quotes are not a good style 
for a manual.

That being said, there were problems with the section: it did not use @dfn to 
define “fullboth”, and the paragraph defining “fullboth” was written awkwardly. 
  I just now installed a followup patch to fix that.  I added index entries 
while I was at it.

> Many places have a quoted text replaced by @dfn, although there's no
> terminology here that we describe or index.

Examples?  I put in @dfn when I thought the text was defining a term.

Indexing is a separate axis.  If the text uses a term that should be indexed, 
the index entry should be created regardless of whether the text surrounds a 
term with @dfn or with ``...'' or with nothing at all.  By and large my recent 
large patch worried about quoting, not about indexing.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Drew Adams]

> it could be written to avoid the need for the quotes, and this
> should help avoid confusion like the problem Drew reported.
> I went through the Emacs, Elisp, and Elisp intro manuals looking for
> this sort of problem and fixed the ones that I found in commit
> ef7dbdf5873bf0a1f3f0e64e5d019e74d5b15b9e.  The sentence Drew mentioned now
> looks like this:
> 
> Emacs handles three different conventions for how to separate lines in a
> file: newline (Unix), carriage-return linefeed (DOS), and just carriage-return
> (Mac).
> 
> which avoids the quoting issue entirely.

That fixed sentence looks good to me, FWIW.

I cannot speak to other quoted terms that you might have changed.
I think that those other changes should be handled separately,
not as part of the fix for this bug.  This bug is about these
particular terms: downcased and quoted.

IOW, if you want to consider/discuss what should be done (if
anything) about other quoted occurrences, please don't tie fixing
this bug to that consideration/discussion and possible changes
resulting from that consideration/discussion.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Drew Adams]

> If this means that we should avoid quoting text just because
> Drew doesn't like a certain type of quotes, then I object.

I made it perfectly clear that this bug report has nothing
to do with my preference or lack thereof for any particular
kind of quoting.

For example:

 This is *not* a general problem.  It is not about the use of
         ^^^^^^^^^^^^^^^^^^^^^^^
 curly double-quotes in, for example, the copyright statement
 (e.g.,  "You have the freedom to copy and modify this GNU manual.
 Buying copies from the FSF supports it in developing GNU and
 promoting software freedom.").

 ...
 The point of this bug is that those *particular* terms do
                               ^^^^^^^^^^^^^^^^^^^^^^^^
 not belong between curly double-quotes (IMHO).  If they were
 ordinary text being quoted then they would be (should be)
 capitalized - "unix", "dos", etc. are written incorrectly
 for such a usage.

 This bug is not about other curly double-quoted text in the
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 manual.  It is specific to these terms.
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

and in another message:

  Quoted text might end up with curly quotes.  The question is
  why these words should be quoted (using ordinary text quotes),
  ^^^^^^^^^^^^^^^
  and if they should (no reason given so far) then why they
  should be lowercase.

Yet you continue with your Drew-bashing, based on your spurious
claim.  Why?

Why is quoting appropriate for _this particular text_ at all?
That's the first question posed, in effect, by the bug report.

You could have answered Paul's removal of the quotes by giving
a _reason why_ they are needed _here_, but you chose only to
dump on Drew for reporting the oddball use of quoting here.
Too bad.  What a cop-out - attack the messenger.

What kind of quotes do you think are appropriate for "unix",
"dos", and "mac", none of which are proper names as lowercase?
And why?

What is the point of downcasing and then quoting them?  That's
what the question underlying this bug report.

No answer, so far.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Drew Adams]

> > If this means that we should avoid quoting text just because Drew
> > doesn't like a certain type of quotes
> 
> No, it doesn't mean that.  There are still thousands of places in the
> manual that still quote text using `` and '', so the corresponding info files
> still quote “like this” with curved double quotes in thousands of places.  The
> particular place Drew objected to was confusing, though, and it's one of
> the hundreds of places where I toned down the quoting.  The manuals were using
> quotes too often, and this was independent of the issue of what quoting
> characters to use on display.

And Drew already explicitly corrected the Eli's "misunderstanding"
(and attacks) about this bug report, by making it perfectly clear
that _this_ report is _NOT_ about curly quotes in general and is
only about their particular use _HERE_, for these particular terms.

And part of this bug is the question of why these terms are downcased.
Downcasing them and then quoting them seems wrong to me.  So I asked
why this was done.  Still haven't gotten an answer.  Lots of heat,
but no light, so far.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Drew Adams]

> > Although the manual was correct as it was, it could be written to avoid
> > the need for the quotes, and this should help avoid confusion like the
> > problem Drew reported.  I went through the Emacs, Elisp, and Elisp
> > intro manuals looking for this sort of problem and fixed the ones that
> > I found in commit ef7dbdf5873bf0a1f3f0e64e5d019e74d5b15b9e.
> 
> After looking through these changes, I must say I don't like too many
> of them.  Phrases like "foo (or “bar”)" now lost their quotes, which
> makes them less correct English-wise, AFAIK.  Even worse, we lost
> quotes in phrases like "foo (a.k.a. “bar”).
...
> Etc., etc. -- I think a large portion of these changes goes too far,
> and replaces perfectly correct English with less correct one.
> 
> I think most of these changes should be reverted.

To be clear, and to _repeat_: _THIS_ bug is about the quoting of
_these particular terms_: whether they should be quoted (and why),
and if so, whether (and why) they should be changed to lowercase.

The bug Subject line indicates that I even mistakenly interpreted
these terms as intended to be Lisp strings, so much was it unclear
to me what these quotations are all about.  These are not the
usual terms ("UNIX", "DOS", and "Mac").

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Drew Adams]

> > This sentence:
> >    On a decentralized version control system, push changes from the
> >    current branch to another location.
> >
> > where "push" was quoted, is now reads like incorrect English
> 
> Why?  It's idiomatic English to talk about pushing changes in a dVCS.
> See, for example,
> <http://docs.telerik.com/platform/appbuilder/version-control/third-party-
> vc/push-changes>,
> which says “You push changes from your local AppBuilder repository to your
> remote Git repository.”
> 
> >    The external border is normally not shown on fullboth and mazimized
> >    frames.
> >
> > Previously, "fullboth", which is not a word, was quoted to indicate
> > that it's not a real word.
> 
> As I understand it the section is intended to define “fullboth” as an
> invented English word, which is fine: the invented word should be defined
> with @dfn (which quotes the word in info files), and other uses of the
> word should appear unquoted just like any other word.  This is standard
> English style.  The manual should not quote every use of a neologism,
> as scare quotes are not a good style for a manual.
> 
> That being said, there were problems with the section: it did not use @dfn
> to define “fullboth”, and the paragraph defining “fullboth” was written
> awkwardly.
>   I just now installed a followup patch to fix that.  I added index
> entries while I was at it.
> 
> > Many places have a quoted text replaced by @dfn, although there's no
> > terminology here that we describe or index.
> 
> Examples?  I put in @dfn when I thought the text was defining a term.
> 
> Indexing is a separate axis.  If the text uses a term that should be
> indexed, the index entry should be created regardless of whether the
> text surrounds a term with @dfn or with ``...'' or with nothing at all.
> By and large my recent large patch worried about quoting, not about indexing.

I do not object if people want to discuss other occurrences of quoted
terms in the context of this bug thread, _provided_ this bug gets
addressed as reported: it is only about _these particular quoted terms_.

IOW, let us please not lose sight of _THIS_ bug in some larger
consideration of other quoted terms and phrases (which I did not
initiate, and in which I have not participated).

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Eli Zaretskii]

> Cc: 21472@debbugs.gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Tue, 15 Sep 2015 12:15:25 -0700
> 
> Eli Zaretskii wrote:
> 
> > This sentence:
> >    On a decentralized version control system, push changes from the
> >    current branch to another location.
> >
> > where "push" was quoted, is now reads like incorrect English
> 
> Why?  It's idiomatic English to talk about pushing changes in a
> dVCS.

I'm not going to argue.  The results of these changes look worse to
me.  Where previously there was good English, we now have
techno-babble and borderline (a.k.a. "idiomatic") English.  It's a
shame we needed to make these changes.


Wrong analogy: here "push" is a literal verb, whereas in the sentence
I quoted "push" is a name of an operation, and "changes" is the verb.

> > Many places have a quoted text replaced by @dfn, although there's no
> > terminology here that we describe or index.
> 
> Examples?  I put in @dfn when I thought the text was defining a term.

Almost all of those are wrong, IMO, as they don't define any
terminology the manual explains or describes.

> Indexing is a separate axis

No, it's not: if you claim something is a term, you need to index it.
We index all terminology introduced in a manual, as a matter of
principle.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Eli Zaretskii]

> Date: Tue, 15 Sep 2015 16:48:07 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> > Emacs handles three different conventions for how to separate lines in a
> > file: newline (Unix), carriage-return linefeed (DOS), and just carriage-return
> > (Mac).
> > 
> > which avoids the quoting issue entirely.
> 
> That fixed sentence looks good to me, FWIW.

It doesn't look good to me.  "Unix" is not used here in a literal
sense, it stands for all Unix-like systems (a.k.a. "Posix"), including
GNU/Linux.  Likewise, "DOS" stands for MS-DOS, MS-Windows, and similar
systems.

Removing the quotes here changed the meaning.

That's also the problem with many other changes Paul made: where
previously a quoted "FOO" frequently meant "like FOO, but not really
FOO", now we have just the literal FOO, and the reader is none the
wiser.

Shame on us for failing to write good expressive English for fear of
quotes.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Eli Zaretskii]

> Date: Wed, 16 Sep 2015 09:56:07 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: 21472@debbugs.gnu.org
> 
> Wrong analogy: here "push" is a literal verb, whereas in the sentence
> I quoted "push" is a name of an operation, and "changes" is the verb.

Please disregard this single paragraph: it was mistakenly left in the
message and not deleted.

All the rest is valid.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Paul Eggert]

Eli Zaretskii wrote:

> We index all terminology introduced in a manual, as a matter of
> principle.

That's news to me, and the manuals often don't index terminology within @dfn. 
For example, doc/emacs/basic.texi says @dfn{minor modes} but does not index the 
term.  A quick eyeball of that file suggests that only about half of its terms 
enclosed in @dfn are indexed.  I'm not opposed to having more index entries for 
@dfns if someone wants to do it, but it doesn't appear to be a hard rule.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Paul Eggert]

Eli Zaretskii wrote:
> Shame on us for failing to write good expressive English for fear of
> quotes.

I didn't remove those quotes due to fear.  I removed them because they made the 
manual harder to read.  Quotes are important to get right in English, and part 
of getting it right is to avoid overusing them.

To be fair, the unnecessary quotes in the manual weren't as bad as these:

http://www.unnecessaryquotes.com/

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Eli Zaretskii]

> Cc: 21472@debbugs.gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Wed, 16 Sep 2015 00:48:51 -0700
> 
> Eli Zaretskii wrote:
> 
> > We index all terminology introduced in a manual, as a matter of
> > principle.
> 
> That's news to me, and the manuals often don't index terminology within @dfn. 
> For example, doc/emacs/basic.texi says @dfn{minor modes} but does not index the 
> term.  A quick eyeball of that file suggests that only about half of its terms 
> enclosed in @dfn are indexed.  I'm not opposed to having more index entries for 
> @dfns if someone wants to do it, but it doesn't appear to be a hard rule.

Many rules of good documentation are followed only partially.  That
doesn't make them any lesser.

This rule should be obvious: if you introduce and explain some
terminology, you should always consider the possibility that someone
will want to read about that terminology, and so it should be in the
index.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Eli Zaretskii]

> Cc: 21472-done@debbugs.gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Wed, 16 Sep 2015 00:49:13 -0700
> 
> Eli Zaretskii wrote:
> > Shame on us for failing to write good expressive English for fear of
> > quotes.
> 
> I didn't remove those quotes due to fear.  I removed them because they made the 
> manual harder to read.  Quotes are important to get right in English, and part 
> of getting it right is to avoid overusing them.

The problem is, you removed too many of them.

For example, any use of "magic" where no real magic (as in Gandalf
coming in and performing it) should be quoted, because the literal
meaning is too far-fetched.  Likewise in other similar situations,
like with "future history".  Likewise when using words that are not
correct English (flagged by spell-checker), such as "fullboth".

I attempted to fix the worst offenders I found in commit 31ff037.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Drew Adams]

> It doesn't look good to me.  "Unix" is not used here in a literal
> sense, it stands for all Unix-like systems (a.k.a. "Posix"), including
> GNU/Linux.  Likewise, "DOS" stands for MS-DOS, MS-Windows, and similar
> systems.

So you say, but does the text say that?  How does a reader get
that from the manual?  Just please put that _in words_, and forget
the problematic use of lowercase and quotation marks here.  IOW,
say what you really mean.

> Removing the quotes here changed the meaning.

What meaning?  There was no meaning given.  No guessing would
lead a reader to understand what you've now written as an
explanation of what you meant the text to say.

> That's also the problem with many other changes Paul made: where
> previously a quoted "FOO" frequently meant "like FOO, but not really
> FOO", now we have just the literal FOO, and the reader is none the
> wiser.
> 
> Shame on us for failing to write good expressive English for fear of
> quotes.

Couldn't agree more with the first part.  Throwing some quotes
around bits of text without care typically hurts instead of helps.

Let us "write good expressive English", by all means.  Just say
what you mean the text to say, instead of hoping that readers will
guess your meaning because of some quote marks.

FWIW, I agree with you wrt your remarks about indexing and using
quote marks to indicate "so-called".  My remarks here, and this
entire bug report, have to do only with the particular quoted
terms that this report calls out.

There might be other such in the manual, but if so they should
be handled outside this bug report and judged case by case, just
like those reported here.

(Use of quote marks to mean "so-called" or "not literally":
http://www.grammar-monster.com/lessons/quotation_(speech)_marks_meaning_alleged_so-called.htm)

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Paul Eggert]

Eli Zaretskii wrote:
> For example, any use of "magic" where no real magic (as in Gandalf
> coming in and performing it) should be quoted, because the literal
> meaning is too far-fetched.  Likewise in other similar situations,

I'll give you “magic” as that is a gray area, where it's no big deal either way, 
but there are many other quotes that are clearly unnecessary, e.g.:

   Some mice have a ``wheel''

   The @dfn{clipboard} is the facility that most graphical applications use for 
``cutting and pasting''.

   If you exit Emacs while it is the current ``owner'' of the clipboard data,

   the @var{predicate} should return non-@code{nil} if the first element is 
``less'' than the second, or @code{nil} if not.

Quotes like these are a disservice to the reader: the reader must slow down and 
process them and think “why is this phrase being quoted?” and the answer to that 
question is not worth the cost of the mental processing.  There is no need to 
quote the word “push” merely because it is used as a noun!

Anyway, clearly you prefer manuals that are way overquoted compared to standard 
English style.  To me, and I think to most people, this gives the manuals a 
overly “fussy” look.  (Apparently I need to quote “fussy” as the manuals are not 
actually fussing. :-)  But I’m not going to “fight” over it.  (The quotes are 
because it wouldn’t be an actual fight with actual fisticuffs. :-)

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Eli Zaretskii]

> Cc: drew.adams@oracle.com, 21472@debbugs.gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Wed, 16 Sep 2015 08:31:00 -0700
> 
> Eli Zaretskii wrote:
> > For example, any use of "magic" where no real magic (as in Gandalf
> > coming in and performing it) should be quoted, because the literal
> > meaning is too far-fetched.  Likewise in other similar situations,
> 
> I'll give you “magic” as that is a gray area, where it's no big deal either way, 
> but there are many other quotes that are clearly unnecessary, e.g.:
> 
>    Some mice have a ``wheel''

It's not a wheel, it's a button whose shape is round and which can be
rotated as well as pressed.  Wheels are what cars and bicycles have.

>    The @dfn{clipboard} is the facility that most graphical applications use for 
> ``cutting and pasting''.

We've always used "cut and paste" in quotes in Emacs, as it's not our
terminology.

>    If you exit Emacs while it is the current ``owner'' of the clipboard data,

Emacs doesn't own anything here: clipboard data is not some real
estate or money.

>    the @var{predicate} should return non-@code{nil} if the first element is 
> ``less'' than the second, or @code{nil} if not.

"Less" here is in the eyes of the beholder; arbitrary objects do not
have intrinsic order or comparison operators.  It's our invention.

> Quotes like these are a disservice to the reader: the reader must slow down and 
> process them and think “why is this phrase being quoted?” and the answer to that 
> question is not worth the cost of the mental processing.

On the contrary, these quotes are most natural, and no such questions
will ever pop up in anyone's mind.

> There is no need to quote the word “push” merely because it is used
> as a noun!

Of course, there is: you don't really "push" anything.  "Push" here is
jargon for copying DAG portions from one location to another.  A
chapter whose subject is VCS should know better.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Paul Eggert]

On 09/16/2015 10:18 AM, Eli Zaretskii wrote:
> "Push" here is
> jargon

It would be ridiculous to quote every use of a technical term in the 
manual.  It's fine to quote the defining occurrence (prefably with 
@dfn), but other uses of technical terms should appear unquoted. This is 
standard English style and it's what Emacs manuals should use.  The 
defenses you gave for the quotes in the examples are weak; those quotes 
are unnecessary distractions to the reader, and their costs outweigh 
their benefits.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Eli Zaretskii]

> Cc: drew.adams@oracle.com, 21472@debbugs.gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Wed, 16 Sep 2015 11:27:14 -0700
> 
> On 09/16/2015 10:18 AM, Eli Zaretskii wrote:
> > "Push" here is
> > jargon
> 
> It would be ridiculous to quote every use of a technical term in the 
> manual.

That's not what I suggested, or did.  I left most of your unquoting in
place, and only changed those that were too annoying.

> It's fine to quote the defining occurrence (prefably with 
> @dfn), but other uses of technical terms should appear unquoted. This is 
> standard English style and it's what Emacs manuals should use.

And that's what we do.  But "push", "wheel", etc. aren't technical
terms, they are jargon that crept into the language in some quarters.
For them, a different rule and a separate judgment call is only
prudent.

> The defenses you gave for the quotes in the examples are weak; those
> quotes are unnecessary distractions to the reader, and their costs
> outweigh their benefits.

I guess we will have to agree to disagree on that.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Paul Eggert]

On 09/16/2015 11:34 AM, Eli Zaretskii wrote:
> "push", "wheel", etc. aren't technical terms,

Sure they are.  And they're commonly used that way nowadays, e.g.:

https://github.com/jquery/jquery-mousewheel
https://lists.gnu.org/archive/html/emacs-diffs/2013-10/msg00185.html
http://git-scm.com/docs/git-push
https://lists.gnu.org/archive/html/emacs-devel/2014-11/msg01746.html

Omitting unnecessary quotes would help improve on the stuffy and dated 
feel that the Emacs manuals too often have.  A part of this stuffiness 
comes from quoting terms that may have been newfangled decades ago but 
are in common use now.  Repeatedly quoting now-common terms like "push", 
"mouse wheel", "cut", "copy", and "minimize" makes the manuals look like 
they were written decades ago and haven't been properly updated since.  
(Look, Ma!  I can "cut" from this window and "paste" into this other one 
with my "mouse wheel"! :-)

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Eli Zaretskii]

> Cc: drew.adams@oracle.com, 21472@debbugs.gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Wed, 16 Sep 2015 13:31:28 -0700
> 
> On 09/16/2015 11:34 AM, Eli Zaretskii wrote:
> > "push", "wheel", etc. aren't technical terms,
> 
> Sure they are.  And they're commonly used that way nowadays, e.g.:
> 
> https://github.com/jquery/jquery-mousewheel
> https://lists.gnu.org/archive/html/emacs-diffs/2013-10/msg00185.html
> http://git-scm.com/docs/git-push
> https://lists.gnu.org/archive/html/emacs-devel/2014-11/msg01746.html

Yes, techno-babble is common.  It doesn't yet make it right.

> Omitting unnecessary quotes would help improve on the stuffy and dated 
> feel that the Emacs manuals too often have.

There's nothing stuffy or dated in using quotes where appropriate.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Paul Eggert]

Eli Zaretskii wrote:
>> >https://github.com/jquery/jquery-mousewheel
>> >https://lists.gnu.org/archive/html/emacs-diffs/2013-10/msg00185.html
>> >http://git-scm.com/docs/git-push
>> >https://lists.gnu.org/archive/html/emacs-devel/2014-11/msg01746.html
> Yes, techno-babble is common.  It doesn't yet make it right.

Did you read all those URLs?  It doesn't seem so.  You might recognize a 
prominent contributor to Emacs in some of them.... :-)

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Eli Zaretskii]

> Cc: drew.adams@oracle.com, 21472@debbugs.gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Wed, 16 Sep 2015 22:21:11 -0700
> 
> Eli Zaretskii wrote:
> >> >https://github.com/jquery/jquery-mousewheel
> >> >https://lists.gnu.org/archive/html/emacs-diffs/2013-10/msg00185.html
> >> >http://git-scm.com/docs/git-push
> >> >https://lists.gnu.org/archive/html/emacs-devel/2014-11/msg01746.html
> > Yes, techno-babble is common.  It doesn't yet make it right.
> 
> Did you read all those URLs?  It doesn't seem so.  You might recognize a 
> prominent contributor to Emacs in some of them.... :-)

I don't have to read them, since none of them are relevant to user
manuals.  Yes, I, too, use the jargon in free speech, but manuals are
different: their language should be cleaner and more thought-out.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Paul Eggert]

Eli Zaretskii wrote:
> manuals ...  language should be cleaner and more thought-out.

Right, but littering a manual with unnecessary quotation marks is not cleaner: 
on the contrary, it is messy and distracting.  Clear and simple explanation 
should trump pedanticism.  The bug report that started this thread stemmed from 
confusion induced by unnecessary quotes, and many of the quotes you recently 
reintroduced are just as unnecessary and could easily cause similar confusion.

bug#21472: 25.0.50; REGRESSION: (emacs) `Coding Systems' uses curly quotes for Lisp strings

[Eli Zaretskii]

> Cc: drew.adams@oracle.com, 21472@debbugs.gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Thu, 17 Sep 2015 00:21:08 -0700
> 
> Eli Zaretskii wrote:
> > manuals ...  language should be cleaner and more thought-out.
> 
> Right, but littering a manual with unnecessary quotation marks is not cleaner: 
> on the contrary, it is messy and distracting.  Clear and simple explanation 
> should trump pedanticism.

We agree on the principles, but disagree about (some of) the concrete
uses of the quotes.  So reiterating the principles is not useful.

> The bug report that started this thread stemmed from confusion
> induced by unnecessary quotes, and many of the quotes you recently
> reintroduced are just as unnecessary and could easily cause similar
> confusion.

As I said, we disagree.  I thought many of the quotes you removed
should not have been removed.  That includes some of the removals I
left alone, because they are really borderline IMO.