=================================================================== RCS file: /cvs/mandoc/apropos.1,v retrieving revision 1.4 retrieving revision 1.10 diff -u -p -r1.4 -r1.10 --- mandoc/apropos.1 2011/11/18 07:02:19 1.4 +++ mandoc/apropos.1 2011/11/29 00:41:33 1.10 @@ -1,4 +1,4 @@ -.\" $Id: apropos.1,v 1.4 2011/11/18 07:02:19 kristaps Exp $ +.\" $Id: apropos.1,v 1.10 2011/11/29 00:41:33 kristaps Exp $ .\" .\" Copyright (c) 2011 Kristaps Dzonsons .\" @@ -14,27 +14,41 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: November 18 2011 $ +.Dd $Mdocdate: November 29 2011 $ .Dt APROPOS 1 .Os .Sh NAME .Nm apropos -.Nd search the manual page database +.Nd search manual page databases .Sh SYNOPSIS .Nm +.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 a manual page database generated by -.Xr mandocdb 8 , +utility queries manual page databases generated by +.Xr mandocdb 8 , evaluating on .Ar expression -for each file in the database. +for each file in each database. Its arguments are as follows: .Bl -tag -width Ds +.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 @@ -57,7 +71,6 @@ The operator has precedence over .Fl o and both are evaluated left-to-right. -.Pp .Bl -tag -width Ds .It \&( Ar expr No \&) True if the subexpression @@ -84,12 +97,15 @@ is satisfied. This has syntax .Li [key[,key]*(=~)]?val , where operand -.Li key +.Cm key is an .Xr mdoc 7 macro to query and -.Li val +.Cm val is its value. +See +.Sx Macro Keys +for a list of available keys. Operator .Li \&= evaluates a substring, while @@ -105,10 +121,14 @@ is evaluated case-insensitively. .Pp By default, .Nm -parses terms as case-sensitive regular expressions +searches for +.Xr mandocdb 8 +databases in the default paths stipulated by +.Xr man 1 , +parses terms as case-insensitive regular expressions .Pq the Li \&~ operator over manual names and descriptions -.Pq the Li \&Nm No and Li \&Nd No macros . +.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 @@ -134,12 +154,90 @@ Resulting manuals may be accessed as If an architecture is specified in the output, use .Pp .Dl $ man \-s sec \-S arch title -.\" .Sh IMPLEMENTATION NOTES -.\" Not used in OpenBSD. -.\" .Sh RETURN VALUES -.\" For sections 2, 3, & 9 only. -.\" .Sh ENVIRONMENT -.\" For sections 1, 6, 7, & 8 only. +.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 overriding the default list of paths searched for +manual databases. +Invalid paths, or paths without manual databases, are ignored. +Overridden by +.Fl M . +.El .\" .Sh FILES .Sh EXIT STATUS .Ex -std @@ -173,23 +271,13 @@ Search for all manuals referencing in any letter case: .Pp .Dl $ apropos \-\- \-i posix -.\" .Sh DIAGNOSTICS -.\" For sections 1, 4, 6, 7, & 8 only. -.\" .Sh ERRORS -.\" For sections 2, 3, & 9 only. .Sh SEE ALSO .Xr man 1 , .Xr mandoc 1 , .Xr re_format 7 -.\" .Sh STANDARDS -.\" .Sh HISTORY .Sh AUTHORS The .Nm utility was written by .An Kristaps Dzonsons , .Mt kristaps@bsd.lv . -.\" .Sh CAVEATS -.\" .Sh BUGS -.\" .Sh SECURITY CONSIDERATIONS -.\" Not used in OpenBSD.