-.\" $Id: apropos.1,v 1.28 2014/04/18 10:30:37 schwarze Exp $
+.\" $Id: apropos.1,v 1.40 2017/01/31 19:44:04 schwarze Exp $
.\"
.\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2011, 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: April 18 2014 $
+.Dd $Mdocdate: January 31 2017 $
.Dt APROPOS 1
.Os
.Sh NAME
.Nd search manual page databases
.Sh SYNOPSIS
.Nm
+.Op Fl acfhklw
.Op Fl C Ar file
.Op Fl M Ar path
.Op Fl m Ar path
evaluating
.Ar expression
for each file in each database.
-By default, it displays the names, section numbers, and description lines
+By default, they display the names, section numbers, and description lines
of all matching manuals.
.Pp
By default,
.Pq the Li \&Nm No and Li \&Nd No macro keys .
Multiple terms imply pairwise
.Fl o .
+.Pp
.Nm whatis
-maps terms only to case-sensitive manual names.
+is a synonym for
+.Nm
+.Fl f .
.Pp
-Its arguments are as follows:
+The options are as follows:
.Bl -tag -width Ds
+.It Fl a
+Instead of showing only the title lines, show the complete manual pages,
+just like
+.Xr man 1
+.Fl a
+would.
+If the standard output is a terminal device and
+.Fl c
+is not specified, use
+.Xr more 1
+to paginate them.
+In
+.Fl a
+mode, the options
+.Fl IKOTW
+described in the
+.Xr mandoc 1
+manual are also available.
.It Fl C Ar file
Specify an alternative configuration
.Ar file
in
.Xr man.conf 5
format.
+.It Fl c
+In
+.Fl a
+mode, copy the formatted manual pages to the standard output without using
+.Xr more 1
+to paginate them.
+.It Fl f
+Search for all words in
+.Ar expression
+in manual page names only.
+The search is case insensitive and matches whole words only.
+In this mode, macro keys, comparison operators, and logical operators
+are not available.
+This overrides any earlier
+.Fl k
+and
+.Fl l
+options.
+.It Fl h
+Instead of showing the title lines, show the SYNOPSIS sections, just like
+.Xr man 1
+.Fl h
+would.
+.It Fl k
+Support the full
+.Ar expression
+syntax.
+This overrides any earlier
+.Fl f
+and
+.Fl l
+options.
+It is the default for
+.Nm .
+.It Fl l
+An alias for
+.Xr mandoc 1
+.Fl a .
+This overrides any earlier
+.Fl f ,
+.Fl k ,
+and
+.Fl w
+options.
.It Fl M Ar path
Use the colon-separated path instead of the default list of paths
searched for
See
.Xr man 1
for a listing of sections.
+.It Fl w
+Instead of showing title lines, show the pathnames of the matching
+manual pages, just like
+.Xr man 1
+.Fl w
+would.
.El
.Pp
An
.Sm off
.Oo
.Op Ar key Op , Ar key ...
-.Pq Cm = | ~
+.Pq Cm = | \(ti
.Oc
-.Ar val
-.Sm on ,
+.Ar val ,
+.Sm on
where
.Ar key
is an
Operator
.Cm =
evaluates a substring, while
-.Cm ~
+.Cm \(ti
evaluates a regular expression.
.It Fl i Ar term
If
Has no effect on substring terms.
.El
.Pp
-.Nm whatis
-considers an
-.Ar expression
-to consist of an opaque keyword.
-.Pp
Results are sorted by manual sections and names, with output formatted as
.Pp
.D1 name[, name...](sec) \- description
.It Li \&Dx Ta Dx No version reference
.El
.Sh ENVIRONMENT
-.Bl -tag -width MANPATH
+.Bl -tag -width MANPAGER
+.It Ev MANPAGER
+Any non-empty value of the environment variable
+.Ev MANPAGER
+will be used instead of the standard pagination program,
+.Xr more 1 .
.It Ev MANPATH
The standard search path used by
.Xr man 1
the standard search path is inserted between the colons.
If none of these conditions are met, it overrides the
standard search path.
+.It Ev PAGER
+Specifies the pagination program to use when
+.Ev MANPAGER
+is not defined.
+If neither PAGER nor MANPAGER is defined,
+.Xr more 1
+.Fl s
+will be used.
.El
.Sh FILES
.Bl -tag -width "/etc/man.conf" -compact
.Pp
Search in names and descriptions using a regular expression:
.Pp
-.Dl $ apropos '~set.?[ug]id'
+.Dl $ apropos \(aq\(tiset.?[ug]id\(aq
.Pp
Search for manuals in the library section mentioning both the
.Qq optind
with the argument
.Qq ssh :
.Pp
-.Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]'
+.Dl $ apropos \-\- \-i \(aqNm\(ti[[:<:]]ssh[[:>:]]\(aq
.Pp
The following two invocations are equivalent:
.Pp
.D1 Li $ apropos -S Ar arch Li -s Ar section expression
.Bd -ragged -offset indent
.Li $ apropos \e( Ar expression Li \e)
-.Li -a arch~^( Ns Ar arch Ns Li |any)$
-.Li -a sec~^ Ns Ar section Ns Li $
+.Li -a arch\(ti^( Ns Ar arch Ns Li |any)$
+.Li -a sec\(ti^ Ns Ar section Ns Li $
.Ed
.Sh SEE ALSO
.Xr man 1 ,
.Xr re_format 7 ,
.Xr makewhatis 8
.Sh HISTORY
-An
+Part of the functionality of
+.Nm whatis
+was already provided by the former
+.Nm manwhere
+utility in
+.Bx 1 .
+The
.Nm
-utility first appeared in
+and
+.Nm whatis
+utilities first appeared in
.Bx 2 .
-It was rewritten from scratch for
+They were rewritten from scratch for
.Ox 5.6 .
.Pp
The
and
.Fl s
in
-.Ox 4.5 .
+.Ox 4.5
+for
+.Nm
+and in
+.Ox 5.6
+for
+.Nm whatis .
+The options
+.Fl acfhIKklOTWw
+appeared in
+.Ox 5.7 .
.Sh AUTHORS
.An -nosplit
.An Bill Joy
-wrote the original
+wrote
+.Nm manwhere
+in 1977 and the original
.Bx
.Nm
+and
+.Nm whatis
in February 1979.
The current version was written by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
git.ckatri.com / mandoc.git / blobdiff