=================================================================== RCS file: /cvs/mandoc/apropos.1,v retrieving revision 1.25 retrieving revision 1.33 diff -u -p -r1.25 -r1.33 --- mandoc/apropos.1 2014/04/04 15:55:19 1.25 +++ mandoc/apropos.1 2014/08/22 04:52:55 1.33 @@ -1,4 +1,4 @@ -.\" $Id: apropos.1,v 1.25 2014/04/04 15:55:19 schwarze Exp $ +.\" $Id: apropos.1,v 1.33 2014/08/22 04:52:55 schwarze Exp $ .\" .\" Copyright (c) 2011, 2012 Kristaps Dzonsons .\" Copyright (c) 2011, 2012, 2014 Ingo Schwarze @@ -15,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: April 4 2014 $ +.Dd $Mdocdate: August 22 2014 $ .Dt APROPOS 1 .Os .Sh NAME @@ -24,6 +24,7 @@ .Nd search manual page databases .Sh SYNOPSIS .Nm +.Op Fl acfkw .Op Fl C Ar file .Op Fl M Ar path .Op Fl m Ar path @@ -37,44 +38,92 @@ The and .Nm whatis utilities query manual page databases generated by -.Xr mandocdb 8 , -evaluating on +.Xr makewhatis 8 , +evaluating .Ar expression for each file in each database. +By default, they display 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 . +.Pp .Nm whatis -maps terms only to case-sensitive manual names. +is a synonym for +.Nm +.Fl f . .Pp -Its arguments are as follows: +The options are as follows: .Bl -tag -width Ds +.It Fl a +Instead of showing only the title lines, show the complete manual pages, +just like +.Xr man 1 +.Fl a +would. +If the standard output is a terminal device and +.Fl c +is not specified, use +.Xr more 1 +to paginate them. +In +.Fl a +mode, the options +.Fl IOTW +described in the +.Xr mandoc 1 +manual are also available. .It Fl C Ar file Specify an alternative configuration .Ar file in .Xr man.conf 5 format. +.It Fl c +In +.Fl a +mode, copy the formatted manual pages to the standard output without using +.Xr more 1 +to paginate them. +.It Fl f +Search for all words in +.Ar expression +in manual page names only. +The search is case insensitive and matches whole words only. +In this mode, macro keys, comparison operators, and logical operators +are not available. +This overrides any earlier +.Fl k +option. +.It Fl k +Support the full +.Ar expression +syntax. +This overrides any earlier +.Fl f +option. +It is the default for +.Nm . .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 @@ -94,6 +143,12 @@ By default, pages from all sections are shown. See .Xr man 1 for a listing of sections. +.It Fl w +Instead of showing title lines, show the pathnames of the matching +manual pages, just like +.Xr man 1 +.Fl w +would. .El .Pp An @@ -120,34 +175,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 @@ -157,46 +218,39 @@ is evaluated case-insensitively. Has no effect on substring terms. .El .Pp -.Nm whatis -considers an -.Ar expression -to consist of an opaque keyword. +Results are sorted by manual sections and names, with output formatted as .Pp -Results are sorted by manual title, with output formatted as +.D1 name[, name...](sec) \- description .Pp -.D1 title(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. .Pp Names and description: .Bl -column "xLix" description -offset indent -compact -.It Li NAME Ta manual name in the NAME section, subset of \&Nm .It Li \&Nm Ta manual name .It Li \&Nd Ta one-line manual description .It Li arch Ta machine architecture (case-insensitive) @@ -264,7 +318,12 @@ Text production: .It Li \&Dx Ta Dx No version reference .El .Sh ENVIRONMENT -.Bl -tag -width MANPATH +.Bl -tag -width MANPAGER +.It Ev MANPAGER +Any non-empty value of the environment variable +.Ev MANPAGER +will be used instead of the standard pagination program, +.Xr more 1 . .It Ev MANPATH The standard search path used by .Xr man 1 @@ -282,12 +341,19 @@ 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. +.It Ev PAGER +Specifies the pagination program to use when +.Ev MANPAGER +is not defined. +If neither PAGER nor MANPAGER is defined, +.Pa /usr/bin/more Fl s +will be used. .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 /etc/man.conf default @@ -315,7 +381,7 @@ Search in names and descriptions using a regular expre .Pp .Dl $ apropos '~set.?[ug]id' .Pp -Search for manuals in the library category mentioning both the +Search for manuals in the library section mentioning both the .Qq optind and the .Qq optarg @@ -341,13 +407,21 @@ The following two invocations are equivalent: .Sh SEE ALSO .Xr man 1 , .Xr re_format 7 , -.Xr mandocdb 8 +.Xr makewhatis 8 .Sh HISTORY -An +Part of the functionality of +.Nm whatis +was already provided by the former +.Nm manwhere +utility in +.Bx 1 . +The .Nm -utility first appeared in +and +.Nm whatis +utilities first appeared in .Bx 2 . -It was rewritten from scratch for +They were rewritten from scratch for .Ox 5.6 . .Pp The @@ -367,13 +441,23 @@ and and .Fl s in -.Ox 4.5 . +.Ox 4.5 +for +.Nm +and in +.Ox 5.6 +for +.Nm whatis . .Sh AUTHORS .An -nosplit .An Bill Joy -wrote the original +wrote +.Nm manwhere +in 1977 and the original .Bx .Nm +and +.Nm whatis in February 1979. The current version was written by .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv