===================================================================
RCS file: /cvs/mandoc/apropos.1,v
retrieving revision 1.4
retrieving revision 1.15
diff -u -p -r1.4 -r1.15
--- mandoc/apropos.1	2011/11/18 07:02:19	1.4
+++ mandoc/apropos.1	2011/12/25 16:53:51	1.15
@@ -1,4 +1,4 @@
-.\"	$Id: apropos.1,v 1.4 2011/11/18 07:02:19 kristaps Exp $
+.\"	$Id: apropos.1,v 1.15 2011/12/25 16:53:51 schwarze Exp $
 .\"
 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,27 +14,48 @@
 .\" 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 18 2011 $
+.Dd $Mdocdate: December 25 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 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 a manual page database generated by
-.Xr mandocdb 8 , 
+utility queries manual page databases generated by
+.Xr mandocdb 8 ,
 evaluating on
 .Ar expression
-for each file in the database.
+for each file in each database.
 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
+.Xr mandocdb 8
+databases.
+Invalid paths, or paths without manual databases, are ignored.
+.It Fl m Ar manpath
+Prepend 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 s Ar cat
@@ -57,7 +78,6 @@ The
 operator has precedence over
 .Fl o
 and both are evaluated left-to-right.
-.Pp
 .Bl -tag -width Ds
 .It \&( Ar expr No \&)
 True if the subexpression
@@ -84,31 +104,38 @@ is satisfied.
 This has syntax
 .Li [key[,key]*(=~)]?val ,
 where operand
-.Li key
+.Cm key
 is an
 .Xr mdoc 7
 macro to query and
-.Li val
+.Cm val
 is its value.
+See
+.Sx Macro Keys
+for a list of available keys.
 Operator
 .Li \&=
 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-sensitive regular expressions
 .Pq the Li \&~ operator
 over manual names and descriptions
-.Pq the Li \&Nm No and Li \&Nd No macros .
+.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
@@ -134,31 +161,135 @@ Resulting manuals may be accessed as
 If an architecture is specified in the output, use
 .Pp
 .Dl $ man \-s sec \-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.
-.\" .Sh FILES
+.Ss Macro Keys
+Queries evaluate over a subset of
+.Xr mdoc 7
+macros indexed by
+.Xr mandocdb 8 .
+In addition to the macro keys listed below, the special key
+.Cm any
+may be used to match any available macro key.
+.Pp
+Names and description:
+.Bl -column "xLix" description -offset indent -compact
+.It Li \&Nm Ta manual name
+.It Li \&Nd Ta one-line manual description
+.El
+.Pp
+Sections and cross references:
+.Bl -column "xLix" description -offset indent -compact
+.It Li \&Sh Ta section header (excluding standard sections)
+.It Li \&Ss Ta subsection header
+.It Li \&Xr Ta cross reference to another manual page
+.It Li \&Rs Ta bibliographic reference
+.El
+.Pp
+Semantic markup for command line utilities:
+.Bl -column "xLix" description -offset indent -compact
+.It Li \&Fl Ta command line options (flags)
+.It Li \&Cm Ta command modifier
+.It Li \&Ar Ta command argument
+.It Li \&Ic Ta internal or interactive command
+.It Li \&Ev Ta environmental variable
+.It Li \&Pa Ta file system path
+.El
+.Pp
+Semantic markup for function libraries:
+.Bl -column "xLix" description -offset indent -compact
+.It Li \&Lb Ta function library name
+.It Li \&In Ta include file
+.It Li \&Ft Ta function return type
+.It Li \&Fn Ta function name
+.It Li \&Fa Ta function argument type and name
+.It Li \&Vt Ta variable type
+.It Li \&Va Ta variable name
+.It Li \&Dv Ta defined variable or preprocessor constant
+.It Li \&Er Ta error constant
+.It Li \&Ev Ta environmental variable
+.El
+.Pp
+Various semantic markup:
+.Bl -column "xLix" description -offset indent -compact
+.It Li \&An Ta author name
+.It Li \&Lk Ta hyperlink
+.It Li \&Mt Ta Do mailto Dc hyperlink
+.It Li \&Cd Ta kernel configuration declaration
+.It Li \&Ms Ta mathematical symbol
+.It Li \&Tn Ta tradename
+.El
+.Pp
+Physical markup:
+.Bl -column "xLix" description -offset indent -compact
+.It Li \&Em Ta italic font or underline
+.It Li \&Sy Ta boldface font
+.It Li \&Li Ta typewriter font
+.El
+.Pp
+Text production:
+.Bl -column "xLix" description -offset indent -compact
+.It Li \&St Ta reference to a standards document
+.It Li \&At Ta At No version reference
+.It Li \&Bx Ta Bx No version reference
+.It Li \&Bsx Ta Bsx No version reference
+.It Li \&Nx Ta Nx No version reference
+.It Li \&Fx Ta Fx No version reference
+.It Li \&Ox Ta Ox No version reference
+.It Li \&Dx Ta Dx No version reference
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Ev MANPATH
+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 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
@@ -166,30 +297,14 @@ 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
-.\" .Sh DIAGNOSTICS
-.\" For sections 1, 4, 6, 7, & 8 only.
-.\" .Sh ERRORS
-.\" For sections 2, 3, & 9 only.
+.Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
 .Sh SEE ALSO
 .Xr man 1 ,
-.Xr mandoc 1 ,
-.Xr re_format 7
-.\" .Sh STANDARDS
-.\" .Sh HISTORY
+.Xr re_format 7 ,
+.Xr mandocdb 8
 .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.