===================================================================
RCS file: /cvs/mandoc/apropos.1,v
retrieving revision 1.17
retrieving revision 1.24
diff -u -p -r1.17 -r1.24
--- mandoc/apropos.1	2012/03/24 01:46:25	1.17
+++ mandoc/apropos.1	2014/04/04 15:51:28	1.24
@@ -1,4 +1,4 @@
-.\"	$Id: apropos.1,v 1.17 2012/03/24 01:46:25 kristaps Exp $
+.\"	$Id: apropos.1,v 1.24 2014/04/04 15:51:28 schwarze Exp $
 .\"
 .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,24 +14,28 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: March 24 2012 $
+.Dd $Mdocdate: April 4 2014 $
 .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 M Ar path
+.Op Fl m Ar path
+.Op Fl O Ar outkey
 .Op Fl S Ar arch
 .Op Fl s Ar section
 .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
@@ -44,11 +48,13 @@ searches for
 databases in the default paths stipulated by
 .Xr man 1 ,
 parses terms as case-sensitive regular expressions
-over manual names and descriptions.
+.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 .
-If standard output is a TTY, a result may be selected from a list and
-its manual displayed with the pager.
+.Nm whatis
+maps terms only to case-sensitive manual names.
 .Pp
 Its arguments are as follows:
 .Bl -tag -width Ds
@@ -58,25 +64,35 @@ Specify an alternative configuration
 in
 .Xr man.conf 5
 format.
-.It Fl M Ar manpath
+.It Fl M Ar path
 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
+.It Fl m Ar path
 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 O Ar outkey
+Show the values associated with the key
+.Ar outkey
+instead of the manual descriptions.
 .It Fl S Ar arch
-Search only for a particular architecture.
-.It Fl s Ar cat
-Search only for a manual section.
+Restrict the search to pages for the specified
+.Xr machine 1
+architecture.
+.Ar arch
+is case insensitive.
+By default, pages for all architectures are shown.
+.It Fl s Ar section
+Restrict the search to the specified section of the manual.
+By default, pages from all sections are shown.
 See
 .Xr man 1
-for a listing of manual sections.
+for a listing of sections.
 .El
 .Pp
 An
@@ -140,6 +156,11 @@ is evaluated case-insensitively.
 Has no effect on substring terms.
 .El
 .Pp
+.Nm whatis
+considers an
+.Ar expression
+to consist of an opaque keyword.
+.Pp
 Results are sorted by manual title, with output formatted as
 .Pp
 .D1 title(sec) \- description
@@ -156,21 +177,13 @@ If an architecture is specified for the manual, it is 
 .Pp
 .D1 title(cat/arch) \- description
 .Pp
-If on a TTY, results are prefixed with a numeric identifier.
+Resulting manuals may be accessed as
 .Pp
-.D1 [index] title(cat) \- description
+.Dl $ man \-s sec title
 .Pp
-One may choose a manual be entering the index at the prompt.
-Valid choices are displayed using
-.Ev MANPAGER ,
-or failing that ,
-.Ev PAGER
-or just
-.Xr more 1 .
-Source pages are formatted with
-.Xr mandoc 1 ;
-preformatted pages with
-.Xr cat 1 .
+If an architecture is specified in the output, use
+.Pp
+.Dl $ man \-s sec \-S arch title
 .Ss Macro Keys
 Queries evaluate over a subset of
 .Xr mdoc 7
@@ -184,6 +197,8 @@ Names and description:
 .Bl -column "xLix" description -offset indent -compact
 .It Li \&Nm Ta manual name
 .It Li \&Nd Ta one-line manual description
+.It Li arch Ta machine architecture (case-insensitive)
+.It Li sec  Ta manual section number
 .El
 .Pp
 Sections and cross references:
@@ -247,43 +262,31 @@ Text production:
 .It Li \&Dx Ta Dx No version reference
 .El
 .Sh ENVIRONMENT
-.Bl -tag -width Ds
-.It Ev MANPAGER
-Default pager for manuals.
-If this is unset, falls back to
-.Ev Pager .
-.It Ev PAGER
-The second choice for a manual pager.
-If this is unset, use
-.Xr more 1 .
+.Bl -tag -width MANPATH
 .It Ev MANPATH
-Colon-separated paths modifying the default list of paths searched for
-manual databases.
+The standard search path used by
+.Xr man 1
+may be changed by specifying a path in the
+.Ev MANPATH
+environment variable.
 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.
+begins with a colon, it is appended to the default list;
+if it ends with a colon, it is prepended to the default list;
+or if it contains two adjacent colons,
+the standard search path is inserted between the colons.
+If none of these conditions are met, it overrides the
+standard search path.
 .El
 .Sh FILES
 .Bl -tag -width "/etc/man.conf" -compact
-.It Pa whatis.db
+.It Pa mandoc.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
@@ -293,36 +296,84 @@ configuration file
 .Ex -std
 .Sh EXAMPLES
 Search for
-.Qq mdoc
-as a substring and regular expression
-within each manual name and description:
+.Qq .cf
+as a substring of manual names and descriptions:
 .Pp
-.Dl $ apropos mdoc
-.Dl $ apropos ~^mdoc$
+.Dl $ apropos .cf
 .Pp
 Include matches for
-.Qq roff
+.Qq .cnf
 and
-.Qq man
-for the regular expression case:
+.Qq .conf
+as well:
 .Pp
-.Dl $ apropos ~^mdoc$ roff man
-.Dl $ apropos ~^mdoc$ \-o roff \-o man
+.Dl $ apropos .cf .cnf .conf
 .Pp
-Search for
+Search in names and descriptions using a regular expression:
+.Pp
+.Dl $ apropos '~set.?[ug]id'
+.Pp
+Search for manuals in the library category mentioning both the
 .Qq optind
-and
+and the
 .Qq optarg
-as variable names in the library category:
+variables:
 .Pp
-.Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
+.Dl $ apropos \-s 3 Va=optind \-a Va=optarg
+.Pp
+Do exactly the same as calling
+.Xr whatis 1
+with the argument
+.Qq ssh :
+.Pp
+.Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]'
+.Pp
+The following two invocations are equivalent:
+.Pp
+.D1 Li $ apropos -S Ar arch Li -s Ar section expression
+.Bd -ragged -offset indent
+.Li $ apropos \e( Ar expression Li \e)
+.Li -a arch~^( Ns Ar arch Ns Li |any)$
+.Li -a sec~^ Ns Ar section Ns Li $
+.Ed
 .Sh SEE ALSO
-.Xr more 1
+.Xr man 1 ,
 .Xr re_format 7 ,
 .Xr mandocdb 8
-.Sh AUTHORS
+.Sh HISTORY
+An
+.Nm
+utility first appeared in
+.Bx 2 .
+It was rewritten from scratch for
+.Ox 5.6 .
+.Pp
 The
+.Fl M
+option and the
+.Ev MANPATH
+variable first appeared in
+.Bx 4.3 ;
+.Fl m
+in
+.Bx 4.3 Reno ;
+.Fl C
+in
+.Bx 4.4 Lite1 ;
+and
+.Fl S
+and
+.Fl s
+in
+.Ox 4.5 .
+.Sh AUTHORS
+.An -nosplit
+.An Bill Joy
+wrote the original
+.Bx
 .Nm
-utility was written by
-.An Kristaps Dzonsons ,
-.Mt kristaps@bsd.lv .
+in February 1979.
+The current version was written by
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
+and
+.An Ingo Schwarze Aq Mt schwarze@openbsd.org .