===================================================================
RCS file: /cvs/mandoc/apropos.1,v
retrieving revision 1.46
retrieving revision 1.51
diff -u -p -r1.46 -r1.51
--- mandoc/apropos.1	2017/07/04 23:40:01	1.46
+++ mandoc/apropos.1	2020/10/01 22:50:00	1.51
@@ -1,7 +1,7 @@
-.\"	$Id: apropos.1,v 1.46 2017/07/04 23:40:01 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, 2017 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: July 4 2017 $
+.Dd $Mdocdate: October 1 2020 $
 .Dt APROPOS 1
 .Os
 .Sh NAME
@@ -51,8 +51,7 @@ 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
@@ -74,7 +73,7 @@ would.
 If the standard output is a terminal device and
 .Fl c
 is not specified, use
-.Xr more 1
+.Xr less 1
 to paginate them.
 In
 .Fl a
@@ -93,7 +92,7 @@ format.
 Search for all words in
 .Ar expression
 in manual page names only.
-The search is case insensitive and matches whole words 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
@@ -123,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.
@@ -199,7 +198,7 @@ Operator
 .Cm =
 evaluates a substring, while
 .Cm \(ti
-evaluates a regular expression.
+evaluates a case-sensitive extended regular expression.
 .It Fl i Ar term
 If
 .Ar term
@@ -208,26 +207,10 @@ is evaluated case-insensitively.
 Has no effect on substring terms.
 .El
 .Pp
-Results are sorted according to the following criteria:
-.Bl -enum
-.It
-The manpath directory tree the page is found in, according to the
-order specified with
-.Fl M ,
-.Fl m ,
-the
-.Ev MANPATH
-environment variable, the
-.Xr man.conf 5
-configuration file, or the default documented in
-.Xr man.conf 5 .
-.It
-The section number in ascending numerical order.
-.It
-The page name in ascending
+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.
-.El
 .Pp
 Each output line is formatted as
 .Pp
@@ -328,13 +311,36 @@ 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 MANPAGER
 .It Ev MANPAGER
 Any non-empty value of the environment variable
 .Ev MANPAGER
 is used instead of the standard pagination program,
-.Xr more 1 ;
+.Xr less 1 ;
 see
 .Xr man 1
 for details.
@@ -357,8 +363,7 @@ Specifies the pagination program to use when
 .Ev MANPAGER
 is not defined.
 If neither PAGER nor MANPAGER is defined,
-.Xr more 1
-.Fl s
+.Xr less 1
 is used.
 Only used if
 .Fl a
@@ -384,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
@@ -392,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 \(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
@@ -425,6 +434,24 @@ The following two invocations are equivalent:
 .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
 Part of the functionality of
 .Nm whatis