313 lines
7.2 KiB
Groff
313 lines
7.2 KiB
Groff
|
.\" $Vendor-Id: apropos.1,v 1.16 2011/12/25 19:35:44 kristaps Exp $
|
||
|
|
.\"
|
||
|
|
.\" 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
|
||
|
|
.\" copyright notice and this permission notice appear in all copies.
|
||
|
|
.\"
|
||
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
||
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
||
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
||
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
||
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
||
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
||
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||
|
|
.\"
|
||
|
|
.Dd December 25, 2011
|
||
|
|
.Dt APROPOS 1
|
||
|
|
.Os
|
||
|
|
.Sh NAME
|
||
|
|
.Nm apropos
|
||
|
|
.Nd search manual page databases
|
||
|
|
.Sh SYNOPSIS
|
||
|
|
.Nm
|
||
|
|
.Op Fl C Ar file
|
||
|
|
.Op Fl M Ar manpath
|
||
|
|
.Op Fl m Ar manpath
|
||
|
|
.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
|
||
|
|
.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 ,
|
||
|
|
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
|
||
|
|
.It Fl C Ar file
|
||
|
|
Specify an alternative configuration
|
||
|
|
.Ar file
|
||
|
|
in
|
||
|
|
.Xr man.conf 5
|
||
|
|
format.
|
||
|
|
.It Fl M Ar manpath
|
||
|
|
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
|
||
|
|
Prepend the colon-separated paths to the list of paths searched
|
||
|
|
for
|
||
|
|
.Xr mandocdb 8
|
||
|
|
databases.
|
||
|
|
Invalid paths, or paths without manual databases, are ignored.
|
||
|
|
.It Fl S Ar arch
|
||
|
|
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 manual sections.
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
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
|
||
|
|
.Li [key[,key]*(=~)]?val ,
|
||
|
|
where operand
|
||
|
|
.Cm key
|
||
|
|
is an
|
||
|
|
.Xr mdoc 7
|
||
|
|
macro to query and
|
||
|
|
.Cm val
|
||
|
|
is its value.
|
||
|
|
See
|
||
|
|
.Sx Macro Keys
|
||
|
|
for a list of available keys.
|
||
|
|
Operator
|
||
|
|
.Li \&=
|
||
|
|
evaluates a substring, 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
|
||
|
|
.Pp
|
||
|
|
Results are sorted by manual title, with output formatted as
|
||
|
|
.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
|
||
|
|
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
|
||
|
|
.Ss Macro Keys
|
||
|
|
Queries evaluate over a subset of
|
||
|
|
.Xr mdoc 7
|
||
|
|
macros indexed by
|
||
|
|
.Xr mandocdb 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 \&Nm Ta manual name
|
||
|
|
.It Li \&Nd Ta one-line manual description
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
Sections and cross references:
|
||
|
|
.Bl -column "xLix" description -offset indent -compact
|
||
|
|
.It Li \&Sh Ta section header (excluding standard sections)
|
||
|
|
.It Li \&Ss Ta subsection header
|
||
|
|
.It Li \&Xr Ta cross reference to another manual page
|
||
|
|
.It Li \&Rs Ta bibliographic reference
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
Semantic markup for command line utilities:
|
||
|
|
.Bl -column "xLix" description -offset indent -compact
|
||
|
|
.It Li \&Fl Ta command line options (flags)
|
||
|
|
.It Li \&Cm Ta command modifier
|
||
|
|
.It Li \&Ar Ta command argument
|
||
|
|
.It Li \&Ic Ta internal or interactive command
|
||
|
|
.It Li \&Ev Ta environmental variable
|
||
|
|
.It Li \&Pa Ta file system path
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
Semantic markup for function libraries:
|
||
|
|
.Bl -column "xLix" description -offset indent -compact
|
||
|
|
.It Li \&Lb Ta function library name
|
||
|
|
.It Li \&In Ta include file
|
||
|
|
.It Li \&Ft Ta function return type
|
||
|
|
.It Li \&Fn Ta function name
|
||
|
|
.It Li \&Fa Ta function argument type and name
|
||
|
|
.It Li \&Vt Ta variable type
|
||
|
|
.It Li \&Va Ta variable name
|
||
|
|
.It Li \&Dv Ta defined variable or preprocessor constant
|
||
|
|
.It Li \&Er Ta error constant
|
||
|
|
.It Li \&Ev Ta environmental variable
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
Various semantic markup:
|
||
|
|
.Bl -column "xLix" description -offset indent -compact
|
||
|
|
.It Li \&An Ta author name
|
||
|
|
.It Li \&Lk Ta hyperlink
|
||
|
|
.It Li \&Mt Ta Do mailto Dc hyperlink
|
||
|
|
.It Li \&Cd Ta kernel configuration declaration
|
||
|
|
.It Li \&Ms Ta mathematical symbol
|
||
|
|
.It Li \&Tn Ta tradename
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
Physical markup:
|
||
|
|
.Bl -column "xLix" description -offset indent -compact
|
||
|
|
.It Li \&Em Ta italic font or underline
|
||
|
|
.It Li \&Sy Ta boldface font
|
||
|
|
.It Li \&Li Ta typewriter font
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
Text production:
|
||
|
|
.Bl -column "xLix" description -offset indent -compact
|
||
|
|
.It Li \&St Ta reference to a standards document
|
||
|
|
.It Li \&At Ta At No version reference
|
||
|
|
.It Li \&Bx Ta Bx No version reference
|
||
|
|
.It Li \&Bsx Ta Bsx No version reference
|
||
|
|
.It Li \&Nx Ta Nx No version reference
|
||
|
|
.It Li \&Fx Ta Fx No version reference
|
||
|
|
.It Li \&Ox Ta Ox No version reference
|
||
|
|
.It Li \&Dx Ta Dx No version reference
|
||
|
|
.El
|
||
|
|
.Sh ENVIRONMENT
|
||
|
|
.Bl -tag -width Ds
|
||
|
|
.It Ev MANPATH
|
||
|
|
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
|
||
|
|
.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
|
||
|
|
.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
|
||
|
|
configuration file
|
||
|
|
.El
|
||
|
|
.Sh EXIT STATUS
|
||
|
|
.Ex -std
|
||
|
|
.Sh EXAMPLES
|
||
|
|
Search for
|
||
|
|
.Qq mdoc
|
||
|
|
as a substring and regular expression
|
||
|
|
within each manual name and description:
|
||
|
|
.Pp
|
||
|
|
.Dl $ apropos mdoc
|
||
|
|
.Dl $ apropos ~^mdoc$
|
||
|
|
.Pp
|
||
|
|
Include matches for
|
||
|
|
.Qq roff
|
||
|
|
and
|
||
|
|
.Qq man
|
||
|
|
for the regular expression case:
|
||
|
|
.Pp
|
||
|
|
.Dl $ apropos ~^mdoc$ roff man
|
||
|
|
.Dl $ apropos ~^mdoc$ \-o roff \-o man
|
||
|
|
.Pp
|
||
|
|
Search for
|
||
|
|
.Qq optind
|
||
|
|
and
|
||
|
|
.Qq optarg
|
||
|
|
as variable names in the library category:
|
||
|
|
.Pp
|
||
|
|
.Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr man 1 ,
|
||
|
|
.Xr re_format 7 ,
|
||
|
|
.Xr mandocdb 8
|
||
|
|
.Sh AUTHORS
|
||
|
|
The
|
||
|
|
.Nm
|
||
|
|
utility was written by
|
||
|
|
.An Kristaps Dzonsons ,
|
||
|
|
.Mt kristaps@bsd.lv .
|