Re: Escaping a string for substitute-command-keys

[Eli Zaretskii]

> Cc: address@hidden
> From: Clément Pit-Claudel <address@hidden>
> Date: Fri, 4 Oct 2019 09:56:56 -0400
> 
> > Then why do you use APIs that are meant for keys and quoted strings?
> > Why not format the message yourself?
> 
> Sorry, I do not understand what you mean.  I want to display information when 
> the mouse hovers on a portion of the buffer.  Isn't the proper way to do that 
> to set a help-echo property on the corresponding text?

help-echo is for displaying documentation, not for displaying
general-purpose text strings.

> The manual says nothing about command-key substitutions, it just says "If 
> text has a string as its help-echo property, then when you move the mouse 
> onto that text, Emacs displays that string in the echo area, or in the 
> tooltip window (see Tooltips)."

And a little ways down from that text you have a cross-reference to
"Help display", which leads to the description of show-help-function,
and that one does say the output is passed through
substitute-command-keys.

> Really, all that I'm complaining about is this bit of code in keyboard.c:
> 
>   if (STRINGP (help) || NILP (help))
>     {
>       if (!NILP (Vshow_help_function))
>       call1 (Vshow_help_function, Fsubstitute_command_keys (help));
>       help_echo_showing_p = STRINGP (help);
>     }
> 
> My question is why Vshow_help_function is called with its arguments passed 
> through Fsubstitute_command_keys.

See above.

> >> Ideally, it would be best to be able to turn off that translation 
> >> entirely, I think.  I see why it is convenient, but it seems wasteful to 
> >> mangle a string with escapes only for these escapes to be promptly removed 
> >> right after.
> > 
> > Format it yourself, and you have that, no?  Or what am I missing?
> 
> I think I've been miscommunication :/ Sorry for wasting your time.

No reason to apologize or think you were wasting my time.

> > I think you are using the wrong APIs for the job you need to do.
> > These APIs perform the substitutions for a reason: they were all
> > written for displaying documentation, not arbitrary strings.
> 
> I'm saying that these APIs are inconsistent: sometimes they do substitution, 
> sometimes they don't.

Please tell more about these inconsistencies.  Specifically, which
APIs behave inconsistently?

> > Then don't use help-echo, use child frames instead.
> 
> Are you saying that flymake should grow its own implementation of tooltips

Tooltips by themselves don't substitute, you get in the tooltip the
exact text you've provided.  Here's an example I just trried:

  M-: (tooltip-show "foo `bar' \\[kill-buffer]") RET

The tooltip that popped up didn't do any substitutions, I see the same
text I typed.

The substitution happens specifically in generating the help-echo, and
it happens before we pop up the tooltip.

It is possible that we need to provide some additional facilities to
make this stuff more flexible in specific situations, but I think we
should first be on the same page regarding the existing facilities and
what they are intended for.