summaryrefslogtreecommitdiffstats
path: root/apropos.1
diff options
context:
space:
mode:
authorIngo Schwarze <schwarze@openbsd.org>2014-03-17 09:43:56 +0000
committerIngo Schwarze <schwarze@openbsd.org>2014-03-17 09:43:56 +0000
commit5489c70bc373fe99b735827edbcf971cfde4537a (patch)
treee38440af2f590c23c5b96bec29ff0f2feab046e7 /apropos.1
parent8e45c6fc98a82d70bc6a02c706b2b33194d29b2b (diff)
downloadmandoc-5489c70bc373fe99b735827edbcf971cfde4537a.tar.gz
Sync to OpenBSD:
* do not talk about shell globbing * describe logical operations * improve examples * add HISTORY * some wording improvements for clarity
Diffstat (limited to 'apropos.1')
-rw-r--r--apropos.1206
1 files changed, 151 insertions, 55 deletions
diff --git a/apropos.1 b/apropos.1
index e0639cff..a316bb7c 100644
--- a/apropos.1
+++ b/apropos.1
@@ -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 .