diff options
| -rw-r--r-- | apropos.1 | 133 |
1 files changed, 90 insertions, 43 deletions
@@ -1,6 +1,6 @@ .\" $Id$ .\" -.\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv> .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -18,8 +18,7 @@ .Dt APROPOS 1 .Os .Sh NAME -.Nm apropos , -.Nm whatis +.Nm apropos .Nd search manual page databases .Sh SYNOPSIS .Nm @@ -31,10 +30,8 @@ .Ar expression ... .Sh DESCRIPTION The -.Nm apropos -and -.Nm whatis -utilities query manual page databases generated by +.Nm +utility queries manual page databases generated by .Xr mandocdb 8 , evaluating on .Ar expression @@ -45,12 +42,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. -.Nm whatis -maps terms only to case-sensitive manual names. +.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 . .Pp Its arguments are as follows: .Bl -tag -width Ds @@ -81,15 +79,43 @@ See for a listing of manual 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 +129,22 @@ 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 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 +153,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 . @@ -219,10 +260,14 @@ If none of these conditions are met, it overrides the default list. .El .Sh FILES .Bl -tag -width "/etc/man.conf" -compact -.It Pa mandocdb.db +.It Pa whatis.db name of the .Xr mandocdb 8 keyword database +.It Pa whatis.index +name of the +.Xr mandocdb 8 +filename database .It Pa /etc/man.conf default .Xr man 1 @@ -233,33 +278,35 @@ configuration file .Sh EXAMPLES Search for .Qq mdoc -as a word or -.Xr glob 7 -expression: +as a substring and regular expression +within each manual name and description: .Pp .Dl $ apropos mdoc -.Dl $ apropos any~mdoc* +.Dl $ apropos ~^mdoc$ .Pp Include matches for .Qq roff and .Qq man -using -.Xr glob 7 -expressions: +for the regular expression case: .Pp -.Dl $ apropos ~*mdoc* ~*roff* +.Dl $ apropos ~^mdoc$ roff man +.Dl $ apropos ~^mdoc$ \-o roff \-o man .Pp Search for +.Qq optind +and .Qq optarg -as a variable name in the library category: +as variable names in the library category: .Pp -.Dl $ apropos \-s 3 Va=optarg +.Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$ .Sh SEE ALSO -.Xr glob 7 , +.Xr man 1 , +.Xr re_format 7 , .Xr mandocdb 8 .Sh AUTHORS The .Nm utility was written by -.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv . |