From: "Clément Pit-Claudel" <cpitclaudel@gmail.com>
To: Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org
Subject: Re: Escaping a string for substitute-command-keys
Date: Sat, 5 Oct 2019 00:03:01 -0400 [thread overview]
Message-ID: <39178daa-2edd-9cf2-9bb4-42942b6e2132@gmail.com> (raw)
In-Reply-To: <83imp461do.fsf@gnu.org>
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.
next prev parent reply other threads:[~2019-10-05 4:03 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-10-03 13:52 Escaping a string for substitute-command-keys Clément Pit-Claudel
2019-10-03 16:31 ` Eli Zaretskii
2019-10-03 16:46 ` Clément Pit-Claudel
2019-10-03 17:21 ` Eli Zaretskii
2019-10-03 18:28 ` Clément Pit-Claudel
2019-10-03 18:54 ` Eli Zaretskii
2019-10-04 13:56 ` Clément Pit-Claudel
2019-10-04 14:17 ` Eli Zaretskii
2019-10-05 4:03 ` Clément Pit-Claudel [this message]
2019-10-05 7:33 ` Eli Zaretskii
2019-10-05 15:05 ` Stefan Monnier
2019-10-05 15:59 ` Eli Zaretskii
2019-10-05 4:06 ` Clément Pit-Claudel
2019-10-05 7:12 ` Eli Zaretskii
2019-10-05 8:04 ` Clément Pit-Claudel
2019-10-05 8:13 ` Eli Zaretskii
2019-10-05 8:24 ` Clément Pit-Claudel
2019-10-05 9:20 ` Eli Zaretskii
2019-10-04 19:19 ` Stefan Monnier
2019-10-05 15:40 ` Basil L. Contovounesios
2019-10-05 16:06 ` Eli Zaretskii
2019-10-05 19:53 ` Basil L. Contovounesios
2019-10-06 2:57 ` Clément Pit-Claudel
2019-10-06 17:21 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=39178daa-2edd-9cf2-9bb4-42942b6e2132@gmail.com \
--to=cpitclaudel@gmail.com \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.