emacs-devel
[Top][All Lists]
Advanced

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

Re: Escaping quotes in docstrings, Was: A simple solution to "Upcoming l


From: Dmitry Gutov
Subject: Re: Escaping quotes in docstrings, Was: A simple solution to "Upcoming loss of usability ..."
Date: Sun, 2 Aug 2015 21:31:09 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:40.0) Gecko/20100101 Thunderbird/40.0

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



reply via email to

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