From 750275745e3ab958193bcd466a35d7286bf8e540 Mon Sep 17 00:00:00 2001 From: Alexander Ziaee Date: Fri, 27 Sep 2024 23:07:07 -0400 Subject: [PATCH] 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 + tidy examples + align files + 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 | 113 ++++++++++++++++++++++----------------------- usr.bin/man/man.sh | 5 +- 2 files changed, 56 insertions(+), 62 deletions(-) diff --git a/usr.bin/man/man.1 b/usr.bin/man/man.1 index 24d9214682f137..6c61fa34374d1c 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. .\" @@ -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,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,61 @@ 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.*archive' -.Ed +.Pp +.Dl $ man -k '\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 the location of manual pages in sections 1 and 8 which contain the word .Ql arm : -.Bd -literal -offset indent -$ ./man -w -K '\e' -S 1:8 -.Ed +.Pp +.Dl $ man -w -K '\e' -S 1:8 .Sh SEE ALSO .Xr apropos 1 , -.Xr egrep 1 , .Xr intro 1 , .Xr mandoc 1 , .Xr manpath 1 , @@ -422,5 +416,6 @@ $ ./man -w -K '\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 f4037ed9221534..68a4b3a4058832 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}