===================================================================
RCS file: /cvs/mandoc/apropos.1,v
retrieving revision 1.11
retrieving revision 1.19
diff -u -p -r1.11 -r1.19
--- mandoc/apropos.1	2011/11/29 10:53:42	1.11
+++ mandoc/apropos.1	2012/06/09 14:11:15	1.19
@@ -1,6 +1,6 @@
-.\"	$Id: apropos.1,v 1.11 2011/11/29 10:53:42 kristaps Exp $
+.\"	$Id: apropos.1,v 1.19 2012/06/09 14:11:15 kristaps Exp $
 .\"
-.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2011, 2012 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,29 +14,52 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: November 29 2011 $
+.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
+.Op Fl C Ar file
 .Op Fl M Ar manpath
 .Op Fl m Ar manpath
 .Op Fl S Ar arch
 .Op Fl s Ar section
-.Ar expression...
+.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
 for each file in each database.
+.Pp
+By default,
+.Nm
+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.
+.Pp
 Its arguments are as follows:
 .Bl -tag -width Ds
+.It Fl C Ar file
+Specify an alternative configuration
+.Ar file
+in
+.Xr man.conf 5
+format.
 .It Fl M Ar manpath
 Use the colon-separated path instead of the default list of paths
 searched for
@@ -58,43 +81,15 @@ See
 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
@@ -108,34 +103,15 @@ See
 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
-By default,
-.Nm
-searches for
-.Xr mandocdb 8
-databases in the default paths stipulated by
-.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 .
 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),
@@ -144,18 +120,10 @@ 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
-.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
+.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 .
@@ -232,42 +200,63 @@ Text production:
 .Sh ENVIRONMENT
 .Bl -tag -width Ds
 .It Ev MANPATH
-Colon-separated paths overriding the default list of paths searched for
+Colon-separated paths modifying the default list of paths searched for
 manual databases.
 Invalid paths, or paths without manual databases, are ignored.
 Overridden by
 .Fl M .
+If
+.Ev MANPATH
+begins with a
+.Sq \&: ,
+it is appended to the default list;
+else if it ends with
+.Sq \&: ,
+it is prepended to the default list; else if it contains
+.Sq \&:: ,
+the default list is inserted between the colons.
+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
+name of the
+.Xr mandocdb 8
+keyword database
+.It Pa /etc/man.conf
+default
+.Xr man 1
+configuration file
+.El
 .Sh EXIT STATUS
 .Ex -std
 .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 man 1 ,
-.Xr re_format 7 ,
+.Xr glob 7 ,
 .Xr mandocdb 8
 .Sh AUTHORS
 The