Re: Escaping quotes in docstrings, Was: A simple solution to "Upcoming loss of usability ..."

[Paul Eggert <eggert@cs.ucla.edu>]

Dmitry Gutov wrote:
> we have an escaping syntax! Yet, Elisp doesn't know what's escaped and what
> isn't, so even this won't help:
>
> (defun ’‘ (a b c)
>   "It's called `\\=’\\=‘'."
>    (+ 1 2 3))

Again, this problem is independent of quoting style, and has long existed in 
Emacs evem with the older quoting style.  For example:

(defun \'\` (a b c)
  "It's called `\\='\\=`'."
   (+ 1 2 3))

has even worse problems than the ’‘ example does (and these problems also exist 
in older Emacs).

> It's also a matter of readability. Take the latest related commit that you
> pushed. Sometime later, someone will come along and wonder: why do we need to
> substitute command keys in widget options? Who would put keys in there?

That can be addressed by renaming the function to 'substitute-doc-string'.

>> this is not just because of curved quotes, but
>> also because its other substitutions can generate characters that also
>> need special treatment.
>
> You might want to give an example.

(defun foo (a b c)
   "It's invoked by `\\[next-error]'."
     (+ 1 2 3))

> But in general, those characters also could
> have `escaped' put on them. Or `substituted', for instance.

Yes, and substituting \[...] has problems and solutions that are quite similar 
to substituting ` and '.  So even if it makes sense to tease this functionality 
apart in some cases, it also makes sense to have a single function that does 
both subsitutions for convenience, as typically programs will not want to do one 
without doing the other.

> As long as that task involves rearranging C code, you're excluding a significant
> portion of Emacs developers from contributing, myself included.

It's a simple-enough matter to add an argument to substitute-doc-string 
specifying which kinds of substitutions are wanted.  I can volunteer to do that 
if it would be helpful (though I confess I don't see the use case).  Or if you 
prefer you can rewrite substitute-doc-string in Lisp -- as long as it doesn't 
affect performance significantly that should be merely an implementation detail.

> as long as font-lock isn't used for translation (and we've pretty much
> agreed that it won't), why wouldn't a Lisp solution work like you describe?

I mentioned the possibility because it's still not clear to me what a Lisp 
solution would be, if it's not something involving font-lock.  If the Lisp 
solution merely translates the existing C code to Lisp, then of course your 
point is correct.