[Top][All Lists]

[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: Mon, 6 Jul 2015 15:07:34 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.0

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

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.

reply via email to

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