[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Escaping a string for substitute-command-keys
From: |
Clément Pit-Claudel |
Subject: |
Re: Escaping a string for substitute-command-keys |
Date: |
Sat, 5 Oct 2019 00:03:01 -0400 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.8.0 |
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.
- Escaping a string for substitute-command-keys, Clément Pit-Claudel, 2019/10/03
- Re: Escaping a string for substitute-command-keys, Eli Zaretskii, 2019/10/03
- Re: Escaping a string for substitute-command-keys, Clément Pit-Claudel, 2019/10/03
- Re: Escaping a string for substitute-command-keys, Eli Zaretskii, 2019/10/03
- Re: Escaping a string for substitute-command-keys, Clément Pit-Claudel, 2019/10/03
- Re: Escaping a string for substitute-command-keys, Eli Zaretskii, 2019/10/03
- Re: Escaping a string for substitute-command-keys, Clément Pit-Claudel, 2019/10/04
- Re: Escaping a string for substitute-command-keys, Eli Zaretskii, 2019/10/04
- Re: Escaping a string for substitute-command-keys,
Clément Pit-Claudel <=
- Re: Escaping a string for substitute-command-keys, Eli Zaretskii, 2019/10/05
- Re: Escaping a string for substitute-command-keys, Stefan Monnier, 2019/10/05
- Re: Escaping a string for substitute-command-keys, Eli Zaretskii, 2019/10/05
- Re: Escaping a string for substitute-command-keys, Clément Pit-Claudel, 2019/10/05
- Re: Escaping a string for substitute-command-keys, Eli Zaretskii, 2019/10/05
- Re: Escaping a string for substitute-command-keys, Clément Pit-Claudel, 2019/10/05
- Re: Escaping a string for substitute-command-keys, Eli Zaretskii, 2019/10/05
- Re: Escaping a string for substitute-command-keys, Clément Pit-Claudel, 2019/10/05
- Re: Escaping a string for substitute-command-keys, Eli Zaretskii, 2019/10/05
- Re: Escaping a string for substitute-command-keys, Stefan Monnier, 2019/10/04