man.1: Improve search + spdx

People are often stunned by robust manual search functionality on
the community discord, so improve introductory doc regarding search by:

+ explain what search related flags do instead of using similies
+ consolidate and standardize search options in synopsis and usage
+ mention that a page or file can be specified in synopsis and example
+ call regular expressions `expression`, which searches to re_format(7)
+ crossreference the regular expression manual instead of egrep(1)
+ improve MANPATH xref flow and explanation, matching MAILPATH in sh(1)
+ mark up aditional semantics for their inclusion in apropos

While here:
+ use consistent spacing and form (Ql) for quoted literals
+ clean a few linter errors regarding self xref and nospace
+ reset a list width to indent for consistency with style.mdoc
+ tidy examples + align files + tag spdx

Outstanding:
- example 3 shows no results on a typical bsdinstall'd system

MFC after:	3 days
Reviewed by:	elliejs, emaste, imp, Jessica Hawkwell, jlduran
Approved by:	imp

2 files changed, 71 insertions, 74 deletions

diff --git a/usr.bin/man/man.1 b/usr.bin/man/man.1
index 24d9214682f1..820d6a5b33a9 100644
--- a/usr.bin/man/man.1
+++ b/usr.bin/man/man.1
@@ -1,4 +1,6 @@
 .\"-
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
 .\"  Copyright (c) 2010 Gordon Tetlow
 .\"  All rights reserved.
 .\"
@@ -23,7 +25,7 @@
 .\"  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\"  SUCH DAMAGE.
 .\"
-.Dd January 26, 2022
+.Dd January 24, 2025
 .Dt MAN 1
 .Os
 .Sh NAME
@@ -39,16 +41,10 @@
 .Op Fl m Ar arch Ns Op : Ns Ar machine
 .Op Fl p Op Ar eprtv
 .Op Ar mansect
-.Ar page ...
-.Nm
-.Fl K
-.Ar regexp ...
-.Nm
-.Fl f
-.Ar keyword ...
+.Ar page | Ar
 .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,37 +91,36 @@ 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 ,
+as described in
+.Xr re_format 7 .
 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 .
-Overrides the
 .Ev MANPATH
-environment variable.
+in
+.Sx ENVIRONMENT .
 .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 +132,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 +212,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 +251,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 :
@@ -278,8 +278,8 @@ character.
 .Sh ENVIRONMENT
 The following environment variables affect the execution of
 .Nm :
-.Bl -tag -width ".Ev MANROFFSEQ"
-.It Ev LC_ALL , LC_CTYPE , LANG
+.Bl -tag -width indent
+.It Ev LC_ALL , Ev LC_CTYPE , Ev LANG
 Used to find locale specific manual pages.
 Valid values can be found by running the
 .Xr locale 1
@@ -290,12 +290,12 @@ for details.
 Influenced by the
 .Fl o
 option.
-.It Ev MACHINE_ARCH , MACHINE
+.It Ev MACHINE_ARCH , Ev MACHINE
 Used to find platform specific manual pages.
 If unset, the output of
-.Dq Li "sysctl hw.machine_arch"
+.Ql sysctl Va hw.machine_arch
 and
-.Dq Li "sysctl hw.machine"
+.Ql sysctl Va hw.machine
 is used respectively.
 See
 .Sx IMPLEMENTATION NOTES
@@ -304,11 +304,9 @@ Corresponds to the
 .Fl m
 option.
 .It Ev MANPATH
-The standard search path used by
-.Xr man 1
-may be changed by specifying a path in the
-.Ev MANPATH
-environment variable.
+A colon
+.Pq Ql \&:
+separated list of directories to check for manual pages.
 Invalid paths, or paths without manual databases, are ignored.
 Overridden by
 .Fl M .
@@ -320,6 +318,8 @@ or if it contains two adjacent colons,
 the standard search path is inserted between the colons.
 If none of these conditions are met, it overrides the
 standard search path.
+See
+.Xr manpath 1 .
 .It Ev MANROFFSEQ
 Used to determine the preprocessors for the manual source before running
 .Xr nroff 1 Pq Pa ports/textproc/groff
@@ -338,7 +338,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,68 +347,65 @@ 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
-.Bl -tag -width indent -compact
+.Bl -tag -width "/usr/local/etc/man.d/*.conf" -compact
 .It Pa /etc/man.conf
-System configuration file.
+System configuration file
 .It Pa /usr/local/etc/man.d/*.conf
-Local configuration files.
+Local configuration files
 .El
 .Sh EXIT STATUS
 .Ex -std
 .Sh EXAMPLES
 Show the manual page for
 .Xr stat 2 :
-.Bd -literal -offset indent
-$ man 2 stat
-.Ed
+.Pp
+.Dl $ man 2 stat
 .Pp
 Show all manual pages for
-.Ql stat .
-.Bd -literal -offset indent
-$ man -a stat
-.Ed
+.Ql stat :
+.Pp
+.Dl $ man -a stat
 .Pp
 List manual pages which match the regular expression either in the title or in
 the body:
-.Bd -literal -offset indent
-$ man -k '\e<copy\e>.*archive'
-.Ed
+.Pp
+.Dl $ man -k '\e<copy\e>.*archive'
 .Pp
 Show the manual page for
 .Xr ls 1
-and use
+using
 .Xr cat 1
-as pager:
-.Bd -literal -offset indent
-$ man -P cat ls
-.Ed
+as the pager:
+.Pp
+.Dl $ man -P cat ls
 .Pp
 Show the location of the
 .Xr ls 1
 manual page:
-.Bd -literal -offset indent
-$ man -w ls
-.Ed
+.Pp
+.Dl $ man -w ls
+.Pp
+Show a manual page in the current working directory:
+.Pp
+.Dl $ man ./man.1
 .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
+.Pp
+.Dl $ man -w -K '\e<arm\e>' -S 1:8
 .Sh SEE ALSO
 .Xr apropos 1 ,
-.Xr egrep 1 ,
 .Xr intro 1 ,
 .Xr mandoc 1 ,
 .Xr manpath 1 ,
@@ -422,5 +419,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
diff --git a/usr.bin/man/man.sh b/usr.bin/man/man.sh
index f4037ed92215..68a4b3a40588 100755
--- a/usr.bin/man/man.sh
+++ b/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}