[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: Tue, 7 Jul 2015 01:10:11 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.0

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

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,

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.

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.

reply via email to

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