=================================================================== RCS file: /cvs/mandoc/apropos.1,v retrieving revision 1.16.2.4 retrieving revision 1.17 diff -u -p -r1.16.2.4 -r1.17 --- mandoc/apropos.1 2014/03/17 09:52:42 1.16.2.4 +++ mandoc/apropos.1 2012/03/24 01:46:25 1.17 @@ -1,4 +1,4 @@ -.\" $Id: apropos.1,v 1.16.2.4 2014/03/17 09:52:42 schwarze Exp $ +.\" $Id: apropos.1,v 1.17 2012/03/24 01:46:25 kristaps Exp $ .\" .\" Copyright (c) 2011, 2012 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: March 17 2014 $ +.Dd $Mdocdate: March 24 2012 $ .Dt APROPOS 1 .Os .Sh NAME @@ -23,8 +23,8 @@ .Sh SYNOPSIS .Nm .Op Fl C Ar file -.Op Fl M Ar path -.Op Fl m Ar path +.Op Fl M Ar manpath +.Op Fl m Ar manpath .Op Fl S Ar arch .Op Fl s Ar section .Ar expression ... @@ -44,11 +44,11 @@ searches for 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 . +over manual names and descriptions. Multiple terms imply pairwise .Fl o . +If standard output is a TTY, a result may be selected from a list and +its manual displayed with the pager. .Pp Its arguments are as follows: .Bl -tag -width Ds @@ -58,31 +58,25 @@ Specify an alternative configuration in .Xr man.conf 5 format. -.It Fl M Ar path +.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 path +.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 -Restrict the search to pages for the specified -.Xr machine 1 -architecture. -.Ar arch -is case insensitive. -By default, pages for all architectures are shown. -.It Fl s Ar section -Restrict the search to the specified section of the manual. -By default, pages from all sections are shown. +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 sections. +for a listing of manual sections. .El .Pp An @@ -162,13 +156,21 @@ If an architecture is specified for the manual, it is .Pp .D1 title(cat/arch) \- description .Pp -Resulting manuals may be accessed as +If on a TTY, results are prefixed with a numeric identifier. .Pp -.Dl $ man \-s sec title +.D1 [index] title(cat) \- description .Pp -If an architecture is specified in the output, use -.Pp -.Dl $ man \-s sec \-S arch title +One may choose a manual be entering the index at the prompt. +Valid choices are displayed using +.Ev MANPAGER , +or failing that , +.Ev PAGER +or just +.Xr more 1 . +Source pages are formatted with +.Xr mandoc 1 ; +preformatted pages with +.Xr cat 1 . .Ss Macro Keys Queries evaluate over a subset of .Xr mdoc 7 @@ -245,32 +247,40 @@ Text production: .It Li \&Dx Ta Dx No version reference .El .Sh ENVIRONMENT -.Bl -tag -width MANPATH +.Bl -tag -width Ds +.It Ev MANPAGER +Default pager for manuals. +If this is unset, falls back to +.Ev Pager . +.It Ev PAGER +The second choice for a manual pager. +If this is unset, use +.Xr more 1 . .It Ev MANPATH -The standard search path used by -.Xr man 1 -may be changed by specifying a path in the -.Ev MANPATH -environment variable. +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 colon, it is appended to the default list; -if it ends with a colon, it is prepended to the default list; -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. +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 mandoc.db +.It Pa whatis.db name of the .Xr mandocdb 8 keyword database -.It Pa mandoc.index +.It Pa whatis.index name of the .Xr mandocdb 8 filename database @@ -283,73 +293,36 @@ configuration file .Ex -std .Sh EXAMPLES Search for -.Qq .cf -as a substring of manual names and descriptions: +.Qq mdoc +as a substring and regular expression +within each manual name and description: .Pp -.Dl $ apropos .cf +.Dl $ apropos mdoc +.Dl $ apropos ~^mdoc$ .Pp Include matches for -.Qq .cnf +.Qq roff and -.Qq .conf -as well: +.Qq man +for the regular expression case: .Pp -.Dl $ apropos .cf .cnf .conf +.Dl $ apropos ~^mdoc$ roff man +.Dl $ apropos ~^mdoc$ \-o roff \-o man .Pp -Search in names and descriptions using a regular expression: -.Pp -.Dl $ apropos '~set.?[ug]id' -.Pp -Search for manuals in the library category mentioning both the +Search for .Qq optind -and the +and .Qq optarg -variables: +as variable names in the library category: .Pp -.Dl $ apropos \-s 3 Va=optind \-a Va=optarg -.Pp -Do exactly the same as calling -.Xr whatis 1 -with the argument -.Qq ssh : -.Pp -.Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]' +.Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$ .Sh SEE ALSO -.Xr man 1 , +.Xr more 1 .Xr re_format 7 , .Xr mandocdb 8 -.Sh HISTORY -An -.Nm -utility first appeared in -.Bx 2 . -It was rewritten from scratch for -.Ox 5.1 . -.Pp -The -.Fl M -option and the -.Ev MANPATH -variable first appeared in -.Bx 4.3 ; -.Fl m -in -.Bx 4.3 Reno ; -.Fl C -in -.Bx 4.4 Lite1 ; -and -.Fl S -and -.Fl s -in -.Ox 4.5 . .Sh AUTHORS -.An -nosplit -.An Bill Joy -wrote the original -.Bx +The .Nm -in February 1979. -The current version was written by -.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . +utility was written by +.An Kristaps Dzonsons , +.Mt kristaps@bsd.lv .