WAYTO: indexed man pages

[James K. Lowden]

gromunity: 

In working with my GUI man page viewer (not ready for its first
audition yet) I found myself asking how indexes could be implemented in
current and future man systems, and what groff would have to produce
for a viewer to provide an index affordance. What follows is my
analysis of where we are, and a few suggestions on where we might go.
I'm hoping for better ideas and a sense of the senate.  

I think this is a "build it and they will come" situation.  If groff
did "something" to support indexed access, then man(1) might be
adapted to use it, and then man page authors woud have cause to
designate indexed terms. I would also suggest that any hyperlink
support provided by groff for man pages would add fuel to the budding
support for OSC 8 hyperlinks not just in terminal emulators, but
eventually in GNU less, too.  

Deri achieved one technical milestone some years ago: 

        http://chuzzlewit.co.uk/WebManPDF.pl/man:/1/bash

If your PDF viewer supports a table of contents, that page is a joy
to behold.  But to my knowledge, PDF doesn't support the concept of "an
index" per se. An index in a PDF file is just a list of terms and links
into the document that happens to appear near the end.  

The best "find term by index" feature in documentation viewing software
isn't very good: in the info viewer, you can type " i " and a string,
and enter.   It also supports tab-completion on indexed terms, which is
as close as info ever comes to "very cool".  

The nearest thing in less(1) to support for an index would be its tag
support. If groff emitted a tags file, less could use it to navigate
within the man page.  

I would bet it's technically feasible to use "one giant tags file",
indexing the whole man-page corpus.  (groff_mdoc mentions IND for a
"master index".  I don't think I've ever seen such a thing in real
life.  Can anyone shed light on how/if/when that was used?)  

There is the, ahem,  *slight* problem of how to denote index anchors,
i.e., locations in the document that the index "points at" for a term
included in the index. Currently in mdoc we have only "points to"
macros:

        .Sx point to a heading
        .Xr point to a page
        .Lk point to a URL (mandoc)

IOW mdoc has nothing akin to the HTML functionality 

        <a href=#foo>
and
        <span id="foo">.  

Possible ways to denote a target in mdoc: 

1.  Extend .Lk to denote a target
2.  Introduce a new macro, perhaps .Ix

Summing up: 

1.  If grotty produced etags output, less(1) could support navigation
by "man page tags". 

2.  If mdoc supported to/from hyperlink macros (links and anchors),
they could produce escapes for grotty and gropdf. 

3.  If the above two were accomplished, man page authors would finally
have the opportunity to enhance their documents with index anchors. 

IMO hyperlink nonsupport is the Achilles heel of the man page system.
The above description is the simplest I have come up with to extend the
existing system in a noninvasive, nonsystemd way.  

What say you?  

--jkl