Sync to OpenBSD:

* do not talk about shell globbing
* describe logical operations
* improve examples
* add HISTORY
* some wording improvements for clarity

1 files changed, 153 insertions, 57 deletions

diff --git a/apropos.1 b/apropos.1
index 09094a46..10eb3d5e 100644
--- a/apropos.1
+++ b/apropos.1
@@ -1,4 +1,4 @@
-.\"	$Id: apropos.1,v 1.22 2013/10/01 20:56:18 schwarze Exp $
+.\"	$Id: apropos.1,v 1.23 2014/03/17 09:43:56 schwarze Exp $
 .\"
 .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,7 +14,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: October 1 2013 $
+.Dd $Mdocdate: March 17 2014 $
 .Dt APROPOS 1
 .Os
 .Sh NAME
@@ -45,10 +45,13 @@ By default,
 searches for
 .Xr mandocdb 8
 databases in the default paths stipulated by
-.Xr man 1
-and
-maps terms to case-sensitive manual names and descriptions.
-Multiple terms are OR'd.
+.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 macro keys .
+Multiple terms imply pairwise
+.Fl o .
 .Nm whatis
 maps terms only to case-sensitive manual names.
 .Pp
@@ -73,23 +76,57 @@ for
 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
-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
-.Nm whatis
-considers an
+An
 .Ar expression
-to consist of an opaque keyword.
-.Nm apropos
-parses a
-.Ar expression
-into type and keyword pairs.
-This pair syntax
+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
 .Cm key
@@ -103,15 +140,27 @@ See
 for a list of available keys.
 Operator
 .Li \&=
-evaluates a full string, while
+evaluates a substring, while
 .Li \&~
-evaluates a
-.Xr glob 7
-pattern.
+evaluates a regular expression.
+.It Fl i Ar term
+If
+.Ar term
+is a regular expression, it
+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
-.Qq title(sec) \- description
-where
+.Pp
+.D1 title(sec) \- description
+.Pp
+Where
 .Qq title
 is the manual's title (note multiple manual names may exist for one
 title),
@@ -120,10 +169,18 @@ 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
-.Qq title(cat/arch) \- description .
+.Pp
+.D1 title(cat/arch) \- description
+.Pp
+Resulting manuals may be accessed as
+.Pp
+.Dl $ man \-s sec title
+.Pp
+If an architecture is specified in the output, use
+.Pp
+.Dl $ man \-s sec \-S arch title
 .Ss Macro Keys
-.Nm apropos
-queries evaluate over a subset of
+Queries evaluate over a subset of
 .Xr mdoc 7
 macros indexed by
 .Xr mandocdb 8 .
@@ -198,24 +255,24 @@ Text production:
 .It Li \&Dx Ta Dx No version reference
 .El
 .Sh ENVIRONMENT
-.Bl -tag -width Ds
+.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
@@ -232,34 +289,73 @@ configuration file
 .Ex -std
 .Sh EXAMPLES
 Search for
-.Qq mdoc
-as a word or
-.Xr glob 7
-expression:
+.Qq .cf
+as a substring of manual names and descriptions:
 .Pp
-.Dl $ apropos mdoc
-.Dl $ apropos any~mdoc*
+.Dl $ apropos .cf
 .Pp
 Include matches for
-.Qq roff
+.Qq .cnf
 and
-.Qq man
-using
-.Xr glob 7
-expressions:
+.Qq .conf
+as well:
 .Pp
-.Dl $ apropos ~*mdoc* ~*roff*
+.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 the
 .Qq optarg
-as a variable name in the library category:
+variables:
+.Pp
+.Dl $ apropos \-s 3 Va=optind \-a Va=optarg
 .Pp
-.Dl $ apropos \-s 3 Va=optarg
+Do exactly the same as calling
+.Xr whatis 1
+with the argument
+.Qq ssh :
+.Pp
+.Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]'
 .Sh SEE ALSO
-.Xr glob 7 ,
+.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.1 .
+.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
+in February 1979.
+The current version was written by
 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .