From nobody Sat Jan 25 00:10:00 2025 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4Yfw6c6rLGz5lcgH; Sat, 25 Jan 2025 00:10:00 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Yfw6c66P7z45VW; Sat, 25 Jan 2025 00:10:00 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1737763800; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=uhVxWp5Ac6iWreiqJigkvpPnk15NVry3bwuu1+ArluI=; b=RJ2tUfFP6/jz9wol7CZjNPXt5Na1AcH55bvjY+PUrhCbTgPaSvXUsRbIHfI/dCwpUmw685 Q0XJU7DveWzTtPTDFB8yVt+MP6DPC6bvoCG7d7lpjHFFBpI0In44AqWA6st2MJ94MNdPHB nWqRX6OhI7pSW8PcL0ShKdkXwhhr1/O9TLo2jiaWJScVqxHk7BhB/bgR+1ceY1qG1aRtKd d9Ef1xn289ZHUaN5t7SPxKg8nGcSKF5dtSrDXsrsYLJGjLBr3KCq5qfBFk7ypLBeuAQHMA ZymesNr4EN4C5WNrKTj1QH4R2f25JsAOaVq9paTHvC2PZLosrSXj8oo4JYvNVg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1737763800; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=uhVxWp5Ac6iWreiqJigkvpPnk15NVry3bwuu1+ArluI=; b=o6XAw032S1sBAF7+hRzE36BHcYtgvaWeEzM5yoN2FLq2UjUOVMrxGYvSC1M37uhZkOrr7W DGU8/La4z5bt3Mg1cV3Dy9RE6ZHv7I1J0/egGaR8Jvnf3t+NNRueI/9wB1T3fyM+PLh9mt +iqWvSSzHN7qgIgMaBwryJDRsbL4sIQEX+nxd0fbmGXju7IjJZpeUsXHmK2j6gepmAcqcq BCxZm7GxW9wVoMH6yKAzx1mM79amXvtU6DbqgNGxCPc6jR0HZPDGIgTja/WG2105LU1NdG uZe9CkwBGn5hxqkuwJbnyqOPZNk48HvtlRnjAdSWz4WgfqiQPBejXEFVGXN8zw== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1737763800; a=rsa-sha256; cv=none; b=xQpNcZNPnW6z2sc4jryr5drPTkSaqPlxwkYXvJJusSBbScMO/2ZM1ooAlR66oa+Hh/nEvN AwA0LwtxcO0G/4wnuMd5TTm+EvTO2kKj1vZDSfBa892K6CGlW3ZQI5ip3wqhz8OhbbP/IF HigSLNz8dxjqwzGQRd2hVpaJjNqXSSNlsvTpiBrNHAZUR5VUw6XB7cdd2m9COXa+AjD0WZ WtjzTyukC0FpT0OKCamnwOhuMdOyA+UTNSADb9GXF7FJ/AGsBsK8t3tB86LWpX9Pus/Q+C G5JwXpPAft6iOsGktNwYFS7AY4getfkgflJzUQCv4EmzVB70+2OS+50dy1PZGg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4Yfw6c58N9zp1q; Sat, 25 Jan 2025 00:10:00 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 50P0A0bF079303; Sat, 25 Jan 2025 00:10:00 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 50P0A0te079279; Sat, 25 Jan 2025 00:10:00 GMT (envelope-from git) Date: Sat, 25 Jan 2025 00:10:00 GMT Message-Id: <202501250010.50P0A0te079279@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Alexander Ziaee Subject: git: 46a9fb7287f4 - main - man.1: Improve search + spdx List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-main@freebsd.org Sender: owner-dev-commits-src-main@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: ziaee X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 46a9fb7287f41eedf321d81a68a826f231d11bfe Auto-Submitted: auto-generated The branch main has been updated by ziaee: URL: https://cgit.FreeBSD.org/src/commit/?id=46a9fb7287f41eedf321d81a68a826f231d11bfe commit 46a9fb7287f41eedf321d81a68a826f231d11bfe Author: Alexander Ziaee AuthorDate: 2024-09-28 03:07:07 +0000 Commit: Alexander Ziaee 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.*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 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' -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 +419,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 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}