man(1): clarify searching + nits + spdx

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

+ 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 leads to re_format(7)
+ explain what search related flags do instead of using similies
+ crossreference the regular expression manual instead of egrep(1)
+ remove prompts to support triple click copy and paste

While here:
+ use consistent spacing and form (Ql) for quoted literals
+ clean a few linter errors regarding self xref and nospace
+ 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, Jessica Hawkwell
Reported by:	Graham Percival <[email protected]> (example prompts)

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 November 5, 2024
 .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 ...
+.Ar page | Ar
 .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,16 @@ 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 understood by
+.Xr egrep 1 .
 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 +110,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 +133,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 +213,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 +252,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 +294,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 +306,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 +339,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 +348,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 +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}