Re: Upcoming loss of usability of Emacs source files and Emacs.

[Paul Eggert]

Richard Stallman wrote:
> as long as both forms are used, this means
> a tiny complication rather than a tiny simplification

The intent is to move to the simpler form, which uses curved quotes uniformly. 
That will be simpler than what's in master now, and simpler than what's in Emacs 
24.5 where curved quotes are in documentation but grave accents are in *Help* 
buffers and diagnostics.  So the idea is to support the traditional form 
indefinitely to ease transition, but to recommend the simpler form.

> To understand Emacs Lisp (beyond the rudiments) one must learn an awful lot.

Comments and strings and doc strings are part of the rudiments.  The course I 
mentioned assumes six months' programming experience.  Even people with less 
experience than that should be able to read and write doc strings.

> When we mention a complicated expression in a doc string, we typically
> put it on separate lines, for readability.

This works if the definition of “complicated” includes any expression containing 
' or `, which requires separate lines that would not be otherwise needed.  And 
there is a reasonable likelihood of confusing docstrings lacking separate lines 
anyway.  For example, until I recently fixed it the docstring for 
‘recursive-edit’ contained this:

  To get out of the recursive edit, a command can throw to `exit' -- for
  instance `(throw 'exit nil)'.

Is one supposed to quasiquote the throw?  An expert should know the answer right 
away, but a non-expert is likely to be confused at first.  Curved-quote 
docstrings lessen this sort of confusion.