man(1): Add full search (-K) flag

[fernape]

Summary

This flag allows a full text search on man pages. Although this is a last resort
option, it can be useful to pin point a certain man page.

It can be used with -S to narrow the search.

Unlike the Linux version, the search takes place in the rendered text so it
avoids false-positives when the text is found in comments in the source files.

It relies on egrep(1) and mandoc(1) to do its job. man.sh assumes
mandoc(1) is available anyway. Errors are discarded silently. I do not see
any advantages to check the existence of the directories in MANPATH before
traversing them.

Add man page documentation and EXAMPLES.

Usage example:

man -w -K '\<arm\>' -S 1:8

Test Plan

• man -K 'regexp' shows the expected results
• man -w -K 'regexp' shows only page locations but no content
• man -K -S... shows results only in the specified sections

[bcr]

OK from manpages. Looks like a nice feature.

[ceri]

Could you add egrep to the .Xr section please?

[fernape]

Add .Xr for egrep(1).

Spotted by ceri@

[fernape]

In D30984#697377, @ceri wrote:

Could you add egrep to the .Xr section please?

Thanks!

[emaste]

Unlike the Linux version

Linux distros man(1) do use the same options though for their similar functionality?

[fernape]

In D30984#697562, @emaste wrote:

Unlike the Linux version

Linux distros man(1) do use the same options though for their similar functionality?

Yes, AFAICT. This is an example from an Ubuntu system:

$ man -w ls
/usr/share/man/man1/ls.1.gz

$ man -S1 ls
<shows the page>

$ man -w -S1:8 -K arm
/usr/share/man/man1/tload.1.gz
/usr/share/man/man1/alsactl.1.gz
/usr/share/man/man1/alsamixer.1.gz
/usr/share/man/man1/amixer.1.gz
...
[snip]

Note that in the absence of other options, -K behaves interactively. I am not sure about the value of this, though.

$ man -K arm
<shows the first man page which matches the regexp. On exit, the following menu is shown>
--Man-- next: alsactl(1) [ view (return) | skip (Ctrl-D) | quit (Ctrl-C) ]

[fernape]

Ping!

Does this look useful and reasonable? Any improvements that we could work on?

[fernape]

• Use grep -E instead of egrep(1)

egrep(1) seems to be there more for backwards compatibility[1]

[1] https://pubs.opengroup.org/onlinepubs/9699919799/utilities/grep.html

[pauamma_gundo.com]

usr.bin/man/man.1

47

Does ... mean "one or more"? This looks inconsistent with the description below and the usage line in the shell program, both of which only mention one.

[debdrup]

I think it's time we land this, as I've been recently reminded just how nice it'd be to have this. :)

usr.bin/man/man.1

47

Does ... mean "one or more"? This looks inconsistent with the description below and the usage line in the shell program, both of which only mention one.

The use of ellipsis here is compatible with the other uses of ellipses on this manual page, and in context mean that something has been left out which the user needs to fill out.

[fernape]

Committed.

Thank you all for the review!