[BACK]Return to apropos.1 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/apropos.1 between version 1.10 and 1.22

version 1.10, 2011/11/29 00:41:33 version 1.22, 2013/10/01 20:56:18
Line 1 
Line 1 
 .\"     $Id$  .\"     $Id$
 .\"  .\"
 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>  .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"  .\"
 .\" Permission to use, copy, modify, and distribute this software for any  .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above  .\" purpose with or without fee is hereby granted, provided that the above
Line 18 
Line 18 
 .Dt APROPOS 1  .Dt APROPOS 1
 .Os  .Os
 .Sh NAME  .Sh NAME
 .Nm apropos  .Nm apropos ,
   .Nm whatis
 .Nd search manual page databases  .Nd search manual page databases
 .Sh SYNOPSIS  .Sh SYNOPSIS
 .Nm  .Nm
 .Op Fl M Ar manpath  .Op Fl C Ar file
 .Op Fl m Ar manpath  .Op Fl M Ar path
   .Op Fl m Ar path
 .Op Fl S Ar arch  .Op Fl S Ar arch
 .Op Fl s Ar section  .Op Fl s Ar section
 .Ar expression...  .Ar expression ...
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm  .Nm apropos
 utility queries manual page databases generated by  and
   .Nm whatis
   utilities query manual page databases generated by
 .Xr mandocdb 8 ,  .Xr mandocdb 8 ,
 evaluating on  evaluating on
 .Ar expression  .Ar expression
 for each file in each database.  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:  Its arguments are as follows:
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It Fl M Ar manpath  .It Fl C Ar file
   Specify an alternative configuration
   .Ar file
   in
   .Xr man.conf 5
   format.
   .It Fl M Ar path
 Use the colon-separated path instead of the default list of paths  Use the colon-separated path instead of the default list of paths
 searched for  searched for
 .Xr mandocdb 8  .Xr mandocdb 8
 databases.  databases.
 Invalid paths, or paths without manual databases, are ignored.  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  Prepend the colon-separated paths to the list of paths searched
 for  for
 .Xr mandocdb 8  .Xr mandocdb 8
Line 58  See
Line 81  See
 for a listing of manual sections.  for a listing of manual sections.
 .El  .El
 .Pp  .Pp
 An  .Nm whatis
   considers an
 .Ar expression  .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 ,  .Li [key[,key]*(=~)]?val ,
 where operand  where operand
 .Cm key  .Cm key
Line 108  See
Line 103  See
 for a list of available keys.  for a list of available keys.
 Operator  Operator
 .Li \&=  .Li \&=
 evaluates a substring, while  evaluates a full string, while
 .Li \&~  .Li \&~
 evaluates a regular expression.  evaluates a
 .It Fl i Ar term  .Xr glob 7
 Same as  pattern.
 .Ar term ,  
 but  
 .Ar term  
 is evaluated case-insensitively.  
 .El  
 .Pp  .Pp
 By default,  
 .Nm  
 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 macro keys .  
 Multiple terms imply pairwise  
 .Fl o .  
 Results are sorted by manual title, with output formatted as  Results are sorted by manual title, with output formatted as
 .Pp  .Qq title(sec) \- description
 .D1 title(sec) \- description  where
 .Pp  
 Where  
 .Qq title  .Qq title
 is the manual's title (note multiple manual names may exist for one  is the manual's title (note multiple manual names may exist for one
 title),  title),
Line 144  is the manual section, and
Line 120  is the manual section, and
 .Qq description  .Qq description
 is the manual's short description.  is the manual's short description.
 If an architecture is specified for the manual, it is displayed as  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  .Ss Macro Keys
 Queries evaluate over a subset of  .Nm apropos
   queries evaluate over a subset of
 .Xr mdoc 7  .Xr mdoc 7
 macros indexed by  macros indexed by
 .Xr mandocdb 8 .  .Xr mandocdb 8 .
Line 232  Text production:
Line 200  Text production:
 .Sh ENVIRONMENT  .Sh ENVIRONMENT
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It Ev MANPATH  .It Ev MANPATH
 Colon-separated paths overriding the default list of paths searched for  Colon-separated paths modifying the default list of paths searched for
 manual databases.  manual databases.
 Invalid paths, or paths without manual databases, are ignored.  Invalid paths, or paths without manual databases, are ignored.
 Overridden by  Overridden by
 .Fl M .  .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  .El
 .\" .Sh FILES  .Sh FILES
   .Bl -tag -width "/etc/man.conf" -compact
   .It Pa mandoc.db
   name of the
   .Xr mandocdb 8
   keyword database
   .It Pa /etc/man.conf
   default
   .Xr man 1
   configuration file
   .El
 .Sh EXIT STATUS  .Sh EXIT STATUS
 .Ex -std  .Ex -std
 .Sh EXAMPLES  .Sh EXAMPLES
 Search for  Search for
 .Qq mdoc  .Qq mdoc
 within the manual name and description:  as a word or
   .Xr glob 7
   expression:
 .Pp  .Pp
 .Dl $ apropos mdoc  .Dl $ apropos mdoc
   .Dl $ apropos any~mdoc*
 .Pp  .Pp
 Two variants of searching for  Include matches for
 .Qq mdoc ,  .Qq roff
 .Qq roff ,  and
 or  
 .Qq man  .Qq man
 within manual names and descriptions:  using
   .Xr glob 7
   expressions:
 .Pp  .Pp
 .Dl $ apropos mdoc roff man  .Dl $ apropos ~*mdoc* ~*roff*
 .Dl $ apropos mdoc \-o roff \-o man  
 .Pp  .Pp
 Search for  Search for
 .Qq optind  
 and  
 .Qq optarg  .Qq optarg
 as variable names in the library category:  as a variable name in the library category:
 .Pp  .Pp
 .Dl $ apropos \-s 3 \(dqVa~^optind$\(dq -a \(dqVa~^optarg$\(dq  .Dl $ apropos \-s 3 Va=optarg
 .Pp  
 Search for all manuals referencing  
 .Qq POSIX  
 in any letter case:  
 .Pp  
 .Dl $ apropos \-\- \-i posix  
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr man 1 ,  .Xr glob 7 ,
 .Xr mandoc 1 ,  .Xr mandocdb 8
 .Xr re_format 7  
 .Sh AUTHORS  .Sh AUTHORS
 The  The
 .Nm  .Nm
 utility was written by  utility was written by
 .An Kristaps Dzonsons ,  .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
 .Mt kristaps@bsd.lv .  
Legend:
Removed from v.1.10  
changed lines
  Added in v.1.22
CVSweb