=================================================================== RCS file: /cvs/mandoc/apropos.1,v retrieving revision 1.16.2.4 retrieving revision 1.22 diff -u -p -r1.16.2.4 -r1.22 --- mandoc/apropos.1 2014/03/17 09:52:42 1.16.2.4 +++ mandoc/apropos.1 2013/10/01 20:56:18 1.22 @@ -1,4 +1,4 @@ -.\" $Id: apropos.1,v 1.16.2.4 2014/03/17 09:52:42 schwarze Exp $ +.\" $Id: apropos.1,v 1.22 2013/10/01 20:56:18 schwarze Exp $ .\" .\" Copyright (c) 2011, 2012 Kristaps Dzonsons .\" @@ -14,11 +14,12 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: March 17 2014 $ +.Dd $Mdocdate: October 1 2013 $ .Dt APROPOS 1 .Os .Sh NAME -.Nm apropos +.Nm apropos , +.Nm whatis .Nd search manual page databases .Sh SYNOPSIS .Nm @@ -30,8 +31,10 @@ .Ar expression ... .Sh DESCRIPTION The -.Nm -utility queries manual page databases generated by +.Nm apropos +and +.Nm whatis +utilities query manual page databases generated by .Xr mandocdb 8 , evaluating on .Ar expression @@ -42,13 +45,12 @@ By default, searches for .Xr mandocdb 8 databases in the default paths stipulated by -.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 . +.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. .Pp Its arguments are as follows: .Bl -tag -width Ds @@ -71,57 +73,23 @@ for databases. Invalid paths, or paths without manual databases, are ignored. .It Fl S Ar arch -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. +Search only for a particular architecture. +.It Fl s Ar cat +Search only for a manual section. See .Xr man 1 -for a listing of sections. +for a listing of manual sections. .El .Pp -An +.Nm whatis +considers 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. -.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 +to consist of an opaque keyword. +.Nm apropos +parses a +.Ar expression +into type and keyword pairs. +This pair syntax .Li [key[,key]*(=~)]?val , where operand .Cm key @@ -135,22 +103,15 @@ See for a list of available keys. Operator .Li \&= -evaluates a substring, while +evaluates a full string, while .Li \&~ -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 +evaluates a +.Xr glob 7 +pattern. .Pp Results are sorted by manual title, with output formatted as -.Pp -.D1 title(sec) \- description -.Pp -Where +.Qq title(sec) \- description +where .Qq title is the manual's title (note multiple manual names may exist for one title), @@ -159,18 +120,10 @@ 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 -.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 +.Qq title(cat/arch) \- description . .Ss Macro Keys -Queries evaluate over a subset of +.Nm apropos +queries evaluate over a subset of .Xr mdoc 7 macros indexed by .Xr mandocdb 8 . @@ -245,24 +198,24 @@ Text production: .It Li \&Dx Ta Dx No version reference .El .Sh ENVIRONMENT -.Bl -tag -width MANPATH +.Bl -tag -width Ds .It Ev MANPATH -The standard search path used by -.Xr man 1 -may be changed by specifying a path in the -.Ev MANPATH -environment variable. +Colon-separated paths modifying the default list of paths searched for +manual databases. Invalid paths, or paths without manual databases, are ignored. Overridden by .Fl M . If .Ev MANPATH -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. +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. .El .Sh FILES .Bl -tag -width "/etc/man.conf" -compact @@ -270,10 +223,6 @@ standard search path. name of the .Xr mandocdb 8 keyword database -.It Pa mandoc.index -name of the -.Xr mandocdb 8 -filename database .It Pa /etc/man.conf default .Xr man 1 @@ -283,73 +232,34 @@ configuration file .Ex -std .Sh EXAMPLES Search for -.Qq .cf -as a substring of manual names and descriptions: +.Qq mdoc +as a word or +.Xr glob 7 +expression: .Pp -.Dl $ apropos .cf +.Dl $ apropos mdoc +.Dl $ apropos any~mdoc* .Pp Include matches for -.Qq .cnf +.Qq roff and -.Qq .conf -as well: +.Qq man +using +.Xr glob 7 +expressions: .Pp -.Dl $ apropos .cf .cnf .conf +.Dl $ apropos ~*mdoc* ~*roff* .Pp -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 +Search for .Qq optarg -variables: +as a variable name in the library category: .Pp -.Dl $ apropos \-s 3 Va=optind \-a Va=optarg -.Pp -Do exactly the same as calling -.Xr whatis 1 -with the argument -.Qq ssh : -.Pp -.Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]' +.Dl $ apropos \-s 3 Va=optarg .Sh SEE ALSO -.Xr man 1 , -.Xr re_format 7 , +.Xr glob 7 , .Xr mandocdb 8 -.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 +The .Nm -in February 1979. -The current version was written by +utility was written by .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .