-.\" $Id: apropos.1,v 1.26 2014/04/15 23:02:27 schwarze Exp $
+.\" $Id: apropos.1,v 1.39 2015/04/03 08:46:17 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 15 2014 $
+.Dd $Mdocdate: April 3 2015 $
.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
and
.Nm whatis
utilities query manual page databases generated by
-.Xr mandocdb 8 ,
-evaluating on
+.Xr makewhatis 8 ,
+evaluating
.Ar expression
for each file in each database.
+By default, they display the names, section numbers, and description lines
+of all matching manuals.
.Pp
By default,
.Nm
searches for
-.Xr mandocdb 8
+.Xr makewhatis 8
databases in the default paths stipulated by
-.Xr man 1 ,
-parses terms as case-sensitive regular expressions
-.Pq the Li \&~ operator
+.Xr man 1
+and uses case-insensitive substring matching
+.Pq the Cm = No operator
over manual names and descriptions
.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
-.Xr mandocdb 8
+.Xr makewhatis 8
databases.
Invalid paths, or paths without manual databases, are ignored.
.It Fl m Ar path
Prepend the colon-separated paths to the list of paths searched
for
-.Xr mandocdb 8
+.Xr makewhatis 8
databases.
Invalid paths, or paths without manual databases, are ignored.
.It Fl O Ar outkey
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
and
.Ar expr2
are true (logical
-.Qq and ) .
+.Sq and ) .
.It Ar expr1 Oo Fl o Oc Ar expr2
True if
.Ar expr1
and/or
.Ar expr2
evaluate to true (logical
-.Qq or ) .
+.Sq or ) .
.It Ar term
True if
.Ar term
is satisfied.
This has syntax
-.Li [key[,key]*(=~)]?val ,
-where operand
-.Cm key
+.Sm off
+.Oo
+.Op Ar key Op , Ar key ...
+.Pq Cm = | \(ti
+.Oc
+.Ar val ,
+.Sm on
+where
+.Ar key
is an
.Xr mdoc 7
macro to query and
-.Cm val
+.Ar val
is its value.
See
.Sx Macro Keys
for a list of available keys.
Operator
-.Li \&=
+.Cm =
evaluates a substring, while
-.Li \&~
+.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.
+Results are sorted by manual sections and names, with output formatted as
.Pp
-Results are sorted by manual title, with output formatted as
-.Pp
-.D1 title(sec) \- description
+.D1 name[, name...](sec) \- description
.Pp
Where
-.Qq title
-is the manual's title (note multiple manual names may exist for one
-title),
-.Qq sec
+.Dq name
+is the manual's name,
+.Dq sec
is the manual section, and
-.Qq description
+.Dq description
is the manual's short description.
If an architecture is specified for the manual, it is displayed as
.Pp
-.D1 title(cat/arch) \- description
+.D1 name(sec/arch) \- description
.Pp
Resulting manuals may be accessed as
.Pp
-.Dl $ man \-s sec title
+.Dl $ man \-s sec name
.Pp
If an architecture is specified in the output, use
.Pp
-.Dl $ man \-s sec \-S arch title
+.Dl $ man \-s sec \-S arch name
.Ss Macro Keys
Queries evaluate over a subset of
.Xr mdoc 7
macros indexed by
-.Xr mandocdb 8 .
+.Xr makewhatis 8 .
In addition to the macro keys listed below, the special key
.Cm any
may be used to match any available macro key.
.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
.It Pa mandoc.db
name of the
-.Xr mandocdb 8
+.Xr makewhatis 8
keyword database
.It Pa /etc/man.conf
default
.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 category mentioning both the
+Search for manuals in the library section mentioning both the
.Qq optind
and the
.Qq optarg
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 mandocdb 8
+.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 .
.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