Page MenuHomeFreeBSD

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

Authored by fernape on Jul 1 2021, 5:16 PM.
Tags
None
Referenced Files
Unknown Object (File)
Thu, Mar 7, 6:05 PM
Unknown Object (File)
Feb 4 2024, 11:08 PM
Unknown Object (File)
Jan 15 2024, 12:36 AM
Unknown Object (File)
Dec 23 2023, 3:46 AM
Unknown Object (File)
Dec 20 2023, 5:45 PM
Unknown Object (File)
Nov 23 2023, 1:32 PM
Unknown Object (File)
Nov 12 2023, 10:36 AM
Unknown Object (File)
Nov 6 2023, 7:15 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 Passed
Unit
No Test Coverage
Build Status
Buildable 40217
Build 37106: 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_gundo.com added inline comments.
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 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
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.

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!