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

Diff for /mandoc/apropos.1 between version 1.5 and 1.17

version 1.5, 2011/11/20 15:43:14 version 1.17, 2012/03/24 01:46:25
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 22 
Line 22 
 .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 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
 utility queries manual page databases generated by  utility queries 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 ,
   parses terms as case-sensitive regular expressions
   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:  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
   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 manpath  .It Fl m Ar manpath
 A colon-separated list of paths containing  Prepend the colon-separated paths to the list of paths searched
   for
 .Xr mandocdb 8  .Xr mandocdb 8
 databases.  databases.
 Paths may be relative or absolute.  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 63  The
Line 92  The
 operator has precedence over  operator has precedence over
 .Fl o  .Fl o
 and both are evaluated left-to-right.  and both are evaluated left-to-right.
 .Pp  
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It \&( Ar expr No \&)  .It \&( Ar expr No \&)
 True if the subexpression  True if the subexpression
Line 90  is satisfied.
Line 118  is satisfied.
 This has syntax  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 substring, while
 .Li \&~  .Li \&~
 evaluates a regular expression.  evaluates a regular expression.
 .It Fl i Ar term  .It Fl i Ar term
 Same as  If
 .Ar term ,  
 but  
 .Ar term  .Ar term
   is a regular expression, it
 is evaluated case-insensitively.  is evaluated case-insensitively.
   Has no effect on substring terms.
 .El  .El
 .Pp  .Pp
 By default,  
 .Nm  
 searches for  
 .Xr mandocdb 8  
 database in the current working directory and  
 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  .Pp
 .D1 title(sec) \- description  .D1 title(sec) \- description
Line 136  If an architecture is specified for the manual, it is 
Line 156  If an architecture is specified for the manual, it is 
 .Pp  .Pp
 .D1 title(cat/arch) \- description  .D1 title(cat/arch) \- description
 .Pp  .Pp
 Resulting manuals may be accessed as  If on a TTY, results are prefixed with a numeric identifier.
 .Pp  .Pp
 .Dl $ man \-s sec title  .D1 [index] title(cat) \- description
 .Pp  .Pp
 If an architecture is specified in the output, use  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
   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
 .Dl $ man \-s sec \-S arch title  Names and description:
 .\" .Sh IMPLEMENTATION NOTES  .Bl -column "xLix" description -offset indent -compact
 .\" Not used in OpenBSD.  .It Li \&Nm Ta manual name
 .\" .Sh RETURN VALUES  .It Li \&Nd Ta one-line manual description
 .\" For sections 2, 3, & 9 only.  .El
 .\" .Sh ENVIRONMENT  .Pp
 .\" For sections 1, 6, 7, & 8 only.  Sections and cross references:
 .\" .Sh FILES  .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
   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
   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
   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
   .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
   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 whatis.db
   name of the
   .Xr mandocdb 8
   keyword database
   .It Pa whatis.index
   name of the
   .Xr mandocdb 8
   filename 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 substring and regular expression
   within each manual name and description:
 .Pp  .Pp
 .Dl $ apropos mdoc  .Dl $ apropos mdoc
   .Dl $ apropos ~^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:  for the regular expression case:
 .Pp  .Pp
 .Dl $ apropos mdoc roff man  .Dl $ apropos ~^mdoc$ roff man
 .Dl $ apropos mdoc \-o roff \-o man  .Dl $ apropos ~^mdoc$ \-o roff \-o man
 .Pp  .Pp
 Search for  Search for
 .Qq optind  .Qq optind
Line 175  and
Line 315  and
 .Qq optarg  .Qq optarg
 as variable names in the library category:  as variable names in the library category:
 .Pp  .Pp
 .Dl $ apropos \-s 3 \(dqVa~^optind$\(dq -a \(dqVa~^optarg$\(dq  .Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
 .Pp  
 Search for all manuals referencing  
 .Qq POSIX  
 in any letter case:  
 .Pp  
 .Dl $ apropos \-\- \-i posix  
 .\" .Sh DIAGNOSTICS  
 .\" For sections 1, 4, 6, 7, & 8 only.  
 .\" .Sh ERRORS  
 .\" For sections 2, 3, & 9 only.  
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr man 1 ,  .Xr more 1
 .Xr mandoc 1 ,  .Xr re_format 7 ,
 .Xr re_format 7  .Xr mandocdb 8
 .\" .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 ,
 .Mt kristaps@bsd.lv .  .Mt kristaps@bsd.lv .
 .\" .Sh CAVEATS  
 .\" .Sh BUGS  
 .\" .Sh SECURITY CONSIDERATIONS  
 .\" Not used in OpenBSD.  
Legend:
Removed from v.1.5  
changed lines
  Added in v.1.17
CVSweb