Please stop putting curly quotes into doc strings!

Please stop putting curly quotes into doc 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. ]]]

Please stop inserting curly quotes into doc strings in Emacs 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.

Re: Please stop putting curly quotes into doc strings!

[Dmitry Gutov]

On 09/05/2015 04:14 AM, Richard Stallman wrote:

> Please stop inserting curly quotes into doc strings in Emacs sources.

I would also ask to remove the ones already inserted.

And make substitute-command-keys, format-message, etc (any other 
functions which deal with quoting now) *not* translate the curly quotes 
in their inputs, nor highlight symbols surrounded with curly quotes in 
docstring sources. In order to reduce the temptation to re-introduce 
them, accidentally or on purpose.

Re: Please stop putting curly quotes into doc strings!

[Paul Eggert]

Richard Stallman wrote:
> Please stop inserting curly quotes into doc strings in Emacs sources.

Since August 25 I by and large stopped inserting curved quotes there, though I 
did make an exception more recently for “Bahá’í”.  We have enough curved quotes 
there to try them out; we don’t need to change those quotes systematically to be 
curved quotes.

Re: Please stop putting curly quotes into doc 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. ]]]

  > > Please stop inserting curly quotes into doc strings in Emacs sources.

  > I would also ask to remove the ones already inserted.

Those that represent symbol quotations in doc strings should be removed.

For the rest, I don't know why they are used.  Perhaps there is a good
reason for some specific 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.

Re: Please stop putting curly quotes into doc 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. ]]]

  > Since August 25 I by and large stopped inserting curved quotes there, though I 
  > did make an exception more recently for “Bahá’í”.

That might be one of the special places where it is proper to have
a curly quote in the Emacs sources: as part of a name.

But I expect that most of the occurrences are mistakes.

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

Re: Please stop putting curly quotes into doc strings!

[Paul Eggert]

Richard Stallman wrote:
> Those that represent symbol quotations in doc strings should be removed.

They work fine just as they are, and in some ways they work better than the 
straight quotes do.  Users can see them as straight quotes if they like.  There 
is not a strong argument for removing them.

RE: Please stop putting curly quotes into doc strings!

[Drew Adams]

> > Those that represent symbol quotations in doc strings should be removed.
> 
> They work fine just as they are, and in some ways they work better than the
> straight quotes do.  Users can see them as straight quotes if they like.
>
> There is not a strong argument for removing them.

No strong argument was ever given for adding them.

There was never _any_ argument given for adding them, beyond
your complaint that you find `...' ugly.

You've turned Emacs upside down and inside out, to make it do
what you want.  Users and Emacs Dev will be dealing with the
aftermath for a long time to come.  Alas, no one stopped you
in your crusade, so here we are.

Re: Please stop putting curly quotes into doc strings!

[Dmitry Gutov]

On 09/06/2015 07:48 AM, Paul Eggert wrote:

> There is not a strong argument for removing them.

You've been given plenty of those already.

Re: Please stop putting curly quotes into doc strings!

[Zack Piper]

On Sat, Sep 05, 2015 at 10:05:43PM -0700, Drew Adams wrote:
> > > Those that represent symbol quotations in doc strings should be removed.
> > 
> > They work fine just as they are, and in some ways they work better than the
> > straight quotes do.  Users can see them as straight quotes if they like.
> >
> > There is not a strong argument for removing them.
> 
> No strong argument was ever given for adding them.
> 
> There was never _any_ argument given for adding them, beyond
> your complaint that you find `...' ugly.
> 
> You've turned Emacs upside down and inside out, to make it do
> what you want.  Users and Emacs Dev will be dealing with the
> aftermath for a long time to come.  Alas, no one stopped you
> in your crusade, so here we are.
> 

As I agree that we didn't really need to change quotes at all (and I
prefer the "old style" quotes) I don't think that level of hostility
was really needed.

However, I am now curious if there is other examples of "Emacs being
turned upside down and inside out" that Paul has participated in.

-- 
Zack Piper <zack@apertron.net> http://apertron.net

Re: Please stop putting curly quotes into doc strings!

[Zack Piper]

> "old style"

This I find slightly ironic of me...

-- 
Zack Piper <zack@apertron.net> http://apertron.net

Re: Please stop putting curly quotes into doc strings!

[raman]

There is indeed a strong argument for removing /undoing this mess and it
has been made multiple times.  Saying it's there already and it's not a
problem equates to declaring a feta  complis  that doesn't feel right in
a project that affects and benefits so many; worse it feels like it is
just being laid aside to return another day and bite us all even harder
in the leg.
-- 

Re: Please stop putting curly quotes into doc strings!

[Kaushal Modi]

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

If this counts, I am also against these mass changes just because the
original quote styles looked "ugly". I prefer the original quotes to the
curly quotes.
On Sep 6, 2015 1:40 PM, "raman" <raman@google.com> wrote:

> There is indeed a strong argument for removing /undoing this mess and it
> has been made multiple times.  Saying it's there already and it's not a
> problem equates to declaring a feta  complis  that doesn't feel right in
> a project that affects and benefits so many; worse it feels like it is
> just being laid aside to return another day and bite us all even harder
> in the leg.
> --
>
>

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

Re: Please stop putting curly quotes into doc 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. ]]]

It was not right to put curly quotes in the doc strings.
Please undo that change.

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

Re: Please stop putting curly quotes into doc strings!

[Paul Eggert]

Richard Stallman wrote:
> It was not right to put curly quotes in the doc strings.
> Please undo that change.

The curved quotes eased Emacs maintainence for me, but judging from recent 
remarks on the mailing list I'm in the minority in preferring that style so I 
just now undid almost all that change in the master branch.  I kept a few curved 
quotes, e.g., in “Bahá’í”, which I hope do not ruffle too many feathers.

Re: Please stop putting curly quotes into doc 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. ]]]

  > The curved quotes eased Emacs maintainence for me, but judging from recent 
  > remarks on the mailing list I'm in the minority in preferring that style so I 
  > just now undid almost all that change in the master branch.

Thank you.

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

Re: Please stop putting curly quotes into doc strings!

[Dmitry Gutov]

Hi Paul,

On 09/08/2015 02:17 AM, Paul Eggert wrote:

> The curved quotes eased Emacs maintainence for me, but judging from
> recent remarks on the mailing list I'm in the minority in preferring
> that style so I just now undid almost all that change in the master
> branch.

Thank you very much.

> I kept a few curved quotes, e.g., in “Bahá’í”, which I hope do
> not ruffle too many feathers.

It's entirely correct, as far as I'm concerned. When used as plain text, 
not markup.

You still kept translations from curly quotes in substitute-command-keys 
and format-message. Is that on purpose?

Re: Please stop putting curly quotes into doc strings!

[Paul Eggert]

Dmitry Gutov wrote:
> You still kept translations from curly quotes in substitute-command-keys and
> format-message. Is that on purpose?

Yes, as well as support for highlighting their contents in docstrings, etc. 
Even if curved quotes are not used in Emacs source code itself, they are still a 
perfectly good style for users like me who prefer them in their own code.

Re: Please stop putting curly quotes into doc strings!

[raman]

Thanks from my side as well -- 
-- 

Re: Please stop putting curly quotes into doc strings!

[raman]

The negative with that is that we'll have inconsistency between say Core
Emacs libraries and code from Elpa. Eventually this entire thread will
be forgotten  or be entirely unknown to another elisp programmer who
ends up cut/pasting from other elpa code.  I think for the long-term
health of emacs, this is a situation that is best avoided.

The needs of developers who view Ascii quotes as ugly and want to see
something else can be easily served by an elpa package that uses all the
tricks you have proposed in reverse on this thread, eg display-table
hacks, shadow glyphs and other alternatives -- it has the advantage of
keeping the codebase clean. In some sense, that is not very  different
from having an addon package display #'(lambda as #'(λ
-- 

RE: Please stop putting curly quotes into doc strings!

[Drew Adams]

> The needs of developers who view Ascii quotes as ugly and want to see
> something else can be easily served by an elpa package that uses all the
> tricks you have proposed in reverse on this thread, eg display-table
> hacks, shadow glyphs and other alternatives -- it has the advantage of
> keeping the codebase clean. In some sense, that is not very  different
> from having an addon package display #'(lambda as #'(λ

Hear, hear!  Switch cart & horse.

Them what needs this byutiful! new suit of clothes can load
a library that puts it on.  Dandy-up on your own, please.

Re: Please stop putting curly quotes into doc strings!

[Dmitry Gutov]

On 09/08/2015 07:20 PM, raman wrote:
> The negative with that is that we'll have inconsistency between say Core
> Emacs libraries and code from Elpa.

Exactly.

Paul, maybe you can extract the set of pairs to be translated (or 
highlighted) to a defvar (not defcustom). By default it will be set to 
((?` . ?')), but you would be able to add any kinds of pairs.

> The needs of developers who view Ascii quotes as ugly and want to see
> something else can be easily served by an elpa package that uses all the
> tricks you have proposed in reverse on this thread,

Unfortunately, I don't see an easy way to write an ELPA package that 
would do that, barring some new changes, like the one mentioned above.

The translation code is written in a non-extensible way, and there's 
nothing that, say, some new font-lock rules can reuse.

Re: Please stop putting curly quotes into doc strings!

[Paul Eggert]

Dmitry Gutov wrote:
> maybe you can extract the set of pairs to be translated (or highlighted) to a
> defvar (not defcustom).

That would be some work; it is not just creating a defvar, it is making sure it 
is used consistently everywhere (e.g., arbitrary chars would need quoting in the 
appropriate regular expressions).  If there is a demonstrated need for it then 
it could be added as part of the code to satisfy that need.  It does not sound 
urgent.

Re: Please stop putting curly quotes into doc strings!

[raman]

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

Definitely is not urgent for many of us on this thread. What is urgent though is that the remaining artifacts from the failed magic quotes be removed which is what we are all asking for -- let's do that -- and move on.> Dmitry Gutov wrote:
>> maybe you can extract the set of pairs to be translated (or highlighted) to a
>> defvar (not defcustom).
>
> That would be some work; it is not just creating a defvar, it is
> making sure it is used consistently everywhere (e.g., arbitrary chars
> would need quoting in the appropriate regular expressions).  If there
> is a demonstrated need for it then it could be added as part of the
> code to satisfy that need.  It does not sound urgent.
>

-- 

Re: Please stop putting curly quotes into doc strings!

[Stefan Monnier]

> Definitely is not urgent for many of us on this thread. What is urgent
> though is that the remaining artifacts from the failed magic quotes be
> removed which is what we are all asking for -- let's do that -- and move
> on.

FWIW, I don't know what those "remaining artifacts" would be.
We still want to see curly quotes in C-h f by default, so it's not like
we want to undo everything that Paul did.

And I think which parts each person thinks should be removed/kept (or
even added) is not nearly as obvious as one may think.  So if you still
want something changed, please be specific.


        Stefan

Re: Please stop putting curly quotes into doc strings!

[T.V Raman]

The only thing I'm asking for is that curly quotes in files  where
they exist be removed so  the codebase goes back to a pristine state.

Stefan Monnier writes:
 > > Definitely is not urgent for many of us on this thread. What is urgent
 > > though is that the remaining artifacts from the failed magic quotes be
 > > removed which is what we are all asking for -- let's do that -- and move
 > > on.
 > 
 > FWIW, I don't know what those "remaining artifacts" would be.
 > We still want to see curly quotes in C-h f by default, so it's not like
 > we want to undo everything that Paul did.
 > 
 > And I think which parts each person thinks should be removed/kept (or
 > even added) is not nearly as obvious as one may think.  So if you still
 > want something changed, please be specific.
 > 
 > 
 >         Stefan

-- 

-- 

Re: Please stop putting curly quotes into doc strings!

[Paul Eggert]

On 09/09/2015 12:55 PM, T.V Raman wrote:
> The only thing I'm asking for is that curly quotes in files  where
> they exist be removed so  the codebase goes back to a pristine state.

That is too strong.  Although I already removed almost all the curved 
quotes I introduced into doc strings, there were a few justifiable 
exceptions.  For example, when the code is about curved quotes 
themselves it is fine for its documentation strings to use curved 
quotes.  Here's the doc string for text-quoting-style:

   Style to use for single quotes when generating text.
   `curve' means quote with curved single quotes \\=‘like this\\=’.
   `straight' means quote with straight apostrophes \\='like this\\='.
   `grave' means quote with grave accent and apostrophe \\=`like this\\='.
   The default value nil acts like `curve' if curved single quotes are
   displayable, and like `grave' otherwise.

The two curved quotes in this docstring are good, because they show the 
user what curved quotes look like.

Re: Please stop putting curly quotes into doc strings!

[Stefan Monnier]

> The only thing I'm asking for is that curly quotes in files  where
> they exist be removed so  the codebase goes back to a pristine state.

I think this is already done,


        Stefan

Re: Please stop putting curly quotes into doc strings!

[David Kastrup]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> The only thing I'm asking for is that curly quotes in files  where
>> they exist be removed so  the codebase goes back to a pristine state.
>
> I think this is already done,

git grep ‘

disagrees.  While the bulk of occurences may be either programmatic or
descriptive, there is a fair share of format strings, manual contents
(not sure whether that transfers well to all Texinfo backends,
particularly PDF), change log entries, comments, dunnet (?!) and others.

I have not looked further into this and it's quite likely that a number
of those have been done at various points of time rather than being part
of the recent large systematic changes.  At any rate, for people feeling
strongly about the issue, there is still opportunity for improving the
consistency of the code base.

-- 
David Kastrup

Re: Please stop putting curly quotes into doc strings!

[Stefan Monnier]

> git grep ‘

I don't see anything serious in this output.  Again, if there's
a problem somewhere, make a specific request.  We don't have a general
rule against arbitrary character code appearing in our code base.


        Stefan

Re: Please stop putting curly quotes into doc strings!

[David Kastrup]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> git grep ‘
>
> I don't see anything serious in this output.  Again, if there's
> a problem somewhere, make a specific request.  We don't have a general
> rule against arbitrary character code appearing in our code base.

Well, various text files like
etc/NEWS:nil for Emacs local time, t for Universal Time, \u2018wall\u2019 for system wall
etc/NEWS:clock time, or a string as in \u2018set-time-zone-rule\u2019 for a time zone
etc/NEWS:rule.  The affected functions are \u2018current-time-string\u2019,
etc/NEWS:\u2018current-time-zone\u2019, \u2018decode-time\u2019, and \u2018format-time-string\u2019.  The
etc/NEWS:function \u2018encode-time\u2019, which already accepted a simple time zone rule
etc/PROBLEMS:  No fonts match \u2018-*-fixed-medium-r-*--6-*-*-*-*-*-iso8859-1\u2019

Comments and messages like
lisp/cedet/mode-local.el:;; \u2018require\u2019 by (defvar find-function-regexp-alist) and
lisp/cedet/mode-local.el:  "For \u2018elisp-xref-find-def-functions\u2019; add overloads for SYMBOL."
lisp/cedet/mode-local.el:      ;; don't want to list the same function twice. So order \u2018modes\u2019
lisp/cedet/mode-local.el:  "Regexp used by \u2018xref-find-definitions\u2019 when searching for a
lisp/cedet/mode-local.el:  "Function used by \u2018xref-find-definitions\u2019 when searching for an

outcommented stuff that would become non-standard when commented back
in:
lisp/emacs-lisp/advice.el:;;          (y-or-n-p (format "\u2018%s\u2019 does not exist, create? " (ad-get-arg 0))))
lisp/emacs-lisp/bytecomp.el:      ;; (message "%s not compiled because of \u2018no-byte-compile: %s\u2019"
lisp/emacs-lisp/bytecomp.el:                      ;;   "\u2018%s\u2019 is not a known condition name
lisp/emacs-lisp/bytecomp.el:          ;;   "\u2018%s\u2019 is not a known condition name (in condition-case)"

various messages like
lisp/info.el:              (format "*Index for \u2018%s\u2019*::" (cdr (nth 0 nodeinfo)))
lisp/info.el:                    (format "*Index for \u2018%s\u2019*" topic))))
lisp/info.el:   (insert "This is a list of search results produced by \u2018info-apropos\u2019.\n\n")
lisp/info.el:   (insert "Index entries that match \u2018" (nth 1 nodeinfo) "\u2019:\n\n")
lisp/info.el:   (setq nodename (format "Index for \u2018%s\u2019" string))
lisp/info.el:     "The following packages match the keyword \u2018" nodename "\u2019:\n\n")
lisp/info.el:     "Description of the package \u2018" nodename "\u2019:\n\n")

The English adventure "dunnet"
lisp/play/dunnet.el:  open it.  You may just use \u2018in\u2019 or walk in the direction of the door.
lisp/play/dunnet.el:- You can save your game with the \u2018save\u2019 command, and use restore it
lisp/play/dunnet.el:  with the \u2018restore\u2019 command.
lisp/play/dunnet.el:      (dun-mprincl "No more questions, just do \u2018answer foo\u2019.")
lisp/play/dunnet.el:says: This VAX is named \u2018pokey\u2019.  To type on the console, use the
lisp/play/dunnet.el:\u2018type\u2019 command.  The exit is to the east."
lisp/play/dunnet.el:is a sign on the wall that reads: \u2018receiving room\u2019."
lisp/play/dunnet.el:that says \u2018put treasures here for points\u2019."
lisp/play/dunnet.el:switch on the wall labeled \u2018BL\u2019.  There are doors to the west and north."
lisp/play/dunnet.el:history.  On the blackboard is written, \u2018No children allowed downstairs.\u2019
lisp/play/dunnet.el:There is a door to the east with an \u2018exit\u2019 sign on it.  There is another
lisp/play/dunnet.el:does have a sign that says: This machine's name is \u2018endgame\u2019.  The
lisp/play/dunnet.el:order to get by.  Use the \u2018answer\u2019 command to answer the question."
lisp/play/dunnet.el:          Type the \u2018reset\u2019 command to type on the PC.
lisp/play/dunnet.el:"The paper says: Don't forget to type \u2018help\u2019 for help.  Also, remember
lisp/play/dunnet.el:this word: \u2018worms\u2019"
lisp/play/dunnet.el:written: \u2018For key upgrade, put key in here.\u2019"
lisp/play/dunnet.el:"It says \u2018express mail\u2019 on it."
lisp/play/dunnet.el:"It is a 35 passenger bus with the company name \u2018mobytours\u2019 on it."

and a few others.  You stated that you considered the source to be in
"pristine state" without curly quotes and I said that this was not quite
accurate.  Now you try to make it about how "serious" this is supposed
to be, conveniently eliding the whole preceding context not supporting
this subject.  I don't think I know any other mailing list where this
sort of quoting game is as popular as on the Emacs developer list.
Appears to be some culture thing but it's definitely annoying, not least
of all because it leads to the same points being made over and over and
promotes exasperation as a main decision-finding process.

-- 
David Kastrup

Re: Please stop putting curly quotes into doc strings!

[Paul Eggert]

On 09/10/2015 08:46 AM, David Kastrup wrote:

 > outcommented stuff that would become non-standard when commented back

Thanks, I missed those, since I didn’t look at comments.  Fixed.

 > Comments and messages like

Thanks, I missed those message instances, as somebody else introduced 
those curved quotes and I looked only at the curved quotes I 
introduced.  I changed them to use grave quotes just now.

It’s OK to use curved quotes in English text in comments.

 > Well, various text files

It’s OK for English text in text files to use curved quotes.  In 
etc/PROBLEMS, the text is showing an Emacs diagnostic as presented to 
the user.  This normally uses curved quotes nowadays, so curved quotes 
are preferable there.  The other curved quotes you mention also look OK.

 > various messages like

Those messages generate info files, which typically use curved quotes 
nowadays, so curved quotes are appropriate there.

 > The English adventure "dunnet"

Please feel free to go through dunnet and change it to use 
substitute-command-keys or format-message so that it generates grave 
quotes for dunnet users who prefer that style.  I did not think it worth 
bothering about, myself.

Re: Please stop putting curly quotes into doc strings!

[David Kastrup]

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

> On 09/10/2015 08:46 AM, David Kastrup wrote:
>
>> outcommented stuff that would become non-standard when commented back
>
> Thanks, I missed those, since I didn’t look at comments.  Fixed.
>
>> Comments and messages like
>
> Thanks, I missed those message instances, as somebody else introduced
> those curved quotes and I looked only at the curved quotes I
> introduced.  I changed them to use grave quotes just now.

Thanks for the cleanup.

-- 
David Kastrup

Re: Please stop putting curly quotes into doc strings!

[T.V Raman]

1+! Thanks Paul for being open to making these changes.

David Kastrup writes:
 > Paul Eggert <eggert@cs.ucla.edu> writes:
 > 
 > > On 09/10/2015 08:46 AM, David Kastrup wrote:
 > >
 > >> outcommented stuff that would become non-standard when commented back
 > >
 > > Thanks, I missed those, since I didn’t look at comments.  Fixed.
 > >
 > >> Comments and messages like
 > >
 > > Thanks, I missed those message instances, as somebody else introduced
 > > those curved quotes and I looked only at the curved quotes I
 > > introduced.  I changed them to use grave quotes just now.
 > 
 > Thanks for the cleanup.
 > 
 > -- 
 > David Kastrup

-- 

--