[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Emacs-diffs] master b533552 2/5: Documentation fixes re quotes

From: Paul Eggert
Subject: Re: [Emacs-diffs] master b533552 2/5: Documentation fixes re quotes
Date: Tue, 1 Sep 2015 18:05:15 -0700
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.2.0

Richard Stallman wrote:

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.

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]