Date: Sat, 25 Jan 2025 00:10:00 GMT From: Alexander Ziaee <ziaee@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Subject: git: 46a9fb7287f4 - main - man.1: Improve search + spdx Message-ID: <202501250010.50P0A0te079279@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by ziaee: URL: https://cgit.FreeBSD.org/src/commit/?id=46a9fb7287f41eedf321d81a68a826f231d11bfe commit 46a9fb7287f41eedf321d81a68a826f231d11bfe Author: Alexander Ziaee <ziaee@FreeBSD.org> AuthorDate: 2024-09-28 03:07:07 +0000 Commit: Alexander Ziaee <ziaee@FreeBSD.org> CommitDate: 2025-01-25 00:07:01 +0000 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 --- usr.bin/man/man.1 | 140 ++++++++++++++++++++++++++--------------------------- usr.bin/man/man.sh | 5 +- 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}
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202501250010.50P0A0te079279>