Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

man(1) clarify searching + minor nits #1438

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

man(1) clarify searching + minor nits #1438

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 54 additions & 59 deletions usr.bin/man/man.1
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
.\"-
.\" SPDX-License-Identifier: BSD-2-Clause
concussious marked this conversation as resolved.
Show resolved Hide resolved
.\"
.\" Copyright (c) 2010 Gordon Tetlow
.\" All rights reserved.
.\"
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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 .
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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 :
Expand Down Expand Up @@ -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 :
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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<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 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 ,
Expand All @@ -422,5 +416,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
5 changes: 2 additions & 3 deletions usr.bin/man/man.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -739,13 +739,12 @@
# 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'
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any chance 'expression' is confusing and should be 'regexp' ? either are better than 'page', that's for sure.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that regexp is less ambiguous for people new to unix, but the term expression is elegant and used in all the rest of the manual manuals like apropos. Also, man -k expression does show re_format(7) - POSIX 1003.2 regular expressions.


# When exit'ing with -h, it's not an error.
exit ${1:-1}

Check warning on line 747 in usr.bin/man/man.sh

View workflow job for this annotation

GitHub Actions / Style Checker 

Missing Signed-off-by: line
}

# Usage: parse_configs
Expand Down
Loading