Why does show_help_echo call substitute_command_keys?

Why does show_help_echo call substitute_command_keys?

[Clément Pit-Claudel]

Hi emacs-devel,

I'm puzzled by this bit of code in show_help_echo:

  if (STRINGP (help) || NILP (help))
    {
      if (!NILP (Vshow_help_function))
	call1 (Vshow_help_function, Fsubstitute_command_keys (help));
      help_echo_showing_p = STRINGP (help);
    }

This is causing trouble in Flycheck, because we set help-echo properties on error spans and we expect them to be displayed without modifications when users hover over them.  Is there a way to disable command-key- (and quote-) substitution in help-echo strings?

Concrete example:

(with-current-buffer (get-buffer-create "A")
  (erase-buffer)
  (insert "AAA")
  (put-text-property (point-min) (point-max) 'help-echo "Expected a 'list<'a>', got a 'pair<'a,'a>'")
  (pop-to-buffer (current-buffer)))

(put your mouse on the "AAA" part, and notice that the quotes were substituted)

Thanks!
Clément.

Re: Why does show_help_echo call substitute_command_keys?

[Yuri Khan]

On Fri, Jul 21, 2017 at 12:05 AM, Clément Pit-Claudel
<cpitclaudel@gmail.com> wrote:
> Hi emacs-devel,
>
> I'm puzzled by this bit of code in show_help_echo:
>
>   if (STRINGP (help) || NILP (help))
>     {
>       if (!NILP (Vshow_help_function))
>         call1 (Vshow_help_function, Fsubstitute_command_keys (help));
>       help_echo_showing_p = STRINGP (help);
>     }

Because the help-echo property is the Emacs API to tooltips, and
tooltips are expected to be able to display keyboard equivalents to
clicking the thing that is pointed?

> This is causing trouble in Flycheck, because we set help-echo properties on error spans and we expect them to be displayed without modifications when users hover over them.  Is there a way to disable command-key- (and quote-) substitution in help-echo strings?

There should probably be a function that knows when and how to quote
the characters that cause such substitution with \=.

Re: Why does show_help_echo call substitute_command_keys?

[Clément Pit-Claudel]

On 2017-07-21 10:48, Yuri Khan wrote:
> Because the help-echo property is the Emacs API to tooltips, and
> tooltips are expected to be able to display keyboard equivalents to
> clicking the thing that is pointed?

Ok. So we don't expect callers to explicitly use substitute-command-keys on their help-echo properties?

> There should probably be a function that knows when and how to quote
> the characters that cause such substitution with \=.

Yes, it would be nice.  Maybe there already is one and I missed it.

Re: Why does show_help_echo call substitute_command_keys?

[Yuri Khan]

On Fri, Jul 21, 2017 at 4:01 PM, Clément Pit-Claudel
<cpitclaudel@gmail.com> wrote:
> On 2017-07-21 10:48, Yuri Khan wrote:
>> Because the help-echo property is the Emacs API to tooltips, and
>> tooltips are expected to be able to display keyboard equivalents to
>> clicking the thing that is pointed?
>
> Ok. So we don't expect callers to explicitly use substitute-command-keys on their help-echo properties?

Imagine if it were so.

You add a button to the tool bar, with a help-echo property containing
tooltip text with command keys substituted at the time of addition.

The user rebinds the command to another key. Your button retains its
(now inaccurate) tooltip text.

Re: Why does show_help_echo call substitute_command_keys?

[Clément Pit-Claudel]

On 2017-07-21 11:10, Yuri Khan wrote:
> On Fri, Jul 21, 2017 at 4:01 PM, Clément Pit-Claudel
> <cpitclaudel@gmail.com> wrote:
>> On 2017-07-21 10:48, Yuri Khan wrote:
>>> Because the help-echo property is the Emacs API to tooltips, and
>>> tooltips are expected to be able to display keyboard equivalents to
>>> clicking the thing that is pointed?
>>
>> Ok. So we don't expect callers to explicitly use substitute-command-keys on their help-echo properties?
> 
> Imagine if it were so.
> 
> You add a button to the tool bar, with a help-echo property containing
> tooltip text with command keys substituted at the time of addition.
> 
> The user rebinds the command to another key. Your button retains its
> (now inaccurate) tooltip text.

This makes complete sense; thanks!

Re: Why does show_help_echo call substitute_command_keys?

[Stefan Monnier]

>> The user rebinds the command to another key. Your button retains its
>> (now inaccurate) tooltip text.
> This makes complete sense; thanks!

FWIW, we could move the substitute-command-keys call into the
show-help-function, so it's not completely hardcoded.
But in any case we do need a quoting function for
substitute-command-keys.


        Stefan

RE: Why does show_help_echo call substitute_command_keys?

[Drew Adams]

> Because the help-echo property is the Emacs API to tooltips, and
> tooltips are expected to be able to display keyboard equivalents
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> to clicking the thing that is pointed?

Tooltips are not expected to display keys, change quote chars, etc.
But of course they are expected to "be able to" do that.  They are
expected to be able to display lots of things.

`tooltip-show-help' just shows "a help string", as it says.

There is nothing in the notion of a tooltip or the doc about
`tooltip-mode' or the doc about property `help-echo' or the
code in `tooltip.el' that suggests that a tooltip should be
about translating commands to keys or apostrophes to curly
quotes or should impose `substitute-command-keys' on the help
text it's given to display.

A tooltip should just display whatever text it is handed,
with no fiddling with or elaboration of that text.  If you
need such fiddling, whether by ``substitute-command-keys'
or `format' or something else, do it beforehand.

> There should probably be a function that knows when and how to
> quote the characters that cause such substitution with \=.

A tooltip should not automatically try to substitute command
keys or change quote characters.  Why impose such behavior on
tooltips?

You should be able, by default, to pass text that contains
`\\[...]' etc. or quote chars to a tooltip and not have it
interpreted and transmogrified.

RE: Why does show_help_echo call substitute_command_keys?

[Drew Adams]

> > Because the help-echo property is the Emacs API to tooltips, and
> > tooltips are expected to be able to display keyboard equivalents to
> > clicking the thing that is pointed?
> 
> Ok. So we don't expect callers to explicitly use
> substitute-command-keys on their help-echo properties?

We should, if/when they want the effect of `substitute-command-keys'.

Emacs should not assume that `substitute-command-keys' is appropriate
for a tooltip.  Code that wants that behavior should ask for it.

RE: Why does show_help_echo call substitute_command_keys?

[Drew Adams]

> FWIW, we could move the substitute-command-keys call into the
> show-help-function, so it's not completely hardcoded.

Yes.

RE: Why does show_help_echo call substitute_command_keys?

[Drew Adams]

> > Ok. So we don't expect callers to explicitly use substitute-command-keys
> on their help-echo properties?
> 
> Imagine if it were so.
> 
> You add a button to the tool bar, with a help-echo property containing
> tooltip text with command keys substituted at the time of addition.
> 
> The user rebinds the command to another key. Your button retains its
> (now inaccurate) tooltip text.

Which just means that your code isn't good enough.

If you hard-code a `help-echo' property to ANYTHING and some
later changes make that value no longer appropriate...

Re: Why does show_help_echo call substitute_command_keys?

[Yuri Khan]

On Fri, Jul 21, 2017 at 9:54 PM, Drew Adams <drew.adams@oracle.com> wrote:
>> Because the help-echo property is the Emacs API to tooltips, and
>> tooltips are expected to be able to display keyboard equivalents
>   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> to clicking the thing that is pointed?
>
> A tooltip should just display whatever text it is handed,
> with no fiddling with or elaboration of that text.  If you
> need such fiddling, whether by ``substitute-command-keys'
> or `format' or something else, do it beforehand.

Actually, client code that wishes to display a command key in a
tooltip can set the help-echo property to a function. So, hardcoding
the substitute-command-keys call in show_help_echo does not seem
necessary after all.

Re: Why does show_help_echo call substitute_command_keys?

[Clément Pit-Claudel]

On 2017-07-21 19:49, Yuri Khan wrote:
> On Fri, Jul 21, 2017 at 9:54 PM, Drew Adams <drew.adams@oracle.com> wrote:
>>> Because the help-echo property is the Emacs API to tooltips, and
>>> tooltips are expected to be able to display keyboard equivalents
>>   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>> to clicking the thing that is pointed?
>>
>> A tooltip should just display whatever text it is handed,
>> with no fiddling with or elaboration of that text.  If you
>> need such fiddling, whether by ``substitute-command-keys'
>> or `format' or something else, do it beforehand.
> 
> Actually, client code that wishes to display a command key in a
> tooltip can set the help-echo property to a function. So, hardcoding
> the substitute-command-keys call in show_help_echo does not seem
> necessary after all.

Indeed, that's what we do in Flycheck (using a function).

If most menu bar entries are created by easy-menu-define, maybe it wouldn't even break much to change show_help_echo to not substitute command keys (easy-menu-define would add the command key substitution instead).

Clément.