man(1): clarify searching + nits + spdx

People are often stunned by robust manual search functionality on
the community discord, so attempt to tidy doc regarding search by:
+ consolidate and standardize search options in synopsis and usage
+ call regular expressions `expression` like other manual pages
+ explain what search related flags do instead of using similies
+ crossreference the regular expression manual instead of egrep(1)

While here, polish and wax:
+ use consistent spacing and form (Ql) for quoted literals
+ clean a few linter errors regarding self xref and nospace
+ tag spdx

Notes on currently outstanding issues:
- man.1 example 3 is confusing, and shows no results on my boxen
- logic preventing -Kk from being used together isn't working

MFC after:	3 days

usr.bin/man/man.1

@@ -1,4 +1,6 @@
 .\"-
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
 .\"  Copyright (c) 2010 Gordon Tetlow
 .\"  All rights reserved.
 .\"
@@ -41,14 +43,8 @@
 .Op Ar mansect
 .Ar page ...
 .Nm
-.Fl K
-.Ar regexp ...
-.Nm
-.Fl f
-.Ar keyword ...
-.Nm
-.Fl k
-.Ar keyword ...
+.Fl K | f | k
+.Ar expression ...
 .Sh DESCRIPTION
 The
 .Nm
@@ -60,6 +56,7 @@ is provided,
 restricts the search to the specific section of the manual.
 .Pp
 The sections of the manual are:
+.Pp
 .Bl -enum -offset indent -compact
 .It
 .Fx
@@ -94,16 +91,14 @@ Options that
 .Nm
 understands:
 .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" .
+.It Fl K Ar expression
+Search full text of all manual pages for an extended regular
+.Ar expression .
 This option requires
 .Xr mandoc 1 .
 This is a slow operation.
 .It Fl M Ar manpath
-Forces a specific colon separated manual path instead of the default
+Force a specific colon separated manual path instead of the default
 search path.
 See
 .Xr manpath 1 .
@@ -113,18 +108,18 @@ environment variable.
 .It Fl P Ar pager
 Use specified pager.
 Defaults to
-.Dq Li "less -sR"
+.Ql less -sR
 if color support is enabled, or
-.Dq Li "less -s" .
+.Ql less -s .
 Overrides the
 .Ev MANPAGER
 environment variable, which in turn overrides the
 .Ev PAGER
 environment variable.
 .It Fl S Ar mansect
-Restricts manual sections searched to the specified colon delimited list.
+Restrict manual sections searched to the specified colon delimited list.
 Defaults to
-.Dq Li 1:8:2:3:3lua:n:4:5:6:7:9:l .
+.Ql 1:8:2:3:3lua:n:4:5:6:7:9:l .
 Overrides the
 .Ev MANSECT
 environment variable.
@@ -136,13 +131,17 @@ argument.
 Print extra debugging information.
 Repeat for increased verbosity.
 Does not display the manual page.
-.It Fl f
-Emulate
+.It Fl f Ar expression
+Search names of all manual pages for an extended regular
+.Ar expression ,
+emulating
 .Xr whatis 1 .
 .It Fl h
 Display short help message and exit.
-.It Fl k
-Emulate
+.It Fl k Ar expression
+Search names and descriptions of all manual pages for an extended regular
+.Ar expression ,
+emulating basic functionality of
 .Xr apropos 1 .
 .It Fl m Ar arch Ns Op : Ns Ar machine
 Override the default architecture and machine settings allowing lookup of
@@ -212,17 +211,17 @@ will search for locale specific manual pages using the following logic:
 .Pp
 .Bl -item -offset indent -compact
 .It
-.Va lang Ns _ Ns Va country Ns . Ns Va charset
+.Va lang Ns _ Ns Va country . Ns Va charset
 .It
-.Va lang Ns . Ns Va charset
+.Va lang . Ns Va charset
 .It
-.Li en Ns . Ns Va charset
+.Li en . Ns Va charset
 .El
 .Pp
 For example, if
 .Ev LC_ALL
 is set to
-.Dq Li ja_JP.eucJP ,
+.Ql ja_JP.eucJP ,
 .Nm
 will search the following paths when considering section 1 manual pages in
 .Pa /usr/share/man :
@@ -251,11 +250,11 @@ environment variables.
 For example, if
 .Ev MACHINE_ARCH
 is set to
-.Dq Li aarch64
+.Ql aarch64
 and
 .Ev MACHINE
 is set to
-.Dq Li arm64 ,
+.Ql arm64 ,
 .Nm
 will search the following paths when considering section 4 manual pages in
 .Pa /usr/share/man :
@@ -293,9 +292,9 @@ option.
 .It Ev MACHINE_ARCH , MACHINE
 Used to find platform specific manual pages.
 If unset, the output of
-.Dq Li "sysctl hw.machine_arch"
+.Ql sysctl hw.machine_arch
 and
-.Dq Li "sysctl hw.machine"
+.Ql sysctl hw.machine
 is used respectively.
 See
 .Sx IMPLEMENTATION NOTES
@@ -305,7 +304,7 @@ Corresponds to the
 option.
 .It Ev MANPATH
 The standard search path used by
-.Xr man 1
+.Nm
 may be changed by specifying a path in the
 .Ev MANPATH
 environment variable.
@@ -338,7 +337,7 @@ option.
 .It Ev MANWIDTH
 If set to a numeric value, used as the width manpages should be displayed.
 Otherwise, if set to a special value
-.Dq Li tty ,
+.Ql tty ,
 and output is to a terminal,
 the pages may be displayed over the whole width of the screen.
 .It Ev MANCOLOR
@@ -347,14 +346,14 @@ If set, enables color support.
 Program used to display files.
 .Pp
 If unset, and color support is enabled,
-.Dq Li "less -sR"
+.Ql less -sR
 is used.
 .Pp
 If unset, and color support is disabled, then
 .Ev PAGER
 is used.
 If that has no value either,
-.Dq Li "less -s"
+.Ql less -s
 is used.
 .El
 .Sh FILES
@@ -408,7 +407,6 @@ $ ./man -w -K '\e<arm\e>' -S 1:8
 .Ed
 .Sh SEE ALSO
 .Xr apropos 1 ,
-.Xr egrep 1 ,
 .Xr intro 1 ,
 .Xr mandoc 1 ,
 .Xr manpath 1 ,
@@ -422,5 +420,6 @@ $ ./man -w -K '\e<arm\e>' -S 1:8
 .Xr intro 6 ,
 .Xr intro 7 ,
 .Xr mdoc 7 ,
+.Xr re_format 7 ,
 .Xr intro 8 ,
 .Xr intro 9

usr.bin/man/man.sh

@@ -739,10 +739,9 @@ man_setup_locale() {
 # Display usage for the man utility.
 man_usage() {
 	echo 'Usage:'
-	echo ' man [-adho] [-t | -w] [-K regexp] [-M manpath] [-P pager] [-S mansect]'
+	echo ' man [-adho] [-t | -w] [-M manpath] [-P pager] [-S mansect]'
 	echo '     [-m arch[:machine]] [-p [eprtv]] [mansect] page [...]'
-	echo ' man -f page [...] -- Emulates whatis(1)'
-	echo ' man -k page [...] -- Emulates apropos(1)'
+	echo ' man -K | -f | -k expression [...] -- Search manual pages'
 
 	# When exit'ing with -h, it's not an error.
 	exit ${1:-1}