diff options
Diffstat (limited to 'apropos.1')
| -rw-r--r-- | apropos.1 | 220 |
1 files changed, 148 insertions, 72 deletions
@@ -1,6 +1,7 @@ -.\" $Id: apropos.1,v 1.16.2.3 2013/10/05 01:25:20 schwarze Exp $ +.\" $Id: apropos.1,v 1.29 2014/04/24 00:28:19 schwarze Exp $ .\" -.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> +.\" Copyright (c) 2011, 2012, 2014 Ingo Schwarze <schwarze@openbsd.org> .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -14,41 +15,49 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: October 5 2013 $ +.Dd $Mdocdate: April 24 2014 $ .Dt APROPOS 1 .Os .Sh NAME -.Nm apropos +.Nm apropos , +.Nm whatis .Nd search manual page databases .Sh SYNOPSIS .Nm .Op Fl C Ar file .Op Fl M Ar path .Op Fl m Ar path +.Op Fl O Ar outkey .Op Fl S Ar arch .Op Fl s Ar section .Ar expression ... .Sh DESCRIPTION The -.Nm -utility queries manual page databases generated by -.Xr mandocdb 8 , -evaluating on +.Nm apropos +and +.Nm whatis +utilities query manual page databases generated by +.Xr makewhatis 8 , +evaluating .Ar expression for each file in each database. +By default, it displays the names, section numbers, and description lines +of all matching manuals. .Pp By default, .Nm searches for -.Xr mandocdb 8 +.Xr makewhatis 8 databases in the default paths stipulated by -.Xr man 1 , -parses terms as case-sensitive regular expressions -.Pq the Li \&~ operator +.Xr man 1 +and uses case-insensitive substring matching +.Pq the Cm = No 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 Its arguments are as follows: .Bl -tag -width Ds @@ -61,22 +70,32 @@ format. .It Fl M Ar path Use the colon-separated path instead of the default list of paths searched for -.Xr mandocdb 8 +.Xr makewhatis 8 databases. Invalid paths, or paths without manual databases, are ignored. .It Fl m Ar path Prepend the colon-separated paths to the list of paths searched for -.Xr mandocdb 8 +.Xr makewhatis 8 databases. Invalid paths, or paths without manual databases, are ignored. +.It Fl O Ar outkey +Show the values associated with the key +.Ar outkey +instead of the manual descriptions. .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 An @@ -103,34 +122,40 @@ True if both and .Ar expr2 are true (logical -.Qq and ) . +.Sq and ) . .It Ar expr1 Oo Fl o Oc Ar expr2 True if .Ar expr1 and/or .Ar expr2 evaluate to true (logical -.Qq or ) . +.Sq or ) . .It Ar term True if .Ar term is satisfied. This has syntax -.Li [key[,key]*(=~)]?val , -where operand -.Cm key +.Sm off +.Oo +.Op Ar key Op , Ar key ... +.Pq Cm = | ~ +.Oc +.Ar val , +.Sm on +where +.Ar key is an .Xr mdoc 7 macro to query and -.Cm val +.Ar val is its value. See .Sx Macro Keys for a list of available keys. Operator -.Li \&= +.Cm = evaluates a substring, while -.Li \&~ +.Cm ~ evaluates a regular expression. .It Fl i Ar term If @@ -140,34 +165,38 @@ is evaluated case-insensitively. Has no effect on substring terms. .El .Pp -Results are sorted by manual title, with output formatted as +.Nm whatis +considers an +.Ar expression +to consist of an opaque keyword. +.Pp +Results are sorted by manual sections and names, with output formatted as .Pp -.D1 title(sec) \- description +.D1 name[, name...](sec) \- description .Pp Where -.Qq title -is the manual's title (note multiple manual names may exist for one -title), -.Qq sec +.Dq name +is the manual's name, +.Dq sec is the manual section, and -.Qq description +.Dq 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 +.D1 name(sec/arch) \- description .Pp Resulting manuals may be accessed as .Pp -.Dl $ man \-s sec title +.Dl $ man \-s sec name .Pp If an architecture is specified in the output, use .Pp -.Dl $ man \-s sec \-S arch title +.Dl $ man \-s sec \-S arch name .Ss Macro Keys Queries evaluate over a subset of .Xr mdoc 7 macros indexed by -.Xr mandocdb 8 . +.Xr makewhatis 8 . In addition to the macro keys listed below, the special key .Cm any may be used to match any available macro key. @@ -176,6 +205,8 @@ Names and description: .Bl -column "xLix" description -offset indent -compact .It Li \&Nm Ta manual name .It Li \&Nd Ta one-line manual description +.It Li arch Ta machine architecture (case-insensitive) +.It Li sec Ta manual section number .El .Pp Sections and cross references: @@ -239,35 +270,31 @@ 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 .It Pa mandoc.db name of the -.Xr mandocdb 8 +.Xr makewhatis 8 keyword database -.It Pa mandoc.index -name of the -.Xr mandocdb 8 -filename database .It Pa /etc/man.conf default .Xr man 1 @@ -277,35 +304,84 @@ configuration file .Ex -std .Sh EXAMPLES Search for -.Qq mdoc -as a substring and regular expression -within each manual name and description: +.Qq .cf +as a substring of manual names and descriptions: .Pp -.Dl $ apropos mdoc -.Dl $ apropos ~^mdoc$ +.Dl $ apropos .cf .Pp Include matches for -.Qq roff +.Qq .cnf and -.Qq man -for the regular expression case: +.Qq .conf +as well: .Pp -.Dl $ apropos ~^mdoc$ roff man -.Dl $ apropos ~^mdoc$ \-o roff \-o man +.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 section mentioning both the .Qq optind -and +and the .Qq optarg -as variable names in the library category: +variables: .Pp -.Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$ +.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[[:>:]]' +.Pp +The following two invocations are equivalent: +.Pp +.D1 Li $ apropos -S Ar arch Li -s Ar section expression +.Bd -ragged -offset indent +.Li $ apropos \e( Ar expression Li \e) +.Li -a arch~^( Ns Ar arch Ns Li |any)$ +.Li -a sec~^ Ns Ar section Ns Li $ +.Ed .Sh SEE ALSO .Xr man 1 , .Xr re_format 7 , -.Xr mandocdb 8 -.Sh AUTHORS +.Xr makewhatis 8 +.Sh HISTORY +An +.Nm +utility first appeared in +.Bx 2 . +It was rewritten from scratch for +.Ox 5.6 . +.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 -.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . +in February 1979. +The current version was written by +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +and +.An Ingo Schwarze Aq Mt schwarze@openbsd.org . |
