mandoc/apropos.1 - diff

Return to apropos.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/apropos.1 between version 1.15 and 1.21

version 1.15, 2011/12/25 16:53:51

version 1.21, 2013/07/13 19:41:16

Line 1

.\" $Id$

.\"

.\" Permission to use, copy, modify, and distribute this software for any

.\" purpose with or without fee is hereby granted, provided that the above

Line 18

.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 manpath

.Op Fl M Ar path

.Op Fl m Ar manpath

.Op Fl m Ar path

.Op Fl S Ar arch

.Op Fl s Ar section

.Ar expression ...

.Sh DESCRIPTION

The

.Nm

.Nm apropos

utility queries manual page databases generated by

and

.Nm whatis

utilities query manual page databases generated by

.Xr mandocdb 8 ,

evaluating on

.Ar expression

for each file in each database.

.Pp

By default,

.Nm

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.

.Pp

Its arguments are as follows:

.Bl -tag -width Ds

.It Fl C Ar file

Line 44 Specify an alternative configuration

Line 60 Specify an alternative configuration

.Xr man.conf 5

format.

.It Fl M Ar manpath

.It Fl M Ar path

Use the colon-separated path instead of the default list of paths

searched for

.Xr mandocdb 8

databases.

Invalid paths, or paths without manual databases, are ignored.

.It Fl m Ar manpath

.It Fl m Ar path

Prepend the colon-separated paths to the list of paths searched

for

.Xr mandocdb 8

Line 65 See

Line 81 See

for a listing of manual sections.

.El

.Pp

.Nm whatis

considers an

.Ar expression

consists of search terms joined by logical operators

to consist of an opaque keyword.

.Fl a

.Nm apropos

.Pq and

parses a

and

.Ar expression

.Fl o

into type and keyword pairs.

.Pq or .

This pair syntax

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

Line 115 See

Line 103 See

for a list of available keys.

Operator

.Li \&=

evaluates a substring, while

evaluates a full string, while

.Li \&~

evaluates a regular expression.

evaluates a

.It Fl i Ar term

.Xr glob 7

pattern.

.Ar term

is a regular expression, it

is evaluated case-insensitively.

Has no effect on substring terms.

.El

.Pp

By default,

.Nm

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 .

Results are sorted by manual title, with output formatted as

.Pp

.Qq title(sec) \- description

.D1 title(sec) \- description

where

.Pp

Where

.Qq title

is the manual's title (note multiple manual names may exist for one

title),

Line 151 is the manual section, and

Line 120 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

.Qq title(cat/arch) \- description .

.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

Queries evaluate over a subset of

.Nm apropos

queries evaluate over a subset of

.Xr mdoc 7

macros indexed by

.Xr mandocdb 8 .

Line 258 If none of these conditions are met, it overrides the

Line 219 If none of these conditions are met, it overrides the

.El

.Sh FILES

.Bl -tag -width "/etc/man.conf" -compact

.It Pa whatis.db

.It Pa mandocdb.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

Line 276 configuration file

Line 233 configuration file

.Sh EXAMPLES

Search for

.Qq mdoc

as a substring and regular expression

as a word or

within each manual name and description:

.Xr glob 7

expression:

.Pp

.Dl $ apropos mdoc

.Dl $ apropos ~^mdoc$

.Dl $ apropos any~mdoc*

.Pp

Include matches for

.Qq roff

and

.Qq man

for the regular expression case:

using

.Xr glob 7

expressions:

.Pp

.Dl $ apropos ~^mdoc$ roff man

.Dl $ apropos ~*mdoc* ~*roff*

.Dl $ apropos ~^mdoc$ \-o roff \-o man

.Pp

Search for

.Qq optind

and

.Qq optarg

as variable names in the library category:

as a variable name in the library category:

.Pp

.Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$

.Dl $ apropos \-s 3 Va=optarg

.Sh SEE ALSO

.Xr man 1 ,

.Xr glob 7 ,

.Xr re_format 7 ,

.Xr mandocdb 8

.Sh AUTHORS

The

.Nm

utility was written by

.An Kristaps Dzonsons ,

.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .

.Mt kristaps@bsd.lv .

CVSweb