-.\" $Id: apropos.1,v 1.17 2012/03/24 01:46:25 kristaps Exp $
+.\" $Id: apropos.1,v 1.19 2012/06/09 14:11:15 kristaps Exp $
.\"
.\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: March 24 2012 $
+.Dd $Mdocdate: June 9 2012 $
.Dt APROPOS 1
.Os
.Sh NAME
-.Nm apropos
+.Nm apropos ,
+.Nm whatis
.Nd search manual page databases
.Sh SYNOPSIS
.Nm
.Ar expression ...
.Sh DESCRIPTION
The
-.Nm
-utility queries manual page databases generated by
+.Nm apropos
+and
+.Nm whatis
+utilities query manual page databases generated by
.Xr mandocdb 8 ,
evaluating on
.Ar expression
searches for
.Xr mandocdb 8
databases in the default paths stipulated by
-.Xr man 1 ,
-parses terms as case-sensitive regular expressions
-over manual names and descriptions.
-Multiple terms imply pairwise
-.Fl o .
-If standard output is a TTY, a result may be selected from a list and
-its manual displayed with the pager.
+.Xr man 1
+and
+maps terms to case-sensitive manual names and descriptions.
+Multiple terms are OR'd.
+.Nm whatis
+maps terms only to case-sensitive manual names.
.Pp
Its arguments are as follows:
.Bl -tag -width Ds
for a listing of manual sections.
.El
.Pp
-An
+.Nm whatis
+considers an
.Ar expression
-consists of search terms joined by logical operators
-.Fl a
-.Pq and
-and
-.Fl o
-.Pq or .
-The
-.Fl a
-operator has precedence over
-.Fl o
-and both are evaluated left-to-right.
-.Bl -tag -width Ds
-.It \&( Ar expr No \&)
-True if the subexpression
-.Ar expr
-is true.
-.It Ar expr1 Fl a Ar expr2
-True if both
-.Ar expr1
-and
-.Ar expr2
-are true (logical
-.Qq and ) .
-.It Ar expr1 Oo Fl o Oc Ar expr2
-True if
-.Ar expr1
-and/or
-.Ar expr2
-evaluate to true (logical
-.Qq or ) .
-.It Ar term
-True if
-.Ar term
-is satisfied.
-This has syntax
+to consist of an opaque keyword.
+.Nm apropos
+parses a
+.Ar expression
+into type and keyword pairs.
+This pair syntax
.Li [key[,key]*(=~)]?val ,
where operand
.Cm key
for a list of available keys.
Operator
.Li \&=
-evaluates a substring, while
+evaluates a full string, while
.Li \&~
-evaluates a regular expression.
-.It Fl i Ar term
-If
-.Ar term
-is a regular expression, it
-is evaluated case-insensitively.
-Has no effect on substring terms.
-.El
+evaluates a
+.Xr glob 7
+pattern.
.Pp
Results are sorted by manual title, with output formatted as
-.Pp
-.D1 title(sec) \- description
-.Pp
-Where
+.Qq title(sec) \- description
+where
.Qq title
is the manual's title (note multiple manual names may exist for one
title),
.Qq 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
-.Pp
-If on a TTY, results are prefixed with a numeric identifier.
-.Pp
-.D1 [index] title(cat) \- description
-.Pp
-One may choose a manual be entering the index at the prompt.
-Valid choices are displayed using
-.Ev MANPAGER ,
-or failing that ,
-.Ev PAGER
-or just
-.Xr more 1 .
-Source pages are formatted with
-.Xr mandoc 1 ;
-preformatted pages with
-.Xr cat 1 .
+.Qq title(cat/arch) \- description .
.Ss Macro Keys
-Queries evaluate over a subset of
+.Nm apropos
+queries evaluate over a subset of
.Xr mdoc 7
macros indexed by
.Xr mandocdb 8 .
.El
.Sh ENVIRONMENT
.Bl -tag -width Ds
-.It Ev MANPAGER
-Default pager for manuals.
-If this is unset, falls back to
-.Ev Pager .
-.It Ev PAGER
-The second choice for a manual pager.
-If this is unset, use
-.Xr more 1 .
.It Ev MANPATH
Colon-separated paths modifying the default list of paths searched for
manual databases.
.El
.Sh FILES
.Bl -tag -width "/etc/man.conf" -compact
-.It Pa whatis.db
+.It Pa mandocdb.db
name of the
.Xr mandocdb 8
keyword database
-.It Pa whatis.index
-name of the
-.Xr mandocdb 8
-filename database
.It Pa /etc/man.conf
default
.Xr man 1
.Sh EXAMPLES
Search for
.Qq mdoc
-as a substring and regular expression
-within each manual name and description:
+as a word or
+.Xr glob 7
+expression:
.Pp
.Dl $ apropos mdoc
-.Dl $ apropos ~^mdoc$
+.Dl $ apropos any~mdoc*
.Pp
Include matches for
.Qq roff
and
.Qq man
-for the regular expression case:
+using
+.Xr glob 7
+expressions:
.Pp
-.Dl $ apropos ~^mdoc$ roff man
-.Dl $ apropos ~^mdoc$ \-o roff \-o man
+.Dl $ apropos ~*mdoc* ~*roff*
.Pp
Search for
-.Qq optind
-and
.Qq optarg
-as variable names in the library category:
+as a variable name in the library category:
.Pp
-.Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
+.Dl $ apropos \-s 3 Va=optarg
.Sh SEE ALSO
-.Xr more 1
-.Xr re_format 7 ,
+.Xr glob 7 ,
.Xr mandocdb 8
.Sh AUTHORS
The
git.ckatri.com / mandoc.git / blobdiff