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

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

version 1.3, 2011/11/09 10:53:48 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 ,
 .Nd search the manual page database  .Nm whatis
   .Nd search manual page databases
 .Sh SYNOPSIS  .Sh SYNOPSIS
 .Nm  .Nm
 .Op Fl I  .Op Fl C Ar file
   .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
 .Op Fl t Ar types  .Ar expression ...
 .Ar pattern  
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
   .Nm apropos
   and
   .Nm whatis
   utilities query manual page databases generated by
   .Xr mandocdb 8 ,
   evaluating on
   .Ar expression
   for each file in each database.
   .Pp
   By default,
 .Nm  .Nm
 utility queries the manual page database.  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 path
   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
   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  .It Fl S Ar arch
 Search only for a particular architecture.  Search only for a particular architecture.
 .It Fl s Ar cat  .It Fl s Ar cat
Line 40  Search only for a manual section.
Line 79  Search only for a manual section.
 See  See
 .Xr man 1  .Xr man 1
 for a listing of manual sections.  for a listing of manual sections.
 .It Fl I  
 Case-insensitive pattern matching.  
 .It Fl t Ar types  
 Consider only types of keyword match, where  
 .Ar types  
 is a comma-separated list consisting of the following:  
 .Ar name ,  
 manual names;  
 .Ar func ,  
 function names;  
 .Ar utility ,  
 utility names;  
 .Ar incl ,  
 include files;  
 .Ar var ,  
 variable names;  
 .Ar stand ,  
 standards ;  
 .Ar auth ,  
 authors;  
 .Ar conf ,  
 configuration strings;  
 .Ar desc ,  
 descriptive text;  
 .Ar xref ,  
 cross-references.  
 .Ar path ,  
 file pathnames;  
 .Ar env ,  
 environment variables; or  
 .Ar err ,  
 error codes.  
 Specifying  
 .Ar all  
 will search for all types.  
 .It Ar key  
 The search key.  
 .El  .El
 .Pp  .Pp
 By default,  .Nm whatis
 .Nm  considers an
 searches for pattern matches of  .Ar expression
 .Ar pattern  to consist of an opaque keyword.
 in manual names and descriptions  .Nm apropos
 and displays results sorted by manual title.  parses a
 Output is formatted as  .Ar expression
   into type and keyword pairs.
   This pair syntax
   .Li [key[,key]*(=~)]?val ,
   where operand
   .Cm key
   is an
   .Xr mdoc 7
   macro to query and
   .Cm val
   is its value.
   See
   .Sx Macro Keys
   for a list of available keys.
   Operator
   .Li \&=
   evaluates a full string, while
   .Li \&~
   evaluates a
   .Xr glob 7
   pattern.
 .Pp  .Pp
 .D1 title(sec) \- description  Results are sorted by manual title, with output formatted as
 .Pp  .Qq title(sec) \- description
 Where  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 98  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:
 .\" .Sh IMPLEMENTATION NOTES  .Bl -column "xLix" description -offset indent -compact
 .\" Not used in OpenBSD.  .It Li \&An Ta author name
 .\" .Sh RETURN VALUES  .It Li \&Lk Ta hyperlink
 .\" For sections 2, 3, & 9 only.  .It Li \&Mt Ta Do mailto Dc hyperlink
 .\" .Sh ENVIRONMENT  .It Li \&Cd Ta kernel configuration declaration
 .\" For sections 1, 6, 7, & 8 only.  .It Li \&Ms Ta mathematical symbol
 .\" .Sh FILES  .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 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
   .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
   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 optind  .Qq mdoc
 as a variable name in the library category:  as a word or
   .Xr glob 7
   expression:
 .Pp  .Pp
 .Dl $ apropos \-tvar \-s 3 optind  .Dl $ apropos mdoc
   .Dl $ apropos any~mdoc*
 .Pp  .Pp
 Search for all manuals referencing the term  Include matches for
 .Qq POSIX  .Qq roff
 in any letter case:  and
   .Qq man
   using
   .Xr glob 7
   expressions:
 .Pp  .Pp
 .Dl $ apropos \-tall \-I posix  .Dl $ apropos ~*mdoc* ~*roff*
 .\" .Sh DIAGNOSTICS  .Pp
 .\" For sections 1, 4, 6, 7, & 8 only.  Search for
 .\" .Sh ERRORS  .Qq optarg
 .\" For sections 2, 3, & 9 only.  as a variable name in the library category:
   .Pp
   .Dl $ apropos \-s 3 Va=optarg
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr man 1 ,  .Xr glob 7 ,
 .Xr mandoc 1 ,  .Xr mandocdb 8
 .Xr re_format 7  
 .\" .Sh STANDARDS  
 .\" .Sh HISTORY  
 .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 .  
 .\" .Sh CAVEATS  
 .\" .Sh BUGS  
 .\" .Sh SECURITY CONSIDERATIONS  
 .\" Not used in OpenBSD.  
Legend:
Removed from v.1.3  
changed lines
  Added in v.1.22
CVSweb