Page MenuHomeFreeBSD

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

Authored by fernape on Jul 1 2021, 5:16 PM.

Details

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

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
Lint OK
Unit
No Unit Test Coverage
Build Status
Buildable 40233
Build 37122: arc lint + arc unit

Event Timeline

bcr added a subscriber: bcr.

OK from manpages. Looks like a nice feature.

Could you add egrep to the .Xr section please?

Add .Xr for egrep(1).

Spotted by ceri@

In D30984#697377, @ceri wrote:

Could you add egrep to the .Xr section please?

Thanks!

Unlike the Linux version

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

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) ]

Ping!

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

  • 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 added inline comments.
usr.bin/man/man.1
46

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 added a subscriber: 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
46

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.

This revision is now accepted and ready to land.Jan 26 2022, 9:01 AM
This revision was automatically updated to reflect the committed changes.

Committed.

Thank you all for the review!