===================================================================
RCS file: /cvs/mandoc/apropos.1,v
retrieving revision 1.28
retrieving revision 1.51
diff -u -p -r1.28 -r1.51
--- mandoc/apropos.1	2014/04/18 10:30:37	1.28
+++ mandoc/apropos.1	2020/10/01 22:50:00	1.51
@@ -1,7 +1,7 @@
-.\"	$Id: apropos.1,v 1.28 2014/04/18 10:30:37 schwarze Exp $
+.\" $Id: apropos.1,v 1.51 2020/10/01 22:50:00 schwarze Exp $
 .\"
 .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2011, 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2011,2012,2014,2017,2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,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: April 18 2014 $
+.Dd $Mdocdate: October 1 2020 $
 .Dt APROPOS 1
 .Os
 .Sh NAME
@@ -24,6 +24,7 @@
 .Nd search manual page databases
 .Sh SYNOPSIS
 .Nm
+.Op Fl afk
 .Op Fl C Ar file
 .Op Fl M Ar path
 .Op Fl m Ar path
@@ -41,7 +42,7 @@ utilities query manual page databases generated by
 evaluating
 .Ar expression
 for each file in each database.
-By default, it displays the names, section numbers, and description lines
+By default, they display the names, section numbers, and description lines
 of all matching manuals.
 .Pp
 By default,
@@ -50,23 +51,56 @@ searches for
 .Xr makewhatis 8
 databases in the default paths stipulated by
 .Xr man 1
-and uses case-insensitive substring matching
-.Pq the Cm = No operator
+and uses case-insensitive extended regular expression matching
 over manual names and descriptions
 .Pq the Li \&Nm No and Li \&Nd No macro keys .
 Multiple terms imply pairwise
 .Fl o .
+.Pp
 .Nm whatis
-maps terms only to case-sensitive manual names.
+is a synonym for
+.Nm
+.Fl f .
 .Pp
-Its arguments are as follows:
+The options are as follows:
 .Bl -tag -width Ds
+.It Fl a
+Instead of showing only the title lines, show the complete manual pages,
+just like
+.Xr man 1
+.Fl a
+would.
+If the standard output is a terminal device and
+.Fl c
+is not specified, use
+.Xr less 1
+to paginate them.
+In
+.Fl a
+mode, the options
+.Fl IKOTW
+described in the
+.Xr mandoc 1
+manual are also available.
 .It Fl C Ar file
 Specify an alternative configuration
 .Ar file
 in
 .Xr man.conf 5
 format.
+.It Fl f
+Search for all words in
+.Ar expression
+in manual page names only.
+The search is case-insensitive and matches whole words only.
+In this mode, macro keys, comparison operators, and logical operators
+are not available.
+.It Fl k
+Support the full
+.Ar expression
+syntax.
+It is the default for
+.Nm .
 .It Fl M Ar path
 Use the colon-separated path instead of the default list of paths
 searched for
@@ -88,7 +122,7 @@ Restrict the search to pages for the specified
 .Xr machine 1
 architecture.
 .Ar arch
-is case insensitive.
+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.
@@ -98,6 +132,14 @@ See
 for a listing of sections.
 .El
 .Pp
+The options
+.Fl chlw
+are also supported and are documented in
+.Xr man 1 .
+The options
+.Fl fkl
+are mutually exclusive and override each other.
+.Pp
 An
 .Ar expression
 consists of search terms joined by logical operators
@@ -138,10 +180,10 @@ This has syntax
 .Sm off
 .Oo
 .Op Ar key Op , Ar key ...
-.Pq Cm = | ~
+.Pq Cm = | \(ti
 .Oc
-.Ar val
-.Sm on ,
+.Ar val ,
+.Sm on
 where
 .Ar key
 is an
@@ -155,8 +197,8 @@ for a list of available keys.
 Operator
 .Cm =
 evaluates a substring, while
-.Cm ~
-evaluates a regular expression.
+.Cm \(ti
+evaluates a case-sensitive extended regular expression.
 .It Fl i Ar term
 If
 .Ar term
@@ -165,12 +207,12 @@ is evaluated case-insensitively.
 Has no effect on substring terms.
 .El
 .Pp
-.Nm whatis
-considers an
-.Ar expression
-to consist of an opaque keyword.
+Results are sorted first according to the section number in ascending
+numerical order, then by the page name in ascending
+.Xr ascii 7
+alphabetical order, case-insensitive.
 .Pp
-Results are sorted by manual sections and names, with output formatted as
+Each output line is formatted as
 .Pp
 .D1 name[, name...](sec) \- description
 .Pp
@@ -269,25 +311,65 @@ Text production:
 .It Li \&Ox Ta Ox No version reference
 .It Li \&Dx Ta Dx No version reference
 .El
+.Pp
+In general, macro keys are supposed to yield complete results without
+expecting the user to consider actual macro usage.
+For example, results include:
+.Pp
+.Bl -tag -width 3n -offset 3n -compact
+.It Li \&Fa
+function arguments appearing on
+.Ic \&Fn
+lines
+.It Li \&Fn
+function names marked up with
+.Ic \&Fo
+macros
+.It Li \&In
+include file names marked up with
+.Ic \&Fd
+macros
+.It Li \&Vt
+types appearing as function return types and
+.It \&
+types appearing in function arguments in the SYNOPSIS
+.El
 .Sh ENVIRONMENT
-.Bl -tag -width MANPATH
+.Bl -tag -width MANPAGER
+.It Ev MANPAGER
+Any non-empty value of the environment variable
+.Ev MANPAGER
+is used instead of the standard pagination program,
+.Xr less 1 ;
+see
+.Xr man 1
+for details.
+Only used if
+.Fl a
+or
+.Fl l
+is specified.
 .It Ev MANPATH
-The standard search path used by
+A colon-separated list of directories to search for manual pages; see
 .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.
+for details.
 Overridden by
-.Fl M .
-If
-.Ev MANPATH
-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.
+.Fl M ,
+ignored if
+.Fl l
+is specified.
+.It Ev PAGER
+Specifies the pagination program to use when
+.Ev MANPAGER
+is not defined.
+If neither PAGER nor MANPAGER is defined,
+.Xr less 1
+is used.
+Only used if
+.Fl a
+or
+.Fl l
+is specified.
 .El
 .Sh FILES
 .Bl -tag -width "/etc/man.conf" -compact
@@ -307,7 +389,7 @@ Search for
 .Qq .cf
 as a substring of manual names and descriptions:
 .Pp
-.Dl $ apropos .cf
+.Dl $ apropos =.cf
 .Pp
 Include matches for
 .Qq .cnf
@@ -315,12 +397,16 @@ and
 .Qq .conf
 as well:
 .Pp
-.Dl $ apropos .cf .cnf .conf
+.Dl $ apropos =.cf =.cnf =.conf
 .Pp
-Search in names and descriptions using a regular expression:
+Search in names and descriptions using a case-sensitive regular expression:
 .Pp
-.Dl $ apropos '~set.?[ug]id'
+.Dl $ apropos \(aq\(tiset.?[ug]id\(aq
 .Pp
+Search for all manual pages in a given section:
+.Pp
+.Dl $ apropos \-s 9 \&.
+.Pp
 Search for manuals in the library section mentioning both the
 .Qq optind
 and the
@@ -330,30 +416,56 @@ variables:
 .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
 .Pp
 Do exactly the same as calling
-.Xr whatis 1
+.Nm whatis
 with the argument
 .Qq ssh :
 .Pp
-.Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]'
+.Dl $ apropos \-\- \-i \(aqNm\(ti[[:<:]]ssh[[:>:]]\(aq
 .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 $
+.Li -a arch\(ti^( Ns Ar arch Ns Li |any)$
+.Li -a sec\(ti^ Ns Ar section Ns Li $
 .Ed
 .Sh SEE ALSO
 .Xr man 1 ,
 .Xr re_format 7 ,
 .Xr makewhatis 8
+.Sh STANDARDS
+The
+.Nm
+utility is compliant with the
+.St -p1003.1-2008
+specification of
+.Xr man 1
+.Fl k .
+.Pp
+All options, the
+.Nm whatis
+command, support for logical operators, macro keys,
+substring matching, sorting of results, the environment variables
+.Ev MANPAGER
+and
+.Ev MANPATH ,
+the database format, and the configuration file
+are extensions to that specification.
 .Sh HISTORY
-An
+Part of the functionality of
+.Nm whatis
+was already provided by the former
+.Nm manwhere
+utility in
+.Bx 1 .
+The
 .Nm
-utility first appeared in
+and
+.Nm whatis
+utilities first appeared in
 .Bx 2 .
-It was rewritten from scratch for
+They were rewritten from scratch for
 .Ox 5.6 .
 .Pp
 The
@@ -373,13 +485,27 @@ and
 and
 .Fl s
 in
-.Ox 4.5 .
+.Ox 4.5
+for
+.Nm
+and in
+.Ox 5.6
+for
+.Nm whatis .
+The options
+.Fl acfhIKklOTWw
+appeared in
+.Ox 5.7 .
 .Sh AUTHORS
 .An -nosplit
 .An Bill Joy
-wrote the original
+wrote
+.Nm manwhere
+in 1977 and the original
 .Bx
 .Nm
+and
+.Nm whatis
 in February 1979.
 The current version was written by
 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv