Would you say this information window is well designed?

Would you say this information window is well designed?

[Peter Dean]

I mean is it easy to parse? Is it appealing?

    https://i.imgur.com/KIWQE60.png

It could use some spacing (e.g. a newline after the first line
and Documentation), some colors (e.g. highlight symbols in
‘...’), and so on.

The package Helpful improves the default Help look. Some ideas
for coloring and formatting could be borrowed from it to make the
default mode more appealing, less spartan:

    https://raw.githubusercontent.com/Wilfred/helpful/master/screenshots/helpful.png

Re: Would you say this information window is well designed?

[Eli Zaretskii]

> Date: Mon, 22 Feb 2021 18:37:20 +0000
> From: Peter Dean <laszlomail@protonmail.com>
> 
> I mean is it easy to parse? Is it appealing?
> 
>     https://i.imgur.com/KIWQE60.png
> 
> It could use some spacing (e.g. a newline after the first line
> and Documentation), some colors (e.g. highlight symbols in
> ‘...’), and so on.

Patches are welcome for adding more colors to the *Help* buffers.

As to the newline, we are discussing that, as you are well aware.

> The package Helpful improves the default Help look. Some ideas
> for coloring and formatting could be borrowed from it to make the
> default mode more appealing, less spartan:
> 
>     https://raw.githubusercontent.com/Wilfred/helpful/master/screenshots/helpful.png

I won't object making something like that an optional feature, but
doing this by default is annoying, IMO: it's too much unsolicited
info.  If, after reading the doc string, I want to look up the symbol
in the Info manual, I can do that with 2 keystrokes, I don't need
Emacs to show it to me unconditionally.

Re: Would you say this information window is well designed?

[Dmitry Gutov]

On 22.02.2021 20:48, Eli Zaretskii wrote:
> I won't object making something like that an optional feature, but
> doing this by default is annoying, IMO: it's too much unsolicited
> info.  If, after reading the doc string, I want to look up the symbol
> in the Info manual, I can do that with 2 keystrokes, I don't need
> Emacs to show it to me unconditionally.

The only extra info on the screenshot are the "View in manual" button 
(which I would imagine you find appealing, given that it will lead more 
users to read the manual) and the "References" section, which is not 
essential, IMHO. The rest are mostly presentation.

Though the "key bindings" section is interesting in that is also shows 
the keymap where each bindings resides. This would have saved me some 
extra debugging efforts in the past.

Re: Would you say this information window is well designed?

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Mon, 22 Feb 2021 21:23:47 +0200
> 
> On 22.02.2021 20:48, Eli Zaretskii wrote:
> > I won't object making something like that an optional feature, but
> > doing this by default is annoying, IMO: it's too much unsolicited
> > info.  If, after reading the doc string, I want to look up the symbol
> > in the Info manual, I can do that with 2 keystrokes, I don't need
> > Emacs to show it to me unconditionally.
> 
> The only extra info on the screenshot are the "View in manual" button 
> (which I would imagine you find appealing, given that it will lead more 
> users to read the manual) and the "References" section, which is not 
> essential, IMHO. The rest are mostly presentation.

I _was_ talking about those two additions.  (Though we don't see all
of the buffer, only its top, so more surprises could be below.)

> Though the "key bindings" section is interesting in that is also shows 
> the keymap where each bindings resides. This would have saved me some 
> extra debugging efforts in the past.

Each one of these could be useful, but not all of them together, and
not every time.  It's too much.  But as an opt-in feature, why not?

Re: Would you say this information window is well designed?

[Joost Kremers]

On Mon, Feb 22 2021, Eli Zaretskii wrote:
> I _was_ talking about those two additions.  (Though we don't see all
> of the buffer, only its top, so more surprises could be below.)

The buffer also contains buttons to enable edebug or tracing of the function, to
disassemble it or to unbind the symbol. Then it gives the source code, a
list of symbol properties and a list of aliases.

> Each one of these could be useful, but not all of them together, and
> not every time.  It's too much.  But as an opt-in feature, why not?

I have the helpful package installed and set up `s-h` as a prefix to access the
various commands. Yet, I mostly use the default Emacs commands on C-h, because
most of the time I'm only interested in the doc string and on my (admittedly
under-powered) laptop, helpful takes precious seconds to gather all its info.

-- 
Joost Kremers
Life has its moments

Re: Would you say this information window is well designed?

[Dmitry Gutov]

On 22.02.2021 21:28, Eli Zaretskii wrote:

>> The only extra info on the screenshot are the "View in manual" button
>> (which I would imagine you find appealing, given that it will lead more
>> users to read the manual) and the "References" section, which is not
>> essential, IMHO. The rest are mostly presentation.
> 
> I _was_ talking about those two additions.  (Though we don't see all
> of the buffer, only its top, so more surprises could be below.)

Yes, there are more. But I thought we were only discussing the 
screenshot. To be clear, I'm not advocating for the additions of any of 
those that would slow down the rendering of the Help buffer.

>> Though the "key bindings" section is interesting in that is also shows
>> the keymap where each bindings resides. This would have saved me some
>> extra debugging efforts in the past.
> 
> Each one of these could be useful, but not all of them together, and
> not every time.  It's too much.  But as an opt-in feature, why not?

It will be a missed opportunity to teach some new users that they 
can/should use the manual for more in-depth explanations.

Or that Emacs actually knows more about the function and its symbol.

Anyway, I'll stop here. If you don't think we should push for manual's 
higher visibility, I certainly don't.

Re: Would you say this information window is well designed?

[Lars Ingebrigtsen]

Dmitry Gutov <dgutov@yandex.ru> writes:

> It will be a missed opportunity to teach some new users that they
> can/should use the manual for more in-depth explanations.
>
> Or that Emacs actually knows more about the function and its symbol.
>
> Anyway, I'll stop here. If you don't think we should push for manual's
> higher visibility, I certainly don't.

I think linking to the manual (as much as practically possible) from
*Help* is a good idea.  However, `info-lookup-symbol' (the innards of
which we basically have to call) is a bit on the slow side.

Would it make sense to precompute (as part of the build process) a cache
that *Help* could consult?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

RE: [External] : Re: Would you say this information window is well designed?

[Drew Adams]

> I think linking to the manual (as much as practically possible) from
> *Help* is a good idea.  However, `info-lookup-symbol' (the innards of
> which we basically have to call) is a bit on the slow side.

I don't find it slow.  And it can be invoked only
when a user clicks (or uses RET) on a link.

I do that (in help-fns+.el) when the only manuals
to be searched are Emacs and Elisp.

This is the logic I use, FWIW:

,----
| Info-make-manuals-xref is a Lisp function in 'help-fns+.el'.
| 
| (Info-make-manuals-xref OBJECT &optional NO-NEWLINES-AFTER-P
| MANUALS-SPEC NOMSG)
| 
| For more information see the manuals.
| 
| Create a cross-ref link for entries for OBJECT in manuals.
| Non-`nil' optional arg NO-NEWLINES-AFTER-P means do not add two
| newlines after the cross reference.
| 
| Optional arg MANUALS-SPEC controls which manuals to search.  It has
| the same form as option `help-cross-reference-manuals', and it
| defaults to the value of that option.
| 
| Do nothing if the car of MANUALS-SPEC is nil (no manuals to search).
| 
| Otherwise, there are 3 cases:
| 
| 1. The cdr is `nil' and the car has the two manuals "emacs" and
|    "elisp", and only these (this is the default).
| 
|    Create the link without first searching any manuals.  Clicking the
|    link uses `help-lookup-symbol'.
| 
| 2. The cdr is `nil' and the car does not have just those two manuals.
| 
|    Create the link without first searching any manuals.  Clicking the
|    link then searches the manuals.
| 
| 3. The cdr is non-`nil'.
| 
|    Create the link only if there are search hits in the manuals.
|    This takes time.
| 
| In cases #1 and #2, clicking the link might find that there are no
| search hits in the manuals.  In case #3, if there is a link then it is
| sure to lead to hits.
| 
| In cases #2 and #3, clicking the link brings up an Info index buffer
| for the manuals with hits.  In case #1, clicking the link takes you
| directly to a hit in one of the manuals, Emacs or Elisp.
| 
| Cases #1 and #2 create the `*Help'* buffer quickly.  Case #3 takes
| time to create it - possibly considerable time.
`----

User option `help-cross-reference-manuals':

,----
| help-cross-reference-manuals is a variable defined in `help-fns+.el'.
| Its value is (("emacs" "elisp"))
| 
| Documentation:
| Manuals to search, for a `*Help*' buffer link to the manuals.
| The default value is (("emacs" "elisp")).  Clicking the
| cross-reference link in `*Help*' uses `info-lookup-symbol' to take you
| directly to the relevant doc in the Emacs or Elisp manual.  This is
| very quick.
| 
| Any other value means that clicking the link searches the indexes of
| the specified manuals and then opens an Info Index buffer with links
| to the relevant manuals.  This can take a while, and if there are no
| matches then the `*info*' buffer shown is empty.  The advantage of
| this approach is that you can get to a hit in more than one manual.
| 
| The option value is a cons: (MANUALS . SEARCH-FIRST).
| 
|  MANUALS is the list of manuals to search, or the symbol `all', to
|   search all.  If `nil' then do not create a cross-reference link.
| 
|  SEARCH-FIRST is a Boolean value.  If MANUALS specifies other than
|  just the Emacs and Elisp manuals (both) then:
| 
|   * `nil' SEARCH-FIRST means create a cross-reference link
|     immediately, whether or not there are actually any matches.
| 
|   * Non-`nil' SEARCH-FIRST means search the indexes, and create a link
|     only if there are matches.  The indexes are thus searched before
|     populating buffer `*Help*', which takes time.  You probably do not
|     want to use this possibility.
| 
| You can customize this variable.
| 
| For more information see the manuals.
`----

RE: [External] : Re: Would you say this information window is well designed?

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

>> I think linking to the manual (as much as practically possible) from
>> *Help* is a good idea.  However, `info-lookup-symbol' (the innards of
>> which we basically have to call) is a bit on the slow side.
>
> I don't find it slow.  And it can be invoked only
> when a user clicks (or uses RET) on a link.

But wouldn't that mean that the link is shown unconditionally?

That's what happens with "helpful.el", and it doesn't make for the best
experience when the function is not in any manual.  It would be better
to not show a link in that case.

RE: [External] : Re: Would you say this information window is well designed?

[Drew Adams]

> >> I think linking to the manual (as much as practically possible) from
> >> *Help* is a good idea.  However, `info-lookup-symbol' (the innards
> >> of which we basically have to call) is a bit on the slow side.
> >
> > I don't find it slow.  And it can be invoked only
> > when a user clicks (or uses RET) on a link.
> 
> But wouldn't that mean that the link is shown unconditionally?

Option `help-cross-reference-manuals' controls the manuals to search, as well as when to search them (on click or before creating the link).  If it's nil then no link is created.  Code could bind it to nil conditionally, if that's wanted.

> That's what happens with "helpful.el", and it doesn't make for the best
> experience when the function is not in any manual.  It would be better
> to not show a link in that case.

Whether to search beforehand, in which case you won't produce a link if there are no matches, or only when a user clicks the link, is controlled by the option (see above).

But depending on what kind of searching is done, searching beforehand, to be sure not to create a link if no match, can take time.

Here's the doc string of the option:

,----
| help-cross-reference-manuals is a variable defined in `help-fns+.el'.
| 
| Its value is (("emacs" "elisp"))
| 
| Documentation:
| Manuals to search, for a `*Help*' buffer link to the manuals.
| The default value is (("emacs" "elisp")).  Clicking the
| cross-reference link in `*Help*' uses `info-lookup-symbol' to take you
| directly to the relevant doc in the Emacs or Elisp manual.  This is
| very quick.
| 
| Any other value means that clicking the link searches the indexes of
| the specified manuals and then opens an Info Index buffer with links
| to the relevant manuals.  This can take a while, and if there are no
| matches then the `*info*' buffer shown is empty.  The advantage of
| this approach is that you can get to a hit in more than one manual.
| 
| The option value is a cons: (MANUALS . SEARCH-FIRST).
| 
|  MANUALS is the list of manuals to search, or the symbol `all', to
|   search all.  If `nil' then do not create a cross-reference link.
| 
|  SEARCH-FIRST is a Boolean value.  If MANUALS specifies other than
|  just the Emacs and Elisp manuals (both) then:
| 
|   * `nil' SEARCH-FIRST means create a cross-reference link
|     immediately, whether or not there are actually any matches.
| 
|   * Non-`nil' SEARCH-FIRST means search the indexes, and create a link
|     only if there are matches.  The indexes are thus searched before
|     populating buffer `*Help*', which takes time.  You probably do not
|     want to use this possibility.
| 
| You can customize this variable.
| 
| For more information see the manuals.
`----

RE: [External] : Re: Would you say this information window is well designed?

[Drew Adams]

> Here's the doc string of the option:

(Apologies for sending that again.
Forgot I'd already sent it.)

RE: [External] : Re: Would you say this information window is well designed?

[Peter Dean]

On Tuesday, February 23, 2021 6:34 AM, Drew Adams <drew.adams@oracle.com> wrote:
>
> But depending on what kind of searching is done, searching beforehand, to be sure not to create a link if no match, can take time.

I haven't used threads yet, but I guess this search could also be
done asynchronously from a thread which yields often to keep the
UI responsive, so the link wouldn't be there when Help is opened,
but if a link is found then the thread inserts the link into
the help buffer.

Re: [External] : Re: Would you say this information window is well designed?

[Eli Zaretskii]

> Date: Tue, 23 Feb 2021 05:54:09 +0000
> From: Peter Dean <laszlomail@protonmail.com>
> Cc: Stefan Kangas <stefankangas@gmail.com>, Lars Ingebrigtsen <larsi@gnus.org>, Dmitry Gutov <dgutov@yandex.ru>, Eli Zaretskii <eliz@gnu.org>, "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> 
> I haven't used threads yet, but I guess this search could also be
> done asynchronously from a thread which yields often to keep the
> UI responsive, so the link wouldn't be there when Help is opened,
> but if a link is found then the thread inserts the link into
> the help buffer.

I suggest that you try using threads for such purposes.  Because it's
easier said than done, and IME this kind of jobs is not something for
which Lisp threads, as currently implemented, are suitable.

Re: [External] : Re: Would you say this information window is well designed?

[Peter Dean]

On Tuesday, February 23, 2021 4:22 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>
> I suggest that you try using threads for such purposes. Because it's
> easier said than done, and IME this kind of jobs is not something for
> which Lisp threads, as currently implemented, are suitable.

Isn't it a kind of async task for which threads would be ideal, provided
the thread takes care of yielding often to keep the UI going?

What is it in Elisp threads which make them unsuitable for this? What
kind of problems do you think of?

Re: [External] : Re: Would you say this information window is well designed?

[Eli Zaretskii]

> Date: Tue, 23 Feb 2021 15:29:41 +0000
> From: Peter Dean <laszlomail@protonmail.com>
> Cc: "drew.adams@oracle.com" <drew.adams@oracle.com>, "stefankangas@gmail.com" <stefankangas@gmail.com>, "larsi@gnus.org" <larsi@gnus.org>, "dgutov@yandex.ru" <dgutov@yandex.ru>, "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> 
> 
> On Tuesday, February 23, 2021 4:22 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> >
> > I suggest that you try using threads for such purposes. Because it's
> > easier said than done, and IME this kind of jobs is not something for
> > which Lisp threads, as currently implemented, are suitable.
> 
> Isn't it a kind of async task for which threads would be ideal, provided
> the thread takes care of yielding often to keep the UI going?

In theory?  Probably.  But we aren't talking about theory here.

> What is it in Elisp threads which make them unsuitable for this? What
> kind of problems do you think of?

There's no simple explanation, not in terms that would be easily
understood, unless you are familiar with the implementation details.
The best I can do is say that our threads don't yield frequently
enough, nowhere near the frequency that you seem to assume.

Re: [External] : Re: Would you say this information window is well designed?

[Peter Dean]

>
> There's no simple explanation, not in terms that would be easily
> understood, unless you are familiar with the implementation details.
> The best I can do is say that our threads don't yield frequently
> enough, nowhere near the frequency that you seem to assume.

Thanks. I thought if a thread calls thread-yield very often (e.g.
in ever iteration of a loop) then it lets the UI process pending
events every time it yields.

But if I understand you correctly, even if the thread calls
thread-yield explicitly, it is not a guaranteed that the UI
processes events and stay responsive.

If this the case then I wonder what the possible uses for threads
are.

Re: [External] : Re: Would you say this information window is well designed?

[Eli Zaretskii]

> Date: Tue, 23 Feb 2021 17:32:09 +0000
> From: Peter Dean <laszlomail@protonmail.com>
> Cc: "drew.adams@oracle.com" <drew.adams@oracle.com>, "stefankangas@gmail.com" <stefankangas@gmail.com>, "larsi@gnus.org" <larsi@gnus.org>, "dgutov@yandex.ru" <dgutov@yandex.ru>, "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> 
> Thanks. I thought if a thread calls thread-yield very often (e.g.
> in ever iteration of a loop) then it lets the UI process pending
> events every time it yields.
> 
> But if I understand you correctly, even if the thread calls
> thread-yield explicitly, it is not a guaranteed that the UI
> processes events and stay responsive.

Yes, because there's no guarantee that the thread running the UI
(usually, the main thread) is the one that will take the lock released
by thread-yield.

> If this the case then I wonder what the possible uses for threads
> are.

Welcome to the club.

Re: [External] : Re: Would you say this information window is well designed?

[Peter Dean]

On Tuesday, February 23, 2021 6:40 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>
> Yes, because there's no guarantee that the thread running the UI
> (usually the main thread) is the one that will take the lock released
> by thread-yield.

Then there could be a refresh rate value (e.g. 15 ms or some other value,
configurable) and thread-yield could check if the main thread got the lock
within this time window.

If not then it would give the lock explicitly to the main thread, otherwise
the next thread gets the lock.

This could guarantee UI responsivity which is the first priority and other
threads get the lock only when the UI is fresh enough.

Re: [External] : Re: Would you say this information window is well designed?

[Eli Zaretskii]

> Date: Tue, 23 Feb 2021 17:59:08 +0000
> From: Peter Dean <laszlomail@protonmail.com>
> Cc: "drew.adams@oracle.com" <drew.adams@oracle.com>, "stefankangas@gmail.com" <stefankangas@gmail.com>, "larsi@gnus.org" <larsi@gnus.org>, "dgutov@yandex.ru" <dgutov@yandex.ru>, "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> 
> Then there could be a refresh rate value (e.g. 15 ms or some other value,
> configurable) and thread-yield could check if the main thread got the lock
> within this time window.
> 
> If not then it would give the lock explicitly to the main thread, otherwise
> the next thread gets the lock.

thread-yield runs in the context of the thread that yields.  You make
it sound like there's some entity other than the involved threads
which runs thread-yield, but that's not what happens.

I really suggest to read the code, it is not too large and not hard to
understand how it works.  Then such discussions could be much more
meaningful.

Re: [External] : Re: Would you say this information window is well designed?

[Peter Dean]

>
> I really suggest to read the code, it is not too large and not hard to
> understand how it works.

I checked and I see yield calls the system scheduler. Could simply
giving the main thread the highest priority work? So it's more likely to
be scheduled next than other threads, thereby increasing the chance of the
UI being updated after a yield.

Re: [External] : Re: Would you say this information window is well designed?

[Eli Zaretskii]

> Date: Tue, 23 Feb 2021 19:36:28 +0000
> From: Peter Dean <laszlomail@protonmail.com>
> Cc: "drew.adams@oracle.com" <drew.adams@oracle.com>, "stefankangas@gmail.com" <stefankangas@gmail.com>, "larsi@gnus.org" <larsi@gnus.org>, "dgutov@yandex.ru" <dgutov@yandex.ru>, "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> 
> I checked and I see yield calls the system scheduler. Could simply
> giving the main thread the highest priority work?

Why the main thread?  The UI could be run in any thread, not
necessarily in the main one.  There's no way to know in advance which
one will run it.

And what if one of the non-main threads wants to ask the user a
question, for example?  It could happen without any intent on the
application level, simply because a thread calls some primitive that
needs to prompt the user.

And finally, if you give the main thread higher priority up front, how
can we make sure the other threads will ever get to run?

Re: [External] : Re: Would you say this information window is well designed?

[Peter Dean]

>
> Why the main thread? The UI could be run in any thread, not
> necessarily in the main one. There's no way to know in advance which
> one will run it.

OK, then how about this: we start a thread which has the only job of
keeping the UI updated. It has high priority and when it is scheduled
it checks when was the UI last updated. If it's within the refresh
rate then it yields to other threads without doing anything. Othwerise,
it updates the UI and then yields.

> And finally, if you give the main thread higher priority up front, how
> can we make sure the other threads will ever get to run?

It is the job of the scheduler to make sure lower priority threads are
not starved, so it takes care of this.

Re: [External] : Re: Would you say this information window is well designed?

[Eli Zaretskii]

> Date: Tue, 23 Feb 2021 21:58:46 +0000
> From: Peter Dean <laszlomail@protonmail.com>
> Cc: "drew.adams@oracle.com" <drew.adams@oracle.com>, "stefankangas@gmail.com" <stefankangas@gmail.com>, "larsi@gnus.org" <larsi@gnus.org>, "dgutov@yandex.ru" <dgutov@yandex.ru>, "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> 
> OK, then how about this: we start a thread which has the only job of
> keeping the UI updated. It has high priority and when it is scheduled
> it checks when was the UI last updated. If it's within the refresh
> rate then it yields to other threads without doing anything. Othwerise,
> it updates the UI and then yields.

You are describing design that is very different from what we have.

> > And finally, if you give the main thread higher priority up front, how
> > can we make sure the other threads will ever get to run?
> 
> It is the job of the scheduler to make sure lower priority threads are
> not starved, so it takes care of this.

I think this is only true wrt threads that are almost always ready to
run.  That's not so with our threads: all but one of them are waiting
for a mutex.

Re: [External] : Re: Would you say this information window is well designed?

[Dmitry Gutov]

On 23.02.2021 20:26, Eli Zaretskii wrote:
>> Date: Tue, 23 Feb 2021 17:59:08 +0000
>> From: Peter Dean <laszlomail@protonmail.com>
>> Cc: "drew.adams@oracle.com" <drew.adams@oracle.com>, "stefankangas@gmail.com" <stefankangas@gmail.com>, "larsi@gnus.org" <larsi@gnus.org>, "dgutov@yandex.ru" <dgutov@yandex.ru>, "emacs-devel@gnu.org" <emacs-devel@gnu.org>
>>
>> Then there could be a refresh rate value (e.g. 15 ms or some other value,
>> configurable) and thread-yield could check if the main thread got the lock
>> within this time window.
>>
>> If not then it would give the lock explicitly to the main thread, otherwise
>> the next thread gets the lock.
> 
> thread-yield runs in the context of the thread that yields.  You make
> it sound like there's some entity other than the involved threads
> which runs thread-yield, but that's not what happens.

It was also my impression that the threading facility in Emacs is 
incomplete.

For one thing, error handling is very low-level (saving only the last 
error looks like a straight translation from C).

Another: there is no 'thread-resume' which some came to expect from 
other languages. Examples:

https://ruby-doc.org/core-2.5.0/Fiber.html#method-i-resume
https://github.com/laverdet/node-fibers ("run() will start execution of 
this Fiber, or if it is currently yielding
  * it will resume execution")

But it seems we can substitute with condition-wait (in the worker 
thread) + condition-notify (in an idle timer which it would create 
before waiting). That should help suspend-resume the worker thread on a 
regular basis, all the while giving the main thread the time to do its 
thing.

Either way, I don't think this can solve the original issue. Having a 
link appear only some time after a Help buffer is shown is not a great 
experience either: blinking elements are a visual nuisance. So if we 
could pre-index the manual for symbols, that would be preferable.

Re: [External] : Re: Would you say this information window is well designed?

[Eli Zaretskii]

> Cc: drew.adams@oracle.com, stefankangas@gmail.com, larsi@gnus.org,
>  emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sat, 27 Feb 2021 23:44:18 +0200
> 
> > thread-yield runs in the context of the thread that yields.  You make
> > it sound like there's some entity other than the involved threads
> > which runs thread-yield, but that's not what happens.
> 
> It was also my impression that the threading facility in Emacs is 
> incomplete.

Nothing in Emacs is ever complete.

> For one thing, error handling is very low-level (saving only the last 
> error looks like a straight translation from C).

Patches welcome.  The original version didn't provide even that
rudimentary error handling.

> Another: there is no 'thread-resume' which some came to expect from 
> other languages.

IMO, thread-resume makes no sense when only one thread can run at a
time.

We could instead add an optional argument to thread-yield, with the
effect that the calling thread would yield to the thread specified by
the argument.

> But it seems we can substitute with condition-wait (in the worker 
> thread) + condition-notify (in an idle timer which it would create 
> before waiting). That should help suspend-resume the worker thread on a 
> regular basis, all the while giving the main thread the time to do its 
> thing.

I encourage you (and everyone else) to try to come up with a real-life
application that uses this paradigm, and see if it works well.  The
original design didn't intend for this to become the main paradigm,
but that doesn't mean it cannot work well.

> Either way, I don't think this can solve the original issue. Having a 
> link appear only some time after a Help buffer is shown is not a great 
> experience either: blinking elements are a visual nuisance. So if we 
> could pre-index the manual for symbols, that would be preferable.

I tend to agree.

Re: [External] : Re: Would you say this information window is well designed?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > It was also my impression that the threading facility in Emacs is 
  > > incomplete.

  > Nothing in Emacs is ever complete.

Some things are tentatively complete.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

RE: [External] : Re: Would you say this information window is well designed?

[Drew Adams]

Anyway, my point was really to say that I don't
find Info-lookup-symbol to be slow, especially
if only manuals Emacs and Elisp are used.

There are tradeoffs, of course.  Which is why
there's an option.  As you see from the doc,
one choice can be costly.  Other choices are
less costly.

The cheapest (quickest) is to create the link
for just Emacs and Elisp, and to do so
unconditionally.  That makes sense as the default
behavior.  The doc tells users what the behavior
is and gives them the choice.  With the default
choice, yes, they will see a link and sometimes
clicking it may only tell them nothing is found.

The text introducing the link is different for
the cases where it's shown unconditionally (and
so may sometimes just tell you sorry) - "check
the manuals" - versus the cases where it's shown
only when there definitely is a target - "see
the manuals".

(The help I showed in my first message about
this explained all of this.)

Re: [External] : Re: Would you say this information window is well designed?

[Lars Ingebrigtsen]

Stefan Kangas <stefankangas@gmail.com> writes:

> That's what happens with "helpful.el", and it doesn't make for the best
> experience when the function is not in any manual.  It would be better
> to not show a link in that case.

Yes, making symbols into links that go nowhere is an awful design, so
the lookup has to be done before the buttonizing. 

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

RE: [External] : Re: Would you say this information window is well designed?

[Drew Adams]

> Yes, making symbols into links that go nowhere is an awful
> design, so the lookup has to be done before the buttonizing.

No, not necessarily; not IMHO.  There is no such
"has to be done".  _That_ is "an awful design",
AFAICT.

Users should themselves be able to decide this.
They're the ones who should decide what "has to
be done", and when.

In the design I use (one example; I don't claim
there is no better approach):

* A user can choose to never provide such links.

* Otherwise:

  . If a user doesn't want to pay a time penalty
    of finding out beforehand whether a given
    symbol is actually covered in (some set of)
    manuals (the set being decidable by the user),
    the action of the link is called out as
    _checking_ for the symbol in the manuals.
    IOW, the link is, in effect, a _search_ link.

  . If a user wants to pay a penalty of checking
    beforehand, a link is created only if a target
    is known.

Your "has to" approach seems to amount to that
last possibility: no link unless we're sure it
can take you to a relevant node of a manual.

IMHO, that's the _least_ useful of all the
possibilities we can (and I do) offer users.

RE: [External] : Re: Would you say this information window is well designed?

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> In the design I use (one example; I don't claim
> there is no better approach):
>
> * A user can choose to never provide such links.
>
> * Otherwise:
>
>   . If a user doesn't want to pay a time penalty
>     of finding out beforehand whether a given
>     symbol is actually covered in (some set of)
>     manuals (the set being decidable by the user),
>     the action of the link is called out as
>     _checking_ for the symbol in the manuals.
>     IOW, the link is, in effect, a _search_ link.
>
>   . If a user wants to pay a penalty of checking
>     beforehand, a link is created only if a target
>     is known.

That sounds like a reasonable way to work around the performance impact.

Another way to solve this is to remove the performance impact.  Then the
user don't have to make any choice: the link is shown when its relevant.

(We could still make showing the link optional, of course, if we think
some users will want to disable it.)

RE: [External] : Re: Would you say this information window is well designed?

[Drew Adams]

> That sounds like a reasonable way to work around the performance
> impact.
> 
> Another way to solve this is to remove the performance impact.  Then
> the user don't have to make any choice: the link is shown when its
> relevant.

Sure, that would of course be welcome.

Re: Would you say this information window is well designed?

[Stefan Kangas]

Peter Dean <laszlomail@protonmail.com> writes:

> The package Helpful improves the default Help look. Some ideas
> for coloring and formatting could be borrowed from it to make the
> default mode more appealing, less spartan:
>
>     https://raw.githubusercontent.com/Wilfred/helpful/master/screenshots/helpful.png

I have tried it before and think there are definitely some good ideas
there.  However, with everything enabled by default it can be a little
bit overpowering (and there are few customization options).

Anyone can install it from MELPA and try it out to see it in action.
Unfortunately it is not on GNU ELPA.  :-/

Obviously this will have no font-locking but see below the full output
of `M-x helpful-function RET describe-package RET':

---

describe-package is an autoloaded, interactive and natively compiled
function defined in package.el.

Signature
(describe-package PACKAGE)

Documentation
Display the full documentation of PACKAGE (a symbol).

View in manual

Key Bindings
ehelp-map P
global-map <help> P
global-map C-h P
help-map P

References
References in package.el:
(defun describe-package ...)              1 reference
(defun describe-package-1 ...)            1 reference
(defun package-install-button-action ...) 1 reference
(defun package-delete-button-action ...)  1 reference
(defun package-menu-describe-package ...) 1 reference

Find all references Find callees

Debugging
Enable edebug Enable tracing
Disassemble Forget

Source Code
;; Defined in ~/wip/emacs-nativecomp/lisp/emacs-lisp/package.el
;;;; Package description buffer.

;;;###autoload
(defun describe-package (package)
  "Display the full documentation of PACKAGE (a symbol)."
  (interactive
   (let* ((guess (or (function-called-at-point)
                     (symbol-at-point))))
     (require 'finder-inf nil t)
     ;; Load the package list if necessary (but don't activate them).
     (unless package--initialized
       (package-initialize t))
     (let ((packages (append (mapcar #'car package-alist)
                             (mapcar #'car package-archive-contents)
                             (mapcar #'car package--builtins))))
       (unless (memq guess packages)
         (setq guess nil))
       (setq packages (mapcar #'symbol-name packages))
       (let ((val
              (completing-read (format-prompt "Describe package" guess)
                               packages nil t nil nil (when guess
                                                        (symbol-name guess)))))
         (list (and (> (length val) 0) (intern val)))))))
  (if (not (or (package-desc-p package) (and package (symbolp package))))
      (message "No package specified")
    (help-setup-xref (list #'describe-package package)
                     (called-interactively-p 'interactive))
    (with-help-window (help-buffer)
      (with-current-buffer standard-output
        (describe-package-1 package)))))

Symbol Properties
autoload
  ("package" 1474660 t nil)
event-symbol-element-mask
  (describe-package 0)
event-symbol-elements
  (describe-package)
modifier-cache
  ((0 . describe-package))