diff options
| -rw-r--r-- | apropos.1 | 206 |
1 files changed, 151 insertions, 55 deletions
@@ -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 . |