Hi James,
James K. Lowden wrote on Sat, May 29, 2021 at 06:01:52PM -0400:
> how indexes could be implemented in
That problem was solved in 2016, and five years of experience have
shown the solution works well.
https://man.openbsd.org/mandoc.db
> then man(1) might be adapted to use it,
It already is. Try
man -O tag=set ksh
on a system running a reasonably recent (less than two years old)
version of the mandoc implementation of man(1).
By the way, the same tags that man(1) reaches with -O tag
can be navigated to on the web as well:
https://man.openbsd.org/ksh#set~2
Imagine the noise trying to search by typing "/set" in less(1)...
> and then man page authors woud have cause to designate indexed terms.
Five years of experience show there is surprisingly little need for
that. The mandoc implementation of deep linking to anchors fully
automated the task without requiring any additional markup. In
practice, it just works without needing to bother the author, just
regular semantic markup is sufficient without adding manual anchors,
in the vast majority of cases.
All the same, the mdoc(7) language did recently start supporting
manual tagging for the very small fraction of situations where it
helps, and for the relatively few authors who are willing to go to
such lengths:
https://man.openbsd.org/mdoc#Tg~2
> 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".
That's not the state of the art.
Mandoc has been doing semantic searching since about 2004:
https://man.openbsd.org/apropos#Macro_Keys
https://man.openbsd.org/apropos#EXAMPLES
I often use queries akin to
man -ks 2 Vt=timespec
when i wonder which system calls deal with the "struct timespec"
data type. And the like - you get the picture.
> 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.
Yes, the mandoc implementation of man(1) has been doing exactly that
for years.
> I would bet it's technically feasible to use "one giant tags file",
> indexing the whole man-page corpus.
Well, actually, you get one mandoc.db(5) file per manual page tree,
so for example if you have your base system in /usr/, your ports and
packages in /usr/local/ and your X11 in /usr/X11R6/, then you get
/usr/share/man/mandoc.db
/usr/local/man/mandoc.db
/usr/X11R6/man/mandoc.db
and man(1) transparently knows how to use those.
If you have specialised collections of manual pages installed,
you may also have files like
/usr/local/lib/tcl/tcl8.5/man/mandoc.db
/usr/local/plan9/man/mandoc.db
/usr/local/share/doc/posix/man/mandoc.db
/usr/local/lib/eopenssl11/man/mandoc.db
such that these don't get confused with native system documentation
but can be accessed when desired using the -M option or the MANPATH
environment variable.
> 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
>
>
> and
> .
It has: .Tg
Only, it has not yet been implemented in groff.
Then again, it is very rarely needed.
The OpenBSD base system currently contains 82 instances of .Tg
in its 3325 mdoc manual pages, so on average one every fourty pages.
> Possible ways to denote a target in mdoc:
>
> 1. Extend .Lk to denote a target
> 2. Introduce a new macro, perhaps .Ix
Please, do not reinvent what is already in production and working well
for years.
> 1. If grotty produced etags output, less(1) could support navigation
> by "man page tags".
The mandoc implemention of man(1) has already been doing exactly
that for years. And the tags you can access with less(1) :t are
more or less the same that you can navigate to on the web using
fragment identifiers.
> 3. If the above two were accomplished, man page authors would finally
> have the opportunity to enhance their documents with index anchors.
Little need to, it mostly just works without providing manual anchors.
> IMO hyperlink nonsupport is the Achilles heel of the man page system.
Maybe it was a decade ago.
All that said, specific suggestions to improve the system are always
welcome, and so are patches. During the last decade, i have
received useful suggestions from probably more than a hundred
people, and patches from probably more than twenty, too.
To name just one person who helped move tagging and indexing support
forward even further recently: Klemens Nanni provided valuable input
on several occasions, but others helped, too. And of course
