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

[Paul Eggert]

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.