From 854630348c4883e1dfa32c631564d69ee8350b1b Mon Sep 17 00:00:00 2001
From: Ingo Schwarze <schwarze@openbsd.org>
Date: Tue, 17 Sep 2013 20:39:17 +0000
Subject: Merge rev. 1.20: Revert the argument names in the SYNOPSIS back to
 the usual ones.

---
 apropos.1 | 137 +++++++++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 92 insertions(+), 45 deletions(-)

diff --git a/apropos.1 b/apropos.1
index dc849ce2..b0f79fc9 100644
--- a/apropos.1
+++ b/apropos.1
@@ -1,6 +1,6 @@
-.\"	$Id: apropos.1,v 1.21 2013/07/13 19:41:16 schwarze Exp $
+.\"	$Id: apropos.1,v 1.16.2.1 2013/09/17 20:39:17 schwarze Exp $
 .\"
-.\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -14,12 +14,11 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 13 2013 $
+.Dd $Mdocdate: September 17 2013 $
 .Dt APROPOS 1
 .Os
 .Sh NAME
-.Nm apropos ,
-.Nm whatis
+.Nm apropos
 .Nd search manual page databases
 .Sh SYNOPSIS
 .Nm
@@ -31,10 +30,8 @@
 .Ar expression ...
 .Sh DESCRIPTION
 The
-.Nm apropos
-and
-.Nm whatis
-utilities query manual page databases generated by
+.Nm
+utility queries manual page databases generated by
 .Xr mandocdb 8 ,
 evaluating on
 .Ar expression
@@ -45,12 +42,13 @@ By default,
 searches for
 .Xr mandocdb 8
 databases in the default paths stipulated by
-.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.
+.Xr man 1 ,
+parses terms as case-sensitive regular expressions
+.Pq the Li \&~ operator
+over manual names and descriptions
+.Pq the Li \&Nm No and Li \&Nd No macro keys .
+Multiple terms imply pairwise
+.Fl o .
 .Pp
 Its arguments are as follows:
 .Bl -tag -width Ds
@@ -81,15 +79,43 @@ See
 for a listing of manual sections.
 .El
 .Pp
-.Nm whatis
-considers an
+An
 .Ar expression
-to consist of an opaque keyword.
-.Nm apropos
-parses a
-.Ar expression
-into type and keyword pairs.
-This pair syntax
+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
 .Li [key[,key]*(=~)]?val ,
 where operand
 .Cm key
@@ -103,15 +129,22 @@ See
 for a list of available keys.
 Operator
 .Li \&=
-evaluates a full string, while
+evaluates a substring, while
 .Li \&~
-evaluates a
-.Xr glob 7
-pattern.
+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
 .Pp
 Results are sorted by manual title, with output formatted as
-.Qq title(sec) \- description
-where
+.Pp
+.D1 title(sec) \- description
+.Pp
+Where
 .Qq title
 is the manual's title (note multiple manual names may exist for one
 title),
@@ -120,10 +153,18 @@ is the manual section, and
 .Qq description
 is the manual's short description.
 If an architecture is specified for the manual, it is displayed as
-.Qq title(cat/arch) \- description .
+.Pp
+.D1 title(cat/arch) \- description
+.Pp
+Resulting manuals may be accessed as
+.Pp
+.Dl $ man \-s sec title
+.Pp
+If an architecture is specified in the output, use
+.Pp
+.Dl $ man \-s sec \-S arch title
 .Ss Macro Keys
-.Nm apropos
-queries evaluate over a subset of
+Queries evaluate over a subset of
 .Xr mdoc 7
 macros indexed by
 .Xr mandocdb 8 .
@@ -219,10 +260,14 @@ If none of these conditions are met, it overrides the default list.
 .El
 .Sh FILES
 .Bl -tag -width "/etc/man.conf" -compact
-.It Pa mandocdb.db
+.It Pa whatis.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
@@ -233,33 +278,35 @@ configuration file
 .Sh EXAMPLES
 Search for
 .Qq mdoc
-as a word or
-.Xr glob 7
-expression:
+as a substring and regular expression
+within each manual name and description:
 .Pp
 .Dl $ apropos mdoc
-.Dl $ apropos any~mdoc*
+.Dl $ apropos ~^mdoc$
 .Pp
 Include matches for
 .Qq roff
 and
 .Qq man
-using
-.Xr glob 7
-expressions:
+for the regular expression case:
 .Pp
-.Dl $ apropos ~*mdoc* ~*roff*
+.Dl $ apropos ~^mdoc$ roff man
+.Dl $ apropos ~^mdoc$ \-o roff \-o man
 .Pp
 Search for
+.Qq optind
+and
 .Qq optarg
-as a variable name in the library category:
+as variable names in the library category:
 .Pp
-.Dl $ apropos \-s 3 Va=optarg
+.Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
 .Sh SEE ALSO
-.Xr glob 7 ,
+.Xr man 1 ,
+.Xr re_format 7 ,
 .Xr mandocdb 8
 .Sh AUTHORS
 The
 .Nm
 utility was written by
-.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
+.An Kristaps Dzonsons ,
+.Mt kristaps@bsd.lv .
-- 
cgit v1.2.3-56-ge451