Add a ‘consult-info’ command.

[okamsn]

Based on ‘selectrum-info’ from the Selectrum wiki, but simplified and without cl-loop.

This goes through an Info buffer and matches against links in the table of contents.

This works well for most cases, but is a bit odd when dealing with TOCs with multiple sub levels, as seen in the following images. I'd prefer that child nodes immediately follow parent nodes, but I'm not sure how to do that.

This command adds the node description (if any) to the candidate, to allow for better searching.

[minad]

This looks pretty good already! Maybe nested sections should be presented flattemed as in the imenu? There is a completing-read in the source. Please replace that with consult--read too for consistency.

How does it differ from the selectrum wiki version?

[okamsn]

Maybe nested sections should be presented flattemed as in the imenu?

I think that they should, but I don't know of a good way to do it. Do you have any ideas?

For example, below is the contents of an Info buffer. The challenge is that I don't know how guaranteed the formatting is. It looks like each sub-node in a node is listed, and then the contents of each sub-node. It would be easy with something like Org or Markdown, but there isn't much formatting information to work with in an Info buffer.

* Menu:

* Introduction::
* How to use::
* Adding Custom Commands::
* How does it compare to cl-loop?::
* Real-World Examples::

— The Detailed Node Listing —

How to use

* Macro Arguments::
* Loop Commands::

Loop Commands

* Commands for Generic Evaluation::
* Iteration and Looping Commands::
* Accumulation Commands::
* Control Flow::

Control Flow

* Conditionals::
* Skipping an Iteration::
* Exiting the Loop Early::

There is a completing-read in the source. Please replace that with consult--read too for consistency.

Fixed.

How does it differ from the selectrum wiki version?

It differs in the following ways:

• No cl-loop.
• No selectrum-specific code. It instead uses a normal alist of candidates for completing sub-sections. Node descriptions are not annotations but part of the candidate.
• Only consult-info performs completion. The other functions only produce candidates.
• No code to handle window placement. Only the command info is used, never info-other-window.

[minad]

I think that they should, but I don't know of a good way to do it. Do you have any ideas?

I wonder how you extract the headlines right now such that it is reliable. Why is it not possible to extract all the headlines as some kind of nested datastructure and then flatten it afterwards?

Thank you for the changes and the further explanations!

[okamsn]

I think that they should, but I don't know of a good way to do it. Do you have any ideas?

I wonder how you extract the headlines right now such that it is reliable. Why is it not possible to extract all the headlines as some kind of nested datastructure and then flatten it afterwards?

Right now, the function consult--info-section-candidates just searches for links in what happens to be the table of contents for the Info buffer. It relies on the fact that links are formatted like \* LINK-NAME::(DESCRIPTION)?\n, where DESCRIPTION can span multiple lines.

From what I can tell (though I am not very familiar with the Info format), I don't think that there is any tree structure available, just a flat list of links.

[minad]

From what I can tell (though I am not very familiar with the Info format), I don't think that there is any tree structure available, just a flat list of links.

What I meant is - if there is a nested list like this:

* section1
** subsection1
** subsection2
* section2
** subsection

we can fold it to section1 > subsection1, section1 > subsection2, ... But I am making this up, is this not how the format looks unfortunately.

---

I tried the following org file:

* section1
** sub1.1
*** subsub1.1.1
*** subsub1.1.2
** sub1.2
*** subsub1.2.1
*** subsub1.2.1
* section2
** sub2.1
*** subsub2.1.1
*** subsub2.1.2
** sub2.2
*** subsub2.2.1
*** subsub2.2.1

and this is what I got, there is the flat menu and the detailed node listing. Seems not too hard to parse, however I am not sure how stable this format is. And in the end there is this tag table?

This is test.info, produced by makeinfo version 6.5 from test.texi.

�
File: test.info,  Node: Top,  Next: section1,  Up: (dir)

* Menu:

* section1::
* section2::

 The Detailed Node Listing 

section1

* sub1.1: sub11.
* sub1.2: sub12.

sub1.1

* subsub1.1.1: subsub111.
* subsub1.1.2: subsub112.

sub1.2

* subsub1.2.1: subsub121.
* subsub1.2.1: subsub121 (1).

section2

* sub2.1: sub21.
* sub2.2: sub22.

sub2.1

* subsub2.1.1: subsub211.
* subsub2.1.2: subsub212.

sub2.2

* subsub2.2.1: subsub221.
* subsub2.2.1: subsub221 (1).


�
File: test.info,  Node: section1,  Next: section2,  Prev: Top,  Up: Top

1 section1
**********

* Menu:

* sub1.1: sub11.
* sub1.2: sub12.

�
File: test.info,  Node: sub11,  Next: sub12,  Up: section1

1.1 sub1.1
==========

* Menu:

* subsub1.1.1: subsub111.
* subsub1.1.2: subsub112.

�
File: test.info,  Node: subsub111,  Next: subsub112,  Up: sub11

1.1.1 subsub1.1.1
-----------------

�
File: test.info,  Node: subsub112,  Prev: subsub111,  Up: sub11

1.1.2 subsub1.1.2
-----------------

�
File: test.info,  Node: sub12,  Prev: sub11,  Up: section1

1.2 sub1.2
==========

* Menu:

* subsub1.2.1: subsub121.
* subsub1.2.1: subsub121 (1).

�
File: test.info,  Node: subsub121,  Next: subsub121 (1),  Up: sub12

1.2.1 subsub1.2.1
-----------------

�
File: test.info,  Node: subsub121 (1),  Prev: subsub121,  Up: sub12

1.2.2 subsub1.2.1
-----------------

�
File: test.info,  Node: section2,  Prev: section1,  Up: Top

2 section2
**********

* Menu:

* sub2.1: sub21.
* sub2.2: sub22.

�
File: test.info,  Node: sub21,  Next: sub22,  Up: section2

2.1 sub2.1
==========

* Menu:

* subsub2.1.1: subsub211.
* subsub2.1.2: subsub212.

�
File: test.info,  Node: subsub211,  Next: subsub212,  Up: sub21

2.1.1 subsub2.1.1
-----------------

�
File: test.info,  Node: subsub212,  Prev: subsub211,  Up: sub21

2.1.2 subsub2.1.2
-----------------

�
File: test.info,  Node: sub22,  Prev: sub21,  Up: section2

2.2 sub2.2
==========

* Menu:

* subsub2.2.1: subsub221.
* subsub2.2.1: subsub221 (1).

�
File: test.info,  Node: subsub221,  Next: subsub221 (1),  Up: sub22

2.2.1 subsub2.2.1
-----------------

�
File: test.info,  Node: subsub221 (1),  Prev: subsub221,  Up: sub22

2.2.2 subsub2.2.1
-----------------


�
Tag Table:
Node: Top�69
Node: section1�543
Node: sub11�685
Node: subsub111�832
Node: subsub112�936
Node: sub12�1040
Node: subsub121�1191
Node: subsub121 (1)�1299
Node: section2�1407
Node: sub21�1537
Node: subsub211�1684
Node: subsub212�1788
Node: sub22�1892
Node: subsub221�2043
Node: subsub221 (1)�2151
�
End Tag Table

�
Local Variables:
coding: utf-8
End:

[minad]

@okamsn Note that consult-outline also works in the info buffer, so I wonder about the specific advantages of this command. If we cannot make it significantly better than that by specializing in info we should not add this here.

[okamsn]

The purpose of the consult-info command is more like info-lookup-symbol then it is like consult-outline. It is like an info-lookup-node command, for immediately opening a node in an Info manual, instead of first opening the Info buffer and then jumping to a node.

I have updated the regexp to work with your example, and have copied into the code a comment from the info library, which states

Note that nowadays we expect Info files to be made using makeinfo.
In particular we make these assumptions:

• a menu item MAY contain colons but not colon-space ": "
• a menu item ending with ": " (but not ":: ") is an index entry
• a node name MAY NOT contain a colon
  This distinction is to support indexing of computer programming
  language terms that may contain ":" but not ": ".

One visual difference between consult-info and consult-outline is that the consult-info command displays the entire description, instead of just the first line. This can be seen below in how both commands display candidates for the Emacs manual.

consult-outline candidates from the Info buffer:

􀦆* Menu:
􀦏* Distrib::             How to get the latest Emacs distribution.
􀧑* Intro::               An introduction to Emacs concepts.
􀨨* Screen::              How to interpret what you see on the screen.
􀩭* User Input::          Kinds of input events (characters, buttons,
􀫛* Keys::                Key sequences: what you type to request one
􀭉* Commands::            Named functions run by key sequences to do editing.
􀮕* Entering Emacs::      Starting Emacs from the shell.

consult-info candidates, which can be used from anywhere:

Distrib - How to get the latest Emacs distribution.
Intro - An introduction to Emacs concepts.
Screen - How to interpret what you see on the screen.
User Input - Kinds of input events (characters, buttons, function keys).
Keys - Key sequences: what you type to request one editing action.
Commands - Named functions run by key sequences to do editing.
Entering Emacs - Starting Emacs from the shell.

[minad]

Thank you for the response! I will try this out soon. Then I can tell more if it is valuable to have over the default info command or consult-outline. Maybe we can make it more useful by providing a preview function too?

[minad]

Ok I tried it now, and it is good. I would definitely like to have such a command in Consult. But I would like to see a few enhancements in order to make this really a major improvement over the existing infrastructure, the info and info-goto-node commands. Both do not show any description however.

My wishlist:

1. Improved formatting of section and descriptions, align the descriptions
2. Show some description additional to the toplevel nodes if possible. This requires reading the file, but with caching and only doing it once it may not be too costly? Should be tried at least.
3. Preview of info nodes
4. Preview of toplevel pages (not as important, maybe not useful?)
5. The sections/subsections should be rendered like this: Section/Subsection or Section>Subsection. We already discussed this above - I am not sure how to do it, but the info buffer also manages to somehow format these info buffers...

Regarding the descriptions - there is also the questios if the descriptions could somehow be provided as Marginalia annotators such that they are useful also for the builtin commands (point 2 and point 3). But then the description would not be searchable without going to an Embark Collect or Completions buffer.

What do you think?

[minad]

Friendly ping @okamsn

[okamsn]

Sorry, I got caught up with work. I'm still working on this.

Getting the descriptions by opening the file was too slow, so I'm trying to get candidates from the top-level Info buffer. Many of these candidates are links to subsections within an Info document, instead of just candidates that would open a file, like the command does now. I have not yet tried caching the links on first run.

I still believe that the descriptions should be part of the candidate and not added by Marginalia

[okamsn]

Closing this PR until I have more time to work on this.

[minad]

Okay! I hope you can pick this up again!

[hmelman]

I wonder if the code to pull out the description would be better off as an annotation in marginalia? Info-complete-menu-item already sets a category info-menu that I think marginalia could key off. That way Info-menu would also benefit.

[minad]

I think I made this suggestion before, but it is not very easy since you have to parse the info files extract the description etc. In any case this will require caching and someone coming forward with a PR ;)

[minad]

Regarding the descriptions - there is also the questios if the descriptions could somehow be provided as Marginalia annotators such that they are useful also for the builtin commands (point 2 and point 3). But then the description would not be searchable without going to an Embark Collect or Completions buffer.

See above.