Re: Escaping a string for substitute-command-keys

[Clément Pit-Claudel]

On 2019-10-04 10:17, Eli Zaretskii wrote:
>> 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.

Understood.  Thanks for taking the time to explain.

In my experience, help-echo is very convenient (modulo this small issue with 
substituting command keys) for the general purpose of associating a small 
amount of help text to a buffer region, because everything is handled 
automagically for you.  For example, both flycheck and flymake use it to attach 
errors or warnings to regions of the buffer.

I have briefly reviewed the places where I use it in my code, and indeed it 
falls into two categories:

* Places where I want to indicate to the user how to interact with the text 
(really, a button) under the cursor.  There's are many places in Emacs that use 
it for this purpose, indeed, but most of them actually don't leverage the 
command substitution facility:
  lisp/help-mode.el:291:4:  'help-echo (purecopy "mouse-2, RET: visit theme 
file"))
  lisp/vc/vc-git.el:706:11:                    'help-echo "mouse-3: Show stash 
menu…
  lisp/progmodes/compile.el:114:30:                                'help-echo 
"Compiling; mouse-2: Goto Buffer"
  lisp/help-fns.el:1073:12:                            'help-echo "mouse-2, 
RET: show value")

* Places where I want to add some general information about the text at point.  
There are some places like that in Emacs too:
  lisp/net/shr.el:1499:8:      'help-echo title ;; This is the title of an 
<abbr> tag
  lisp/net/shr.el:1237:4:        'help-echo (let ((parsed 
(url-generic-parse-url ;; This shows the URL a links points to
  lisp/progmodes/flymake.el:647:23:      (default-maybe 'help-echo ;; This 
attaches a compiler message to a buffer region

The motivation for using help-echo in the second case is that works very easily 
and very smoothly: users see the text in a tooltip if they hover, and in the 
echo area otherwise, and you don't have to do much on the package side at all.  
But the command-key substitution only makes sense in the first case: neither 
shr nor flymake want quotes transformed in the help-echos that they set, 
because these are data coming from the outside. 

> 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.

Got it, thanks. My bad.
> No reason to apologize or think you were wasting my time.

Thanks for your patience :)

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

There are two main places that I know of in Emacs that use help-echo: 
help-at-pt, specifically display-local-help, which displays the contents of the 
help-echo in the echo area; and show_help_echo, in keyboard.c, which calls 
show-help-function after running substitute-command-keys.

The inconsistency is that the former displays the help-echo property 
unmodified, whereas the latter displays it after running 
substitute-command-keys.

> Tooltips by themselves don't substitute, you get in the tooltip the
> exact text you've provided.  Here's an example I just trried: […]
> The substitution happens specifically in generating the help-echo, and
> it happens before we pop up the tooltip.

Indeed, you're absolutely correct.  The convenience that help-echo provides is 
that it provides a very easy way to tell Emacs "display a tooltip with this 
text when the mouse hovers above this overlay".  I think it's not easy to 
achieve this result otherwise, which makes help-echo a generally useful 
primitive.

> 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.

I hope the above helps with that. Thanks again for your help.

Clément.