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

[Dmitry Gutov]

On 07/06/2015 09:12 AM, Paul Eggert wrote:

> I've done that, and have discovered a couple of problems.

Thank you.

> First, a doc string that contains \[foo] is supposed to generate a key
> description for 'foo', derived by calling (key-description 'foo).  But
> key-description can return a string that contains quote marks, and in
> general some of them should be escaped and others should not be.  It's
> not clear to me whether both possibilities can occur in doc strings, but
> the situation is worrisome.

Why not put `escaped' (or rename that `translated', maybe) on those 
generated regions as well?

> Second, and more generally, the overall approach seems error prone.  It
> asks programmers to mark every quote character that should not be
> transformed.  But characters can come from many different sources, and
> it's hard to keep track of each place that can insert user data of some
> sort.

So far I've only seen a few places of complication nearby: key 
translations, keymap translations, and the escaping mechanism itself.

The rest of them will likely have to be handled in 
substitute-command-keys anyway, somehow.

> In contrast, it's easy to find grave accents in doc strings, to
> fix the relative few that aren't already transformed automatically, and
> to not worry about user data.

If we find it hard to expose this data to Lisp, it will make the output 
presentation less flexible, and could indicate an overall problem in our 
docstring generation (we don't know all the possible sources the 
characters can come from? that's not very good).

By the way, when doing translation in Lisp, instead of using 
help-mode-finish, we can instead examine all the functions that generate 
help buffers for Lisp stuff, and translate only the docstrings, when 
they are being inserted.