[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: |
Paul Eggert |
Subject: |
Re: Escaping quotes in docstrings, Was: A simple solution to "Upcoming loss of usability ..." |
Date: |
Sun, 02 Aug 2015 08:13:51 -0700 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.8.0 |
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.