summaryrefslogtreecommitdiffstats
path: root/apropos.1
diff options
context:
space:
mode:
authorKristaps Dzonsons <kristaps@bsd.lv>2011-11-18 07:02:19 +0000
committerKristaps Dzonsons <kristaps@bsd.lv>2011-11-18 07:02:19 +0000
commitc6a92b0f2edb58bd80173e5a0e1039832bf104fd (patch)
tree722fa6986c4ec6adbc673d3bab45cf07d50783af /apropos.1
parent608c3b4f807222334e608d25042ce5cd40c2fe4b (diff)
downloadmandoc-c6a92b0f2edb58bd80173e5a0e1039832bf104fd.tar.gz
Evaluation with logical subexpressions. This allows support for arbitrary,
nested logical subexpressions with AND (-a) and OR (-o) support.
Diffstat (limited to 'apropos.1')
-rw-r--r--apropos.1144
1 files changed, 94 insertions, 50 deletions
diff --git a/apropos.1 b/apropos.1
index 2c903f0a..9de71454 100644
--- a/apropos.1
+++ b/apropos.1
@@ -22,15 +22,17 @@
.Nd search the manual page database
.Sh SYNOPSIS
.Nm
-.Op Fl I
.Op Fl S Ar arch
.Op Fl s Ar section
-.Op Fl t Ar types
-.Ar pattern
+.Ar expression...
.Sh DESCRIPTION
The
.Nm
-utility queries the manual page database.
+utility queries a manual page database generated by
+.Xr mandocdb 8 ,
+evaluating on
+.Ar expression
+for each file in the database.
Its arguments are as follows:
.Bl -tag -width Ds
.It Fl S Ar arch
@@ -40,52 +42,76 @@ Search only for a manual section.
See
.Xr man 1
for a listing of manual sections.
-.It Fl I
-Case-insensitive pattern matching.
-.It Fl t Ar types
-Consider only types of keyword match, where
-.Ar types
-is a comma-separated list consisting of the following:
-.Ar name ,
-manual names;
-.Ar func ,
-function names;
-.Ar utility ,
-utility names;
-.Ar incl ,
-include files;
-.Ar var ,
-variable names;
-.Ar stand ,
-standards ;
-.Ar auth ,
-authors;
-.Ar conf ,
-configuration strings;
-.Ar desc ,
-descriptive text;
-.Ar xref ,
-cross-references.
-.Ar path ,
-file pathnames;
-.Ar env ,
-environment variables; or
-.Ar err ,
-error codes.
-Specifying
-.Ar all
-will search for all types.
-.It Ar key
-The search key.
+.El
+.Pp
+An
+.Ar expression
+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.
+.Pp
+.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
+.Li key
+is an
+.Xr mdoc 7
+macro to query and
+.Li val
+is its value.
+Operator
+.Li \&=
+evaluates a substring, while
+.Li \&~
+evaluates a regular expression.
+.It Fl i Ar term
+Same as
+.Ar term ,
+but
+.Ar term
+is evaluated case-insensitively.
.El
.Pp
By default,
.Nm
-searches for pattern matches of
-.Ar pattern
-in manual names and descriptions
-and displays results sorted by manual title.
-Output is formatted as
+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 macros .
+Multiple terms imply pairwise
+.Fl o .
+Results are sorted by manual title, with output formatted as
.Pp
.D1 title(sec) \- description
.Pp
@@ -119,16 +145,34 @@ If an architecture is specified in the output, use
.Ex -std
.Sh EXAMPLES
Search for
+.Qq mdoc
+within the manual name and description:
+.Pp
+.Dl $ apropos mdoc
+.Pp
+Two variants of searching for
+.Qq mdoc ,
+.Qq roff ,
+or
+.Qq man
+within manual names and descriptions:
+.Pp
+.Dl $ apropos mdoc roff man
+.Dl $ apropos mdoc \-o roff \-o man
+.Pp
+Search for
.Qq optind
-as a variable name in the library category:
+and
+.Qq optarg
+as variable names in the library category:
.Pp
-.Dl $ apropos \-tvar \-s 3 optind
+.Dl $ apropos \-s 3 \(dqVa~^optind$\(dq -a \(dqVa~^optarg$\(dq
.Pp
-Search for all manuals referencing the term
+Search for all manuals referencing
.Qq POSIX
in any letter case:
.Pp
-.Dl $ apropos \-tall \-I posix
+.Dl $ apropos \-\- \-i posix
.\" .Sh DIAGNOSTICS
.\" For sections 1, 4, 6, 7, & 8 only.
.\" .Sh ERRORS