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

Diff for /mandoc/apropos.1 between version 1.8 and 1.19

version 1.8, 2011/11/23 10:09:30 version 1.19, 2012/06/09 14:11:15
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 C Ar file
 .Op Fl M Ar manpath  .Op Fl M Ar manpath
 .Op Fl m Ar manpath  .Op Fl m Ar manpath
 .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 C Ar file
   Specify an alternative configuration
   .Ar file
   in
   .Xr man.conf 5
   format.
 .It Fl M Ar manpath  .It Fl M Ar manpath
 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
Line 44  searched for
Line 67  searched for
 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 manpath
 Append 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.
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
 .Li key  .Cm key
 is an  is an
 .Xr mdoc 7  .Xr mdoc 7
 macro to query and  macro to query and
 .Li val  .Cm val
 is its value.  is its value.
   See
   .Sx Macro 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-sensitive regular expressions  
 .Pq the Li \&~ operator  
 over manual names and descriptions  
 .Pq the Li \&Nm No and Li \&Nd No macros .  
 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 141  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
   .Qq title(cat/arch) \- description .
   .Ss Macro Keys
   .Nm apropos
   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  .Pp
 .D1 title(cat/arch) \- description  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  .Pp
 Resulting manuals may be accessed as  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  .Pp
 .Dl $ man \-s sec title  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  .Pp
 If an architecture is specified in the output, use  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  .Pp
 .Dl $ man \-s sec \-S arch title  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  .Sh ENVIRONMENT
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It Ev MANPATH  .It Ev MANPATH
 Comma-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.
 Takes precedence over  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 mandocdb.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
Legend:
Removed from v.1.8  
changed lines
  Added in v.1.19
CVSweb