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

[Dmitry Gutov]

On 07/06/2015 07:30 PM, Paul Eggert wrote:

> I'm afraid this is because you've only started looking.  Even if we
> limit ourselves to the regions you mention, the relevant code is
> scattered all over the place and it's hard to find exactly where to put
> 'escaped' or 'translated' into those regions.

I meant complications related to `substitute-command-keys'. That 
function should know exactly where to put them, because it expands 
\\[command] and similar syntax.

But if you were looking for consumers of `key-description' in 
help-fns.el, these are concentrated in `help-fns--key-bindings'. And 
it's only used in one place: `describe-function-1'. Putting `help-value' 
on it is trivial.

> For example, one place
> might be the following code in keymap.c's single_key_description function:

That doesn't sound right to me. `key-description' should continue 
returning a plain string.

> Since KEY can be an arbitrary symbol, quite possibly its characters
> should be marked as 'escaped' or 'translated', which would mean adding
> this:

I never was proposing a "dirty" string tagging throughout all functions 
that deal with them.  Only in functions that output to Help buffers (and 
know about it), that deal with `' markup.

>    put_text_property (1, 1 + SCHARS (SYMBOL_NAME (key)), Qescaped, Qt,
> result);
>
> before the return.  Unfortunately it's not at all obvious whether this
> is needed unless one examines all the ways that C-h can put text into
> the *Help* buffer (which I haven't done).  And one must do this
> potentially every time a string or symbol name is looked at.

I'm afraid I don't understand you here.

> Plus,
> there are a lot of possibilities for off-by-one errors: for example,
> that '1 +' might easily be forgotten.

That's one of the reasons to implement as little as possible in C.

> Plus, even then there are
> opportunities for bugs: the above call to 'put_text_property' is not
> correct if the symbol name contains a NUL byte.  Plus, there are other
> areas that will require this sort of complication, e.g., button labels,
> *Apropos* buffers.

Apropos buffers - maybe. But since when do button labels have quotes in 
them?

> In contrast, it's much easier to look through the code for ` inside a
> string, and mark the exceptional characters that are intended to be
> quotes and that are not automatically translated already.

Sorry, I don't understand this either. Mark? Automatically translated?

> > (we don't know all the possible sources the characters can
> > come from? that's not very good).
>
> No, actually, it's a good thing.  It's nice that programs can put
> arbitrary text into *Help* buffers, and that that we don't need to worry
> about where the text came from: it just works.  That's a simple
> interface, and simple interfaces are good.

Well, it's one way of looking at it.

> > we can instead examine all the functions that generate help buffers
> > for Lisp
> > stuff, and translate only the docstrings, when they are being inserted.
>
> That's what the master branch is doing now, no?

That would be closer, but the current master implements more in C, which 
means fewer people who can change or maintain the code. And it 
complicates the API of a low-level function (substitute-command-keys), 
in a way that seems incompatible with radically changing the output later.