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

[Dmitry Gutov <dgutov@yandex.ru>]

On 08/02/2015 06:13 PM, Paul Eggert wrote:

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

We didn't have an escaping syntax for quotes before. You've increased 
the complexity of our handling of quoting. Might as well fix some 
pre-existing problems. Right?

Look at it from the user's point of view: quotes can be escaped, it's 
documented in the substitute-command-keys docstring. And yet, it doesn't 
help in this kind of situations, where it seemingly should.

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

This works now, and would continue to work, as per my suggestion.

> 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.

When both substitutions are required, calling the second function on the 
result of the first function will be just as easy. Splitting the logic 
between two functions will make sure the first one doesn't lose information.

> 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).

It's better to keep the quote translation logic in one place (in a 
different function).

> 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.

Rewriting it also requires some C chops, if only to read the original. I 
don't know whether it'll lose performance: it might, handing certain 
keymaps might be intensive.

Anyway, even if the resulting function is in Lisp, it won't help as long 
as it's just one function, and it still loses information about which 
characters were originally escaped.

> 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.

The Lisp solution would replace actual characters with different 
characters. In the text, not apply the transformation via text 
properties (although that's also an option).