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

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 `grep(1)` and `mandoc(1)` to do its job.

Add flag documentation and EXAMPLES to the manual page (bump .Dd).

Usage example:

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

Reviewed By: ceri, emaste, pauamma_gundo.com
Approved by: manpages (bcr@), debdrup@
Differential Revision: https://reviews.freebsd.org/D30984
This commit is contained in:
Fernando Apesteguía 2022-01-25 13:12:27 +01:00
parent 81de556105
commit 1594084f3f
2 changed files with 63 additions and 5 deletions

View File

@ -25,7 +25,7 @@
.\" .\"
.\" $FreeBSD$ .\" $FreeBSD$
.\" .\"
.Dd January 9, 2021 .Dd January 26, 2022
.Dt MAN 1 .Dt MAN 1
.Os .Os
.Sh NAME .Sh NAME
@ -43,6 +43,9 @@
.Op Ar mansect .Op Ar mansect
.Ar page ... .Ar page ...
.Nm .Nm
.Fl K
.Ar regexp ...
.Nm
.Fl f .Fl f
.Ar keyword ... .Ar keyword ...
.Nm .Nm
@ -93,6 +96,14 @@ Options that
.Nm .Nm
understands: understands:
.Bl -tag -width indent .Bl -tag -width indent
.It Fl K Ar regexp
Does a full text search in all manual pages.
.Ar regexp
is a regular expression as understood by
.Dq Li "grep -E" .
This option requires
.Xr mandoc 1 .
This is a slow operation.
.It Fl M Ar manpath .It Fl M Ar manpath
Forces a specific colon separated manual path instead of the default Forces a specific colon separated manual path instead of the default
search path. search path.
@ -392,8 +403,14 @@ manual page:
$ man -w ls $ man -w ls
.Ed .Ed
.Pp .Pp
Show the location of manual pages in sections 1 and 8 which contain the word
.Ql arm :
.Bd -literal -offset indent
$ ./man -w -K '\e<arm\e>' -S 1:8
.Ed
.Sh SEE ALSO .Sh SEE ALSO
.Xr apropos 1 , .Xr apropos 1 ,
.Xr egrep 1 ,
.Xr intro 1 , .Xr intro 1 ,
.Xr mandoc 1 , .Xr mandoc 1 ,
.Xr manpath 1 , .Xr manpath 1 ,

View File

@ -548,8 +548,10 @@ man_parse_args() {
local IFS cmd_arg local IFS cmd_arg
OPTIND=1 OPTIND=1
while getopts 'M:P:S:adfhkm:op:tw' cmd_arg; do while getopts 'K:M:P:S:adfhkm:op:tw' cmd_arg; do
case "${cmd_arg}" in case "${cmd_arg}" in
K) Kflag=Kflag
REGEXP=$OPTARG ;;
M) MANPATH=$OPTARG ;; M) MANPATH=$OPTARG ;;
P) MANPAGER=$OPTARG ;; P) MANPAGER=$OPTARG ;;
S) MANSECT=$OPTARG ;; S) MANSECT=$OPTARG ;;
@ -570,7 +572,11 @@ man_parse_args() {
shift $(( $OPTIND - 1 )) shift $(( $OPTIND - 1 ))
# Check the args for incompatible options. # Check the args for incompatible options.
case "${fflag}${kflag}${tflag}${wflag}" in
case "${Kflag}${fflag}${kflag}${tflag}${wflag}" in
Kflagfflag*) echo "Incompatible options: -K and -f"; man_usage ;;
Kflag*kflag*) echo "Incompatible options: -K and -k"; man_usage ;;
Kflag*tflag) echo "Incompatible options: -K and -t"; man_usage ;;
fflagkflag*) echo "Incompatible options: -f and -k"; man_usage ;; fflagkflag*) echo "Incompatible options: -f and -k"; man_usage ;;
fflag*tflag*) echo "Incompatible options: -f and -t"; man_usage ;; fflag*tflag*) echo "Incompatible options: -f and -t"; man_usage ;;
fflag*wflag) echo "Incompatible options: -f and -w"; man_usage ;; fflag*wflag) echo "Incompatible options: -f and -w"; man_usage ;;
@ -711,7 +717,7 @@ man_setup_locale() {
# Display usage for the man utility. # Display usage for the man utility.
man_usage() { man_usage() {
echo 'Usage:' echo 'Usage:'
echo ' man [-adho] [-t | -w] [-M manpath] [-P pager] [-S mansect]' echo ' man [-adho] [-t | -w] [-K regexp] [-M manpath] [-P pager] [-S mansect]'
echo ' [-m arch[:machine]] [-p [eprtv]] [mansect] page [...]' echo ' [-m arch[:machine]] [-p [eprtv]] [mansect] page [...]'
echo ' man -f page [...] -- Emulates whatis(1)' echo ' man -f page [...] -- Emulates whatis(1)'
echo ' man -k page [...] -- Emulates apropos(1)' echo ' man -k page [...] -- Emulates apropos(1)'
@ -965,14 +971,49 @@ do_apropos() {
search_whatis apropos "$@" search_whatis apropos "$@"
} }
# Usage: do_full_search reg_exp
# Do a full search of the regular expression passed
# as parameter in all man pages
do_full_search() {
local gflags re
re=${1}
# Build grep(1) flags
gflags="-H"
# wflag implies -l for grep(1)
if [ -n "$wflag" ]; then
gflags="${gflags} -l"
fi
gflags="${gflags} --label"
set +f
for mpath in $(echo "${MANPATH}" | tr : [:blank:]); do
for section in $(echo "${MANSECT}" | tr : [:blank:]); do
for manfile in ${mpath}/man${section}/*.${section}*; do
mandoc "${manfile}" 2>/dev/null |
grep -E ${gflags} "${manfile}" -e ${re}
done
done
done
set -f
}
do_man() { do_man() {
man_parse_args "$@" man_parse_args "$@"
if [ -z "$pages" ]; then if [ -z "$pages" -a -z "${Kflag}" ]; then
echo 'What manual page do you want?' >&2 echo 'What manual page do you want?' >&2
exit 1 exit 1
fi fi
man_setup man_setup
if [ ! -z "${Kflag}" ]; then
# Short circuit because -K flag does a sufficiently
# different thing like not showing the man page at all
do_full_search "${REGEXP}"
fi
for page in $pages; do for page in $pages; do
decho "Searching for $page" decho "Searching for $page"
man_find_and_display "$page" man_find_and_display "$page"