===================================================================
RCS file: /cvs/mandoc/apropos.1,v
retrieving revision 1.10
retrieving revision 1.16
diff -u -p -r1.10 -r1.16
--- mandoc/apropos.1	2011/11/29 00:41:33	1.10
+++ mandoc/apropos.1	2011/12/25 19:35:44	1.16
@@ -1,4 +1,4 @@
-.\"	$Id: apropos.1,v 1.10 2011/11/29 00:41:33 kristaps Exp $
+.\"	$Id: apropos.1,v 1.16 2011/12/25 19:35:44 kristaps Exp $
 .\"
 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,7 +14,7 @@
 .\" 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: December 25 2011 $
 .Dt APROPOS 1
 .Os
 .Sh NAME
@@ -22,11 +22,12 @@
 .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
@@ -35,8 +36,28 @@ utility queries manual page databases generated by
 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 ,
+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
+.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
@@ -112,25 +133,13 @@ evaluates a substring, while
 .Li \&~
 evaluates a regular expression.
 .It Fl i Ar term
-Same as
-.Ar term ,
-but
+If
 .Ar term
+is a regular expression, it
 is evaluated case-insensitively.
+Has no effect on substring terms.
 .El
 .Pp
-By default,
-.Nm
-searches for
-.Xr mandocdb 8
-databases in the default paths stipulated by
-.Xr man 1 ,
-parses terms as case-insensitive 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
@@ -232,31 +241,57 @@ 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
+.Sh FILES
+.Bl -tag -width "/etc/man.conf" -compact
+.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
+configuration file
+.El
 .Sh EXIT STATUS
 .Ex -std
 .Sh EXAMPLES
 Search for
 .Qq mdoc
-within the manual name and description:
+as a substring and regular expression
+within each manual name and description:
 .Pp
 .Dl $ apropos mdoc
+.Dl $ apropos ~^mdoc$
 .Pp
-Two variants of searching for
-.Qq mdoc ,
-.Qq roff ,
-or
+Include matches for
+.Qq roff
+and
 .Qq man
-within manual names and descriptions:
+for the regular expression case:
 .Pp
-.Dl $ apropos mdoc roff man
-.Dl $ apropos mdoc \-o roff \-o man
+.Dl $ apropos ~^mdoc$ roff man
+.Dl $ apropos ~^mdoc$ \-o roff \-o man
 .Pp
 Search for
 .Qq optind
@@ -264,17 +299,11 @@ and
 .Qq optarg
 as variable names in the library category:
 .Pp
-.Dl $ apropos \-s 3 \(dqVa~^optind$\(dq -a \(dqVa~^optarg$\(dq
-.Pp
-Search for all manuals referencing
-.Qq POSIX
-in any letter case:
-.Pp
-.Dl $ apropos \-\- \-i posix
+.Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
 .Sh SEE ALSO
 .Xr man 1 ,
-.Xr mandoc 1 ,
-.Xr re_format 7
+.Xr re_format 7 ,
+.Xr mandocdb 8
 .Sh AUTHORS
 The
 .Nm