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

Diff for /mandoc/apropos.1 between version 1.18 and 1.24

version 1.18, 2012/06/08 10:44:52 version 1.24, 2014/04/04 15:51:28
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 C Ar file  .Op Fl C Ar file
 .Op Fl M Ar manpath  .Op Fl M Ar path
 .Op Fl m Ar manpath  .Op Fl m Ar path
   .Op Fl O Ar outkey
 .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
Line 42  By default,
Line 46  By default,
 searches for  searches for
 .Xr mandocdb 8  .Xr mandocdb 8
 databases in the default paths stipulated by  databases in the default paths stipulated by
 .Xr man 1  .Xr man 1 ,
 and  parses terms as case-sensitive regular expressions
 parses terms as case-sensitive words  .Pq the Li \&~ operator
 over manual names and descriptions.  over manual names and descriptions
 Multiple terms are OR'd.  .Pq the Li \&Nm No and Li \&Nd No macro keys .
   Multiple terms imply pairwise
   .Fl o .
   .Nm whatis
   maps terms only to case-sensitive manual names.
 .Pp  .Pp
 Its arguments are as follows:  Its arguments are as follows:
 .Bl -tag -width Ds  .Bl -tag -width Ds
Line 56  Specify an alternative configuration
Line 64  Specify an alternative configuration
 in  in
 .Xr man.conf 5  .Xr man.conf 5
 format.  format.
 .It Fl M Ar manpath  .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
 databases.  databases.
 Invalid paths, or paths without manual databases, are ignored.  Invalid paths, or paths without manual databases, are ignored.
   .It Fl O Ar outkey
   Show the values associated with the key
   .Ar outkey
   instead of the manual descriptions.
 .It Fl S Ar arch  .It Fl S Ar arch
 Search only for a particular architecture.  Restrict the search to pages for the specified
 .It Fl s Ar cat  .Xr machine 1
 Search only for a manual section.  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.
 See  See
 .Xr man 1  .Xr man 1
 for a listing of manual sections.  for a listing of sections.
 .El  .El
 .Pp  .Pp
 An  An
 .Ar expression  .Ar expression
 consists of type and keyword pairs.  consists of search terms joined by logical operators
 This pair syntax  .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 ,  .Li [key[,key]*(=~)]?val ,
 where operand  where operand
 .Cm key  .Cm key
Line 94  See
Line 145  See
 for a list of available keys.  for a list of available keys.
 Operator  Operator
 .Li \&=  .Li \&=
 evaluates a full string, while  evaluates a substring, while
 .Li \&~  .Li \&~
 evaluates a  evaluates a regular expression.
 .Xr glob 7  .It Fl i Ar term
 pattern.  If
   .Ar term
   is a regular expression, it
   is evaluated case-insensitively.
   Has no effect on substring terms.
   .El
 .Pp  .Pp
   .Nm whatis
   considers an
   .Ar expression
   to consist of an opaque keyword.
   .Pp
 Results are sorted by manual title, with output formatted as  Results are sorted by manual title, with output formatted as
 .Qq title(sec) \- description  .Pp
 where  .D1 title(sec) \- description
   .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 111  is the manual section, and
Line 174  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
 .Qq title(cat/arch) \- description .  .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  .Ss Macro Keys
 Queries evaluate over a subset of  Queries evaluate over a subset of
 .Xr mdoc 7  .Xr mdoc 7
Line 125  Names and description:
Line 197  Names and description:
 .Bl -column "xLix" description -offset indent -compact  .Bl -column "xLix" description -offset indent -compact
 .It Li \&Nm Ta manual name  .It Li \&Nm Ta manual name
 .It Li \&Nd Ta one-line manual description  .It Li \&Nd Ta one-line manual description
   .It Li arch Ta machine architecture (case-insensitive)
   .It Li sec  Ta manual section number
 .El  .El
 .Pp  .Pp
 Sections and cross references:  Sections and cross references:
Line 188  Text production:
Line 262  Text production:
 .It Li \&Dx Ta Dx No version reference  .It Li \&Dx Ta Dx No version reference
 .El  .El
 .Sh ENVIRONMENT  .Sh ENVIRONMENT
 .Bl -tag -width Ds  .Bl -tag -width MANPATH
 .It Ev MANPATH  .It Ev MANPATH
 Colon-separated paths modifying the default list of paths searched for  The standard search path used by
 manual databases.  .Xr man 1
   may be changed by specifying a path in the
   .Ev MANPATH
   environment variable.
 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  If
 .Ev MANPATH  .Ev MANPATH
 begins with a  begins with a colon, it is appended to the default list;
 .Sq \&: ,  if it ends with a colon, it is prepended to the default list;
 it is appended to the default list;  or if it contains two adjacent colons,
 else if it ends with  the standard search path is inserted between the colons.
 .Sq \&: ,  If none of these conditions are met, it overrides the
 it is prepended to the default list; else if it contains  standard search path.
 .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  .Bl -tag -width "/etc/man.conf" -compact
 .It Pa whatis.db  .It Pa mandoc.db
 name of the  name of the
 .Xr mandocdb 8  .Xr mandocdb 8
 keyword database  keyword database
 .It Pa whatis.index  
 name of the  
 .Xr mandocdb 8  
 filename database  
 .It Pa /etc/man.conf  .It Pa /etc/man.conf
 default  default
 .Xr man 1  .Xr man 1
Line 226  configuration file
Line 296  configuration file
 .Ex -std  .Ex -std
 .Sh EXAMPLES  .Sh EXAMPLES
 Search for  Search for
 .Qq mdoc  .Qq .cf
 as a word or  as a substring of manual names and descriptions:
 .Xr glob 7  
 expression:  
 .Pp  .Pp
 .Dl $ apropos mdoc  .Dl $ apropos .cf
 .Dl $ apropos any~mdoc*  
 .Pp  .Pp
 Include matches for  Include matches for
 .Qq roff  .Qq .cnf
 and  and
 .Qq man  .Qq .conf
 using  as well:
 .Xr glob 7  
 expressions:  
 .Pp  .Pp
 .Dl $ apropos ~*mdoc* ~*roff*  .Dl $ apropos .cf .cnf .conf
 .Pp  .Pp
 Search for  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
   .Qq optind
   and the
 .Qq optarg  .Qq optarg
 as a variable name in the library category:  variables:
 .Pp  .Pp
 .Dl $ apropos \-s 3 Va=optarg  .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[[:>:]]'
   .Pp
   The following two invocations are equivalent:
   .Pp
   .D1 Li $ apropos -S Ar arch Li -s Ar section expression
   .Bd -ragged -offset indent
   .Li $ apropos \e( Ar expression Li \e)
   .Li -a arch~^( Ns Ar arch Ns Li |any)$
   .Li -a sec~^ Ns Ar section Ns Li $
   .Ed
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr glob 7 ,  .Xr man 1 ,
   .Xr re_format 7 ,
 .Xr mandocdb 8  .Xr mandocdb 8
 .Sh AUTHORS  .Sh HISTORY
   An
   .Nm
   utility first appeared in
   .Bx 2 .
   It was rewritten from scratch for
   .Ox 5.6 .
   .Pp
 The  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
 .Nm  .Nm
 utility was written by  in February 1979.
 .An Kristaps Dzonsons ,  The current version was written by
 .Mt kristaps@bsd.lv .  .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
   and
   .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
Legend:
Removed from v.1.18  
changed lines
  Added in v.1.24
CVSweb