=================================================================== RCS file: /cvs/mandoc/apropos.1,v retrieving revision 1.5 retrieving revision 1.10 diff -u -p -r1.5 -r1.10 --- mandoc/apropos.1 2011/11/20 15:43:14 1.5 +++ mandoc/apropos.1 2011/11/29 00:41:33 1.10 @@ -1,4 +1,4 @@ -.\" $Id: apropos.1,v 1.5 2011/11/20 15:43:14 kristaps Exp $ +.\" $Id: apropos.1,v 1.10 2011/11/29 00:41:33 kristaps Exp $ .\" .\" Copyright (c) 2011 Kristaps Dzonsons .\" @@ -14,7 +14,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: November 20 2011 $ +.Dd $Mdocdate: November 29 2011 $ .Dt APROPOS 1 .Os .Sh NAME @@ -22,6 +22,7 @@ .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 @@ -30,17 +31,24 @@ The .Nm utility queries manual page databases generated by -.Xr mandocdb 8 , +.Xr mandocdb 8 , evaluating on .Ar expression 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 -A colon-separated list of paths containing +Prepend the colon-separated paths to the list of paths searched +for .Xr mandocdb 8 databases. -Paths may be relative or absolute. +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 @@ -63,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 @@ -90,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 @@ -113,11 +123,12 @@ By default, .Nm searches for .Xr mandocdb 8 -database in the current working directory and -parses terms as case-sensitive regular expressions +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 @@ -143,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 @@ -182,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.