Re: Escaping a string for substitute-command-keys

["Clément Pit-Claudel" <cpitclaudel@gmail.com>]

On 2019-10-04 10:17, Eli Zaretskii wrote:
>> Cc: emacs-devel@gnu.org
>> From: Clément Pit-Claudel <cpitclaudel@gmail.com>
>> 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.