===================================================================
RCS file: /cvs/mandoc/apropos.1,v
retrieving revision 1.2
retrieving revision 1.8
diff -u -p -r1.2 -r1.8
--- mandoc/apropos.1	2011/10/08 12:24:40	1.2
+++ mandoc/apropos.1	2011/11/23 10:09:30	1.8
@@ -1,4 +1,4 @@
-.\"	$Id: apropos.1,v 1.2 2011/10/08 12:24:40 kristaps Exp $
+.\"	$Id: apropos.1,v 1.8 2011/11/23 10:09:30 kristaps Exp $
 .\"
 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,106 +14,130 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: October 8 2011 $
+.Dd $Mdocdate: November 23 2011 $
 .Dt APROPOS 1
 .Os
 .Sh NAME
 .Nm apropos
-.Nd search the manual page database
+.Nd search manual page databases
 .Sh SYNOPSIS
 .Nm
-.Op Fl eIr
-.Op Fl a Ar arch
-.Op Fl c Ar cat
-.Op Fl s Ar sort
-.Op Fl t Ar types
-.Ar key
+.Op Fl M Ar manpath
+.Op Fl m Ar manpath
+.Op Fl S Ar arch
+.Op Fl s Ar section
+.Ar expression...
 .Sh DESCRIPTION
 The
 .Nm
-utility queries the manual page database.
+utility queries manual page databases generated by
+.Xr mandocdb 8 ,
+evaluating on
+.Ar expression
+for each file in each database.
 Its arguments are as follows:
 .Bl -tag -width Ds
-.It Fl a Ar arch
+.It Fl M Ar manpath
+Use the colon-separated path instead of the default list of paths
+searched for
+.Xr mandocdb 8
+databases.
+Invalid paths, or paths without manual databases, are ignored.
+.It Fl m Ar manpath
+Append the colon-separated paths to the list of paths searched
+for
+.Xr mandocdb 8
+databases.
+Invalid paths, or paths without manual databases, are ignored.
+.It Fl S Ar arch
 Search only for a particular architecture.
-.It Fl c Ar cat
-Search only for a category (manual section).
+.It Fl s Ar cat
+Search only for a manual section.
 See
 .Xr man 1
-for a listing of categories.
-.It Fl e
-Search only for exact matches (subject to
-.Fl I ) .
-.It Fl I
-Case-insensitive matching.
-.It Fl r
-Consider
-.Ar key
-to be a POSIX regular expression (subject to
-.Fl I ) .
-See
-.Xr re_format 7
-for a description of regular expressions.
-.It Fl s Ar sort
-Sorting type.
-Accepts
-.Ar cat
-to sort by category and then by title or
-.Ar title
-to sort by title (which is the default).
-.It Fl t Ar types
-Consider only types of keyword match, where
-.Ar types
-is a comma-separated list consisting of the following:
-.Ar name ,
-manual names;
-.Ar func ,
-function names;
-.Ar utility ,
-utility names;
-.Ar incl ,
-include files;
-.Ar var ,
-variable names;
-.Ar stand ,
-standards ;
-.Ar auth ,
-authors;
-.Ar conf ,
-configuration strings;
-.Ar desc ,
-descriptive text;
-.Ar xref ,
-cross-references.
-.Ar path ,
-file pathnames;
-.Ar env ,
-environment variables; or
-.Ar err ,
-error codes.
-Specifying
-.Ar all
-will search for all types.
-.It Ar key
-The search key.
+for a listing of manual sections.
 .El
 .Pp
+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
+.Li [key[,key]*(=~)]?val ,
+where operand
+.Li key
+is an
+.Xr mdoc 7
+macro to query and
+.Li val
+is its value.
+Operator
+.Li \&=
+evaluates a substring, while
+.Li \&~
+evaluates a regular expression.
+.It Fl i Ar term
+Same as
+.Ar term ,
+but
+.Ar term
+is evaluated case-insensitively.
+.El
+.Pp
 By default,
 .Nm
-searches for substring matches of
-.Ar key
-in manual names and descriptions
-and displays results by manual title.
-Output is formatted as
+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 macros .
+Multiple terms imply pairwise
+.Fl o .
+Results are sorted by manual title, with output formatted as
 .Pp
-.D1 title(cat) \- description
+.D1 title(sec) \- description
 .Pp
 Where
 .Qq title
 is the manual's title (note multiple manual names may exist for one
 title),
-.Qq cat
-is the category, and
+.Qq sec
+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
@@ -122,49 +146,60 @@ If an architecture is specified for the manual, it is 
 .Pp
 Resulting manuals may be accessed as
 .Pp
-.Dl $ man -s cat title
+.Dl $ man \-s sec title
 .Pp
 If an architecture is specified in the output, use
 .Pp
-.Dl $ man -s cat -S arch title
-.\" .Sh IMPLEMENTATION NOTES
-.\" Not used in OpenBSD.
-.\" .Sh RETURN VALUES
-.\" For sections 2, 3, & 9 only.
-.\" .Sh ENVIRONMENT
-.\" For sections 1, 6, 7, & 8 only.
+.Dl $ man \-s sec \-S arch title
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Ev MANPATH
+Comma-separated paths overriding the default list of paths searched for
+manual databases.
+Invalid paths, or paths without manual databases, are ignored.
+Takes precedence over
+.Fl M .
+.El
 .\" .Sh FILES
 .Sh EXIT STATUS
 .Ex -std
 .Sh EXAMPLES
 Search for
+.Qq mdoc
+within the manual name and description:
+.Pp
+.Dl $ apropos mdoc
+.Pp
+Two variants of searching for
+.Qq mdoc ,
+.Qq roff ,
+or
+.Qq man
+within manual names and descriptions:
+.Pp
+.Dl $ apropos mdoc roff man
+.Dl $ apropos mdoc \-o roff \-o man
+.Pp
+Search for
 .Qq optind
-as a variable name in the library category:
+and
+.Qq optarg
+as variable names in the library category:
 .Pp
-.Dl $ apropos -tvar -c 3 optind
+.Dl $ apropos \-s 3 \(dqVa~^optind$\(dq -a \(dqVa~^optarg$\(dq
 .Pp
-Search for all manuals referencing the term
+Search for all manuals referencing
 .Qq POSIX
 in any letter case:
 .Pp
-.Dl $ apropos -tall -I posix
-.\" .Sh DIAGNOSTICS
-.\" For sections 1, 4, 6, 7, & 8 only.
-.\" .Sh ERRORS
-.\" For sections 2, 3, & 9 only.
+.Dl $ apropos \-\- \-i posix
 .Sh SEE ALSO
 .Xr man 1 ,
 .Xr mandoc 1 ,
 .Xr re_format 7
-.\" .Sh STANDARDS
-.\" .Sh HISTORY
 .Sh AUTHORS
 The
 .Nm
 utility was written by
 .An Kristaps Dzonsons ,
 .Mt kristaps@bsd.lv .
-.\" .Sh CAVEATS
-.\" .Sh BUGS
-.\" .Sh SECURITY CONSIDERATIONS
-.\" Not used in OpenBSD.