Re: Accessibility of man pages

[Dirk Gouders <dirk@gouders.net>]

Dirk Gouders <dirk@gouders.net> writes:

> 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.

Hmm, I already learned that I have all those commands available with an
'm' prefixed, i.e. mapropos, mman, mmakewhatis...

So, I built the makewhatis databases:

# find / -name mandoc.db -ls
   659416      4 -rw-r--r--   1 root     root         3984 Apr  9 12:25 /usr/lib/rust/1.66.1/share/man/mandoc.db
   659419      8 -rw-r--r--   1 root     root         4456 Apr  9 12:25 /usr/lib/llvm/15/share/man/mandoc.db
   954004   1812 -rw-r--r--   1 root     root      1848712 Apr  9 12:25 /usr/share/man/mandoc.db
   954003      4 -rw-r--r--   1 root     root         1864 Apr  9 12:24 /usr/share/binutils-data/x86_64-pc-linux-gnu/2.39/man/mandoc.db
   787032      4 -rw-r--r--   1 root     root         1164 Apr  9 12:24 /usr/share/gcc-data/x86_64-pc-linux-gnu/12/man/mandoc.db
      732     12 -rw-r--r--   1 root     root         8444 Apr  9 12:24 /usr/lib64/icedtea8/man/mandoc.db

But your example query gives not matches:

$ mman -k any=RLIMIT_NOFILE
mman: nothing appropriate

It's very fast, though:

real 0.00
user 0.00
sys 0.00

;-)

Dirk