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

[Dmitry Gutov]

On 07/07/2015 10:54 AM, Paul Eggert wrote:

> In customization buffers.

Ok. We haven't considered those so far.

So yeah, if there are a lot of places where the docstrings are 
displayed, it's probably better to perform the translation of docstring 
markup in a centralized way.

> I meant that although normally doc strings are translated and one can
> quote with either grave accent and apostrophe or curved quotation marks
> and they will be translated automatically to the user preferred style,
> occasionally one wants an actual grave accent or curved quotation mark
> to be output as-is regardless of user preference and these exceptional
> cases need to be marked in the doc strings.

I sounds like you're describing a use case for an escaping mechanism. 
But what is the point of that? We've already agreed on a need for it.

> We can't anticipate radical changes that future maintainers might want
> to do. Worrying about that is likely to lead to overengineering and
> wasted effort. We'll have enough trouble just solving today's problems.

Concern about the API complication is not over-engineering. We can 
totally worry about it now.

And one alternative use has already been mentioned (at least twice): 
don't use the quotes in the output at all, and instead highlight the 
quoted expressions with color; and possibly a different font-face.

> As for whether the implementation should be in C -- some parts have to
> be used by C, since C code generates quoted strings on occasion.

Not necessarily, C code is perfectly able to use Lisp functions. You'd 
have to look at what the diagnostics formatting will do anyway (would it 
have to support escaping, for instance).

Even so, some duplication might be in order: docstrings and disgnostics 
can do different things in the output; you cannot reliably use colors 
and fonts in the latter.

> How much should be in C vs Lisp is an implementation detail that is no big
> deal.

No big deal for you?

I hope we can agree, at least, that substitute-command-keys shouldn't 
perform the translation itself.