RFE: Page outline / navigate to subsection?

[intelfx]

It would be nice if qman could somehow extract the page structure and present an "outline view" of the page, with potential fuzzy search capability for locating a (sub)section by name.

For instance, man.archlinux.org is able to extract (sub)section titles and other items into id= attributes, which then allows easy linking and navigation to a specific manpage section or even toa a specific option or subcommand described in the man:

https://man.archlinux.org/man/tmux.1#respawn-pane

It would be useful if qman could perform a similar process and present an outline view for navigation.

To be clear, in the above example of tmux(1) man page I'm expecting a hierarchical outline view similar to the "Table of contents" at the link above, but with added subitems for each tmux subcommand:

tmux(1) ├ NAME ├ SYNOPSIS ├ ... ├ WINDOWS AND PANES │ ├ append-selection │ ├ append-selection-and-cancel │ ├ ... │ └ unlink-window ├ KEY BINDINGS │ ├ bind-key │ ├ ... │ ├ send-prefix │ └ unbind-key ├ ... └ AUTHORS

Would it be feasible to implement such a feature?

[plp13]

Hi intelfx, thanks for your suggestion.

Support for inline links to section headings is in the works. In fact, the program already supports such links in whatis/apropos pages, and in the index page. However, the way these are implemented wouldn't work for man pages without reworking the code a bit.

So, this is a feature that will definitely happen at some point.

And yes, the next logical step after that would be having some sort of searchable table of contents (and perhaps a table of links) for the entire page. Implementing this will take some effort, though.

[plp13]

I'm trying to consider the possible performance issues for this.

Currently, Qman works by retrieving the formatted manual page from man and then going through it once to discover links and blocks of text that should be highlighted. This is all currently done in a single loop.

(1) Identifying all (sub)sections and creating a table of contents for them can be done in the same loop. So, that should be OK, although it will still add several ms to processing time.

(2) Going through the text to "discover" potential internal links to the various (sub)sections would be considerably costlier, as it would require looping through the text a second time, searching for text that matches them. Having such a feature, however, would be nice. For text like "please refer to the CONFIGURATION section for more details" we'll be able to click on "CONFIGURATION" to jump there.

(3) Finally, there's the list of available languages for the manual page that man.archlinux.org also provides. I don't know if that would be useful for someone, however I suppose it could be done upon request, with the available languages appearing in a pop-up menu. That wouldn't really impact performance.

Anyway, I think I should start with (1) and take it from there.

[plp13]

I think I've made progress. Pressing t now brings a "table of contents" popup window that shows you a list of all sections, subsections, and paragraph tags in a page. Selecting an entry from this list takes you to the correct position in the page.

Beware that there are still bugs around.

Also some features are still pending:

• A list of all sections at the top of each manual page (similar to the one we have for apropos/whatis pages, and for the index page)
• Internal links to sections in the same page

It's all in the devel branch, which I encourage you to checkout and play with.

[plp13]

Feature implemented in devel branch and appears to be functioning correctly.

[intelfx]

Sorry, I just missed the previous comment here.

Indeed, works nicely with the traditional man macros (like the .TP one in ls(1)), thanks! I wonder if it could be extended to mdoc macros (.Bl/.It), like in tmux(1)?

[plp13]

Yeah, well, the .Bl/.It/El commands have a very complex syntax, and produce all sorts of lists and tables. Trying to properly handle them would take us into the realm of proper parsing (***), which goes beyond the scope of a simple utility such as Qman, IMHO.

Please note that I'm not saying that it can't be done, only that (in my opinion) it's out of scope.

While building Qman, I actually started having ideas about building a completely new and modern help system for Linux, perhaps one that is based on Markdown and incorporates modern features, such as links, tags, metadata, images/media, proper indexing, etc. And also community features, such as online editing, comments, TL/DR, and so on.

Obviously, such a system would include a full groff_man parser that would translate all the 'legacy' manual pages into the new format. But it would be an enormous undertaking, requiring community effort. Certainly not the kind of project an old dude could do by himself.

It would be useful, though. The current man system dates from the 1970s.

(***) If you think there's a way to do it more easily (and reliably) I'm all ears.