bug#54175: 27.2; Info-follow-reference completions in reverse order

bug#54175: 27.2; Info-follow-reference completions in reverse order

[Howard Melman]

This is the same issue as in bug#38614 which was about
Info-complete-menu-item, but this is about
Info-follow-reference.  I hope it will also be fixed.

Info-follow-reference calls completing-read with a list of
candidates found in the node.  It scans the node from top to
bottom pushing references onto a completions list.  The list
ends up being in the reverse order of position in the node.
For the default completion mechanism this isn't a problem,
but with a completion package like fido or ivy which
immediately displays the list of candidates, this order
isn't particularly useful.

My use case is browsing an info manual, going to a new node
via n, so my point is near the top of the node.  I see I
want to follow the first reference and type f and I'm
presented with a list of completion candidates. The first
candidate is from the bottom of the node, it's not even
visible on my screen.  If the list was in the order as found
in the mode I could just type RET, but now I have to type to
complete or beforehand position point at the reference so
that it will be used as a default.

I suggest adding something like the following in
Info-follow-reference just after the while loop that builds
completions:

     (setq completions (nreverse completions))

I saw this on the macport of Emacs 27.2 but the code on
master looks to me to be the same.

Howard

In GNU Emacs 27.2 (build 1, x86_64-apple-darwin20.6.0, Carbon Version 164 AppKit 2022.6)
of 2021-11-16 built on Mac-1637103180448.local
System Description:  macOS 11.6.4

bug#54175: 27.2; Info-follow-reference completions in reverse order

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Sat, 26 Feb 2022 19:17:21 -0500
> 
> This is the same issue as in bug#38614 which was about
> Info-complete-menu-item, but this is about
> Info-follow-reference.  I hope it will also be fixed.
> 
> Info-follow-reference calls completing-read with a list of
> candidates found in the node.  It scans the node from top to
> bottom pushing references onto a completions list.  The list
> ends up being in the reverse order of position in the node.
> For the default completion mechanism this isn't a problem,
> but with a completion package like fido or ivy which
> immediately displays the list of candidates, this order
> isn't particularly useful.
> 
> My use case is browsing an info manual, going to a new node
> via n, so my point is near the top of the node.  I see I
> want to follow the first reference and type f and I'm
> presented with a list of completion candidates. The first
> candidate is from the bottom of the node, it's not even
> visible on my screen.  If the list was in the order as found
> in the mode I could just type RET, but now I have to type to
> complete or beforehand position point at the reference so
> that it will be used as a default.
> 
> I suggest adding something like the following in
> Info-follow-reference just after the while loop that builds
> completions:
> 
>      (setq completions (nreverse completions))

I must say that I'm uneasy with such changes, which punish every user
of Info because some optional completion facility out there would like
that.  It sounds wrong.  Why shouldn't we expect from those optional
completion facilities to do this if and when they need?

bug#54175: 27.2; Info-follow-reference completions in reverse order

[Howard Melman]

On Feb 27, 2022, at 2:17 AM, Eli Zaretskii <eliz@gnu.org> wrote:

> I must say that I'm uneasy with such changes, which punish every user
> of Info because some optional completion facility out there would like
> that.  It sounds wrong.  Why shouldn't we expect from those optional
> completion facilities to do this if and when they need?

1. I understand your "who has the burden" argument but the cost of 
reversing a list of a handful of items is hardly punishment. And I 
explained my use case which for a user means fewer keystrokes
in a common case (visit the first reference without having to navigate
to it or type it's name) which seems far more meaningful than a 
negligible cost in other cases.

2. It's not unreasonable to expect a completion table to be in a meaningful 
order when there is one.  And there's no way for a completion package to
generate this order unless it assumes the candidates of this command are
in this reverse order, which isn't part of the contract.

3. Why should other completions facilities, some of which ship with emacs, 
be punished because the default one decides to not show any candidates
without first sorting them after someone hits TAB?

Howard

bug#54175: 27.2; Info-follow-reference completions in reverse order

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Sun, 27 Feb 2022 10:43:49 -0500
> 
> On Feb 27, 2022, at 2:17 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> > I must say that I'm uneasy with such changes, which punish every user
> > of Info because some optional completion facility out there would like
> > that.  It sounds wrong.  Why shouldn't we expect from those optional
> > completion facilities to do this if and when they need?
> 
> 1. I understand your "who has the burden" argument but the cost of 
> reversing a list of a handful of items is hardly punishment.

It doesn't have to be a handful, though.  Large manuals, such as
Emacs and ELisp, have some large nodes with many cross-references.
For example, see the Glossary node.

bug#54175: 27.2; Info-follow-reference completions in reverse order

[Howard Melman]

> On Feb 27, 2022, at 11:36 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Howard Melman <hmelman@gmail.com>
>> Date: Sun, 27 Feb 2022 10:43:49 -0500
>> 
>> On Feb 27, 2022, at 2:17 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> 
>>> I must say that I'm uneasy with such changes, which punish every user
>>> of Info because some optional completion facility out there would like
>>> that.  It sounds wrong.  Why shouldn't we expect from those optional
>>> completion facilities to do this if and when they need?
>> 
>> 1. I understand your "who has the burden" argument but the cost of 
>> reversing a list of a handful of items is hardly punishment.
> 
> It doesn't have to be a handful, though.  Large manuals, such as
> Emacs and ELisp, have some large nodes with many cross-references.
> For example, see the Glossary node.

I mean if this is the degenerate case... the Emacs 27.2 manual 
glossary has 182 references:

    (setq strlist (make-list 182 "Some String"))
    (benchmark-run 1000 (setq strlist (nreverse strlist)))
    (0.00032399999999999996 0 0.0)

This is not a function that will be typically be called in by code, this is
"cost" will essentially always be paid during an interactive command
done occasionally while the user is reading.  Not doing this for performance
reasons seems like a pointless micro-optimization.

Howard

bug#54175: 27.2; Info-follow-reference completions in reverse order

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Sun, 27 Feb 2022 10:43:49 -0500
> 
> 2. It's not unreasonable to expect a completion table to be in a meaningful 
> order when there is one.

But what is a meaningful order in this particular case, why is it
more meaningful than the current order?

bug#54175: 27.2; Info-follow-reference completions in reverse order

[Howard Melman]

On Feb 27, 2022, at 11:49 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Howard Melman <hmelman@gmail.com>
>> Date: Sun, 27 Feb 2022 10:43:49 -0500
>> 
>> 2. It's not unreasonable to expect a completion table to be in a meaningful 
>> order when there is one.
> 
> But what is a meaningful order in this particular case, why is it
> more meaningful than the current order?

I believe I explained this.  It is the order they are found in the node. It means 
the offered candidates appear to me in the order I see them in the node.  I think
it was probably more meaningful in the other bug (#38614) as that affected the
order of menu items which are closer together, but this is similar.

And as I explained (and you elided), it provides a meaning interactive experience:

> And I explained my use case which for a user means fewer keystrokes

> in a common case (visit the first reference without having to navigate

> to it or type it's name) which seems far more meaningful than a 

> negligible cost in other cases.

Howard

bug#54175: 27.2; Info-follow-reference completions in reverse order

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Sun, 27 Feb 2022 11:59:35 -0500
> 
> On Feb 27, 2022, at 11:49 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> > 
> >> From: Howard Melman <hmelman@gmail.com>
> >> Date: Sun, 27 Feb 2022 10:43:49 -0500
> >> 
> >> 2. It's not unreasonable to expect a completion table to be in a meaningful 
> >> order when there is one.
> > 
> > But what is a meaningful order in this particular case, why is it
> > more meaningful than the current order?
> 
> I believe I explained this.  It is the order they are found in the node. It means 
> the offered candidates appear to me in the order I see them in the
> node.

But if your position is near the end of the buffer, the first
cross-reference in the node will also be the one that's the farthest.
I'm not sure I understand the utility of such an order.

bug#54175: 27.2; Info-follow-reference completions in reverse order

[Howard Melman]

> On Feb 27, 2022, at 12:09 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Howard Melman <hmelman@gmail.com>
>> Date: Sun, 27 Feb 2022 11:59:35 -0500
>> 
>> On Feb 27, 2022, at 11:49 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>>> 
>>>> From: Howard Melman <hmelman@gmail.com>
>>>> Date: Sun, 27 Feb 2022 10:43:49 -0500
>>>> 
>>>> 2. It's not unreasonable to expect a completion table to be in a meaningful 
>>>> order when there is one.
>>> 
>>> But what is a meaningful order in this particular case, why is it
>>> more meaningful than the current order?
>> 
>> I believe I explained this.  It is the order they are found in the node. It means 
>> the offered candidates appear to me in the order I see them in the
>> node.
> 
> But if your position is near the end of the buffer, the first
> cross-reference in the node will also be the one that's the farthest.
> I'm not sure I understand the utility of such an order.

It doesn't help in all cases.  If you're positioned near the end of the node
then you might be positioned near the reference and get it as the default.
But when visiting a node you start at the top, and many nodes fit entirely
on one screen, so it's a more common case that it will help (again for a
imperceptible cost).  It's certainly a more intuitive order than what is returned
now.

Howard

bug#54175: 27.2; Info-follow-reference completions in reverse order

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Sun, 27 Feb 2022 12:18:49 -0500
> 
> >> I believe I explained this.  It is the order they are found in the node. It means 
> >> the offered candidates appear to me in the order I see them in the
> >> node.
> > 
> > But if your position is near the end of the buffer, the first
> > cross-reference in the node will also be the one that's the farthest.
> > I'm not sure I understand the utility of such an order.
> 
> It doesn't help in all cases.  If you're positioned near the end of the node
> then you might be positioned near the reference and get it as the default.
> But when visiting a node you start at the top, and many nodes fit entirely
> on one screen, so it's a more common case that it will help (again for a
> imperceptible cost).  It's certainly a more intuitive order than what is returned
> now.

I don't think I agree.  I could understand if the request was to order
them starting from the current position, or to sort them by their
distance from the current position, but starting from the node
beginning sounds as arbitrary as starting from the end.

In any case, instead of sorting or reversing, an alternative could be
to collect the cross-reference in the desired order to begin with, to
avoid the cost of sorting/reversing.

And finally, Info-follow-reference is called by other functions, so we
should make sure we don't break them by changing the order.

bug#54175: 27.2; Info-follow-reference completions in reverse order

[Howard Melman]

On Feb 27, 2022, at 12:31 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Howard Melman <hmelman@gmail.com>
>> Date: Sun, 27 Feb 2022 12:18:49 -0500
>> 
>>>> I believe I explained this.  It is the order they are found in the node. It means 
>>>> the offered candidates appear to me in the order I see them in the
>>>> node.
>>> 
>>> But if your position is near the end of the buffer, the first
>>> cross-reference in the node will also be the one that's the farthest.
>>> I'm not sure I understand the utility of such an order.
>> 
>> It doesn't help in all cases.  If you're positioned near the end of the node
>> then you might be positioned near the reference and get it as the default.
>> But when visiting a node you start at the top, and many nodes fit entirely
>> on one screen, so it's a more common case that it will help (again for a
>> imperceptible cost).  It's certainly a more intuitive order than what is returned
>> now.
> 
> I don't think I agree.  I could understand if the request was to order
> them starting from the current position, or to sort them by their
> distance from the current position, but starting from the node
> beginning sounds as arbitrary as starting from the end.
> 
> In any case, instead of sorting or reversing, an alternative could be
> to collect the cross-reference in the desired order to begin with, to
> avoid the cost of sorting/reversing.

I proposed an easy-to-understand one line fix with negligible performance
impact similar to a previously accepted fix; if someone wants to fix it with
a rewrite of the function I don't object.

> And finally, Info-follow-reference is called by other functions, so we
> should make sure we don't break them by changing the order.

Yes, though given my proposed change is in the call to interactive I believe
it shouldn't affect other non-interactive callers of it.

There is code in Info-menu-update "stolen from `Info-follow-reference'" that builds
the dynamic submenu of References.  That currently shows references, in the menu
in the same reverse order.  It would be nice if those were in some sensible order; either
alphabetical or as found in the node seem more reasonable than what's there now.

Howard

bug#54175: 27.2; Info-follow-reference completions in reverse order

[Howard Melman]

To follow up on this from Feb.  Here's a summary of
what's been discussed.  My original report:

> This is the same issue as in bug#38614 which was about
> Info-complete-menu-item, but this is about
> Info-follow-reference.  I hope it will also be fixed.
>
> Info-follow-reference calls completing-read with a list of
> candidates found in the node.  It scans the node from top to
> bottom pushing references onto a completions list.  The list
> ends up being in the reverse order of position in the node.
> For the default completion mechanism this isn't a problem,
> but with a completion package like fido or ivy which
> immediately displays the list of candidates, this order
> isn't particularly useful.
>
> My use case is browsing an info manual, going to a new node
> via n, so my point is near the top of the node.  I see I
> want to follow the first reference and type f and I'm
> presented with a list of completion candidates. The first
> candidate is from the bottom of the node, it's not even
> visible on my screen.  If the list was in the order as found
> in the mode I could just type RET, but now I have to type to
> complete or beforehand position point at the reference so
> that it will be used as a default.
>
> I suggest adding something like the following in
> Info-follow-reference just after the while loop that builds
> completions:
>
>      (setq completions (nreverse completions))
>

Eli argued that this would put a burden on users who stick
with the default completion system.  I showed that his example
degenerate case had no meaningful performance impact.

He also asked why is this order more meaningful.  It seems
obvious to me that the order the references appear in the
text is more meaningful than the reverse of that order.  And I
showed a common use case of visiting a page and wanting
to follow one of the first references without having to move point,
particularly if the node fits on one page.

Eli proposed some different order could be more useful.  I said "I
proposed an easy-to-understand one line fix with negligible
performance impact similar to a previously accepted fix; if someone
wants to fix it with a rewrite of the function I don't object."
Additionally, I point out that this change doesn't affect that if
point is on a reference the default is still that reference.

I also pointed out:

> There is code in Info-menu-update "stolen from
> `Info-follow-reference'" that builds the dynamic submenu of
> References.  That currently shows references, in the menu in the
> same reverse order.  It would be nice if those were in some sensible
> order; either alphabetical or as found in the node seem more
> reasonable than what's there now.

I think the order of a menu is more clearly a bug than of a
completion table, but I think both should be fixed. My
preference would be that the order in a menu be the order of
references found in the text and that Info-follow-reference
candidates use the same order.  I think alphabetical is also
reasonable for this menu and could be different from
Info-follow-reference, but I don't see how it's useful for
either to be in the reverse order as found in the text.

I still think the proposed one line fix (applied in both
places) is the easiest and least risky change.

-- 

Howard

bug#54175: 27.2; Info-follow-reference completions in reverse order

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

> I still think the proposed one line fix (applied in both
> places) is the easiest and least risky change.

Yup.  I've now done so in Emacs 29.

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

bug#54175: 27.2; Info-follow-reference completions in reverse order

[Howard Melman]

On May 5, 2022, at 7:30 AM, Lars Ingebrigtsen <larsi@gnus.org> wrote:
> 
> Howard Melman <hmelman@gmail.com> writes:
> 
>> I still think the proposed one line fix (applied in both
>> places) is the easiest and least risky change.
> 
> Yup.  I've now done so in Emacs 29.

Thanks.

Howard