Re: Accessibility of man pages

[Dirk Gouders]

Hi Ingo,

Ingo Schwarze <schwarze@usta.de> writes:
> Dirk Gouders wrote on Sat, Apr 08, 2023 at 10:59:32PM +0200:
>> Ingo Schwarze <schwarze@usta.de> writes:
>>> Dirk Gouders wrote on Sat, Apr 08, 2023 at 09:48:13PM +0200:
>
>>>> Yes, it's very slow but close to `man -K`:
>>>> 
>>>> find...             man -K...
>>>> 
>>>> real 107.45         real 96.34
>>>> user 117.06         user 70.11
>>>> sys 14.43           sys 26.86
>>>> 
>>>> [a thought later]
>>>> 
>>>> Oh, I found something much faster:
>>>> 
>>>> $ time -p find /usr/share/man -type f | xargs bzgrep -l RLIMIT_NOFILE
>>>> [snip]
>>>> 
>>>> real 24.30
>>>> user 32.34
>>>> sys 6.84
>>>> 
>>>> Hmm, perhaps, someone has an explanation for this?
>
>>> These are all terribly slow IMHO.
>>>
>>> For comparison, this happens on my OpenBSD notebook, with more than
>>> five hundred optional software packages installed in addition to the
>>> complete default installation:
>>>
>>>    $ time man -k any=RLIMIT_NOFILE
>>>   dup, dup2, dup3(2) - duplicate an existing file descriptor
>>>   getrlimit, setrlimit(2) - control maximum system resource consumption
>>>   sudoers(5) - default sudo security policy plugin
>>>     0m00.21s real     0m00.00s user     0m00.03s system
>
>> Yes, this is really fast and would allow for quite interesting ways to
>> work with manual pages.
>> 
>> But, OpenBSD's `man -k` operates on a makewhatis(8) database and not
>> on every single manual page or am I wrong?
>
> Yes, you are completely correct about that.
> The database format is documented here:
>
>   https://man.openbsd.org/mandoc.db.5
>
> And the search syntax here:
>
>   https://man.openbsd.org/apropos.1
>
> The concept works very well because in contrast to man(7), mdoc(7)
> provides substatial semantic markup (without being harder to write
> or maintain).
>
> The comparison seemed relevant to me because as far as i understood the
> intention of the thread, participants were looking for ideas to make
> searching for content in manual pages more powerful and more efficient.
> The combination of semantic markup and indexing of marked up content
> is one way to make progress in that direction, and the combination
> of mdoc(7) with mandoc(1) is an example of a system demonstrating
> the concept.

Very interesting.  I gues that makewhatis(8) then has to cope both
formats (man(7) and mdoc(7)) and from between the lines I read that it
is not really a problem.

Are there any outstanding queries mdoc(7) enables that man(7) cannot?
>From what I read so far with mdoc(7) it should be very easy (by querying
.Xr), for example to get an answer to the question "Which manual pages
are referencing me?" (From inside a pager, for example).

> I understand people familiar with GNU info(1) pointed out that
> providing index entries that do not correspond to marked up
> content is also occasionally useful.  I do not completely disagree
> with that, and the mdoc(7) language as implemented by mandoc(1)
> provides a dedicated macro to do just that:
>
>   https://man.openbsd.org/mdoc.7#Tg

My role in this thread is not an experts one but the one of a naive guy
who plays with an experimental pager (lsp(1)) that tries to offer some
additional features for handling manual pages.

I read that with .Tg tags are passed to the PAGER and with less(1) one
could use :t to navigate to them.  I tried to see how this works and
wonder how the user knows which tags are available -- maybe man-db's
man(1) doesn't support this...

If your time allows and it's not too off-topic, perhaps you could
provide more detail, e.g. if I can make use of the .Tg tags on a
non-OpenBSD system.

Regards,

Dirk