[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.50

version 1.3, 2011/11/09 10:53:48 version 1.50, 2020/07/20 16:57:29
Line 1 
Line 1 
 .\"     $Id$  .\"     $Id$
 .\"  .\"
 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>  .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
   .\" Copyright (c) 2011,2012,2014,2017,2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"  .\"
 .\" 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 19 
 .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 afk
   .Op Fl C Ar file
   .Op Fl M Ar path
   .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
 .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 makewhatis 8 ,
   evaluating
   .Ar expression
   for each file in each database.
   By default, they display the names, section numbers, and description lines
   of all matching manuals.
   .Pp
   By default,
 .Nm  .Nm
 utility queries the manual page database.  searches for
 Its arguments are as follows:  .Xr makewhatis 8
   databases in the default paths stipulated by
   .Xr man 1
   and uses case-insensitive extended regular expression matching
   over manual names and descriptions
   .Pq the Li \&Nm No and Li \&Nd No macro keys .
   Multiple terms imply pairwise
   .Fl o .
   .Pp
   .Nm whatis
   is a synonym for
   .Nm
   .Fl f .
   .Pp
   The options are as follows:
 .Bl -tag -width Ds  .Bl -tag -width Ds
   .It Fl a
   Instead of showing only the title lines, show the complete manual pages,
   just like
   .Xr man 1
   .Fl a
   would.
   If the standard output is a terminal device and
   .Fl c
   is not specified, use
   .Xr less 1
   to paginate them.
   In
   .Fl a
   mode, the options
   .Fl IKOTW
   described in the
   .Xr mandoc 1
   manual are also available.
   .It Fl C Ar file
   Specify an alternative configuration
   .Ar file
   in
   .Xr man.conf 5
   format.
   .It Fl f
   Search for all words in
   .Ar expression
   in manual page names only.
   The search is case-insensitive and matches whole words only.
   In this mode, macro keys, comparison operators, and logical operators
   are not available.
   .It Fl k
   Support the full
   .Ar expression
   syntax.
   It is the default for
   .Nm .
   .It Fl M Ar path
   Use the colon-separated path instead of the default list of paths
   searched for
   .Xr makewhatis 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 makewhatis 8
   databases.
   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.
 .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,  The options
 .Nm  .Fl chlw
 searches for pattern matches of  are also supported and are documented in
 .Ar pattern  .Xr man 1 .
 in manual names and descriptions  The options
 and displays results sorted by manual title.  .Fl fkl
 Output is formatted as  are mutually exclusive and override each other.
 .Pp  .Pp
 .D1 title(sec) \- description  An
   .Ar expression
   consists of search terms joined by logical operators
   .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
   .Sq and ) .
   .It Ar expr1 Oo Fl o Oc Ar expr2
   True if
   .Ar expr1
   and/or
   .Ar expr2
   evaluate to true (logical
   .Sq or ) .
   .It Ar term
   True if
   .Ar term
   is satisfied.
   This has syntax
   .Sm off
   .Oo
   .Op Ar key Op , Ar key ...
   .Pq Cm = | \(ti
   .Oc
   .Ar val ,
   .Sm on
   where
   .Ar key
   is an
   .Xr mdoc 7
   macro to query and
   .Ar val
   is its value.
   See
   .Sx Macro Keys
   for a list of available keys.
   Operator
   .Cm =
   evaluates a substring, while
   .Cm \(ti
   evaluates a case-sensitive extended regular expression.
   .It Fl i Ar term
   If
   .Ar term
   is a regular expression, it
   is evaluated case-insensitively.
   Has no effect on substring terms.
   .El
 .Pp  .Pp
   Results are sorted first according to the section number in ascending
   numerical order, then by the page name in ascending
   .Xr ascii 7
   alphabetical order, case-insensitive.
   .Pp
   Each output line is formatted as
   .Pp
   .D1 name[, name...](sec) \- description
   .Pp
 Where  Where
 .Qq title  .Dq name
 is the manual's title (note multiple manual names may exist for one  is the manual's name,
 title),  .Dq sec
 .Qq sec  
 is the manual section, and  is the manual section, and
 .Qq description  .Dq 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  .Pp
 .D1 title(cat/arch) \- description  .D1 name(sec/arch) \- description
 .Pp  .Pp
 Resulting manuals may be accessed as  Resulting manuals may be accessed as
 .Pp  .Pp
 .Dl $ man \-s sec title  .Dl $ man \-s sec name
 .Pp  .Pp
 If an architecture is specified in the output, use  If an architecture is specified in the output, use
 .Pp  .Pp
 .Dl $ man \-s sec \-S arch title  .Dl $ man \-s sec \-S arch name
 .\" .Sh IMPLEMENTATION NOTES  .Ss Macro Keys
 .\" Not used in OpenBSD.  Queries evaluate over a subset of
 .\" .Sh RETURN VALUES  .Xr mdoc 7
 .\" For sections 2, 3, & 9 only.  macros indexed by
 .\" .Sh ENVIRONMENT  .Xr makewhatis 8 .
 .\" For sections 1, 6, 7, & 8 only.  In addition to the macro keys listed below, the special key
 .\" .Sh FILES  .Cm any
   may be used to match any available macro key.
   .Pp
   Names and description:
   .Bl -column "xLix" description -offset indent -compact
   .It Li \&Nm Ta manual name
   .It Li \&Nd Ta one-line manual description
   .It Li arch Ta machine architecture (case-insensitive)
   .It Li sec  Ta manual section number
   .El
   .Pp
   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
   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
   .Pp
   In general, macro keys are supposed to yield complete results without
   expecting the user to consider actual macro usage.
   For example, results include:
   .Pp
   .Bl -tag -width 3n -offset 3n -compact
   .It Li \&Fa
   function arguments appearing on
   .Ic \&Fn
   lines
   .It Li \&Fn
   function names marked up with
   .Ic \&Fo
   macros
   .It Li \&In
   include file names marked up with
   .Ic \&Fd
   macros
   .It Li \&Vt
   types appearing as function return types and
   .It \&
   types appearing in function arguments in the SYNOPSIS
   .El
   .Sh ENVIRONMENT
   .Bl -tag -width MANPAGER
   .It Ev MANPAGER
   Any non-empty value of the environment variable
   .Ev MANPAGER
   is used instead of the standard pagination program,
   .Xr less 1 ;
   see
   .Xr man 1
   for details.
   Only used if
   .Fl a
   or
   .Fl l
   is specified.
   .It Ev MANPATH
   A colon-separated list of directories to search for manual pages; see
   .Xr man 1
   for details.
   Overridden by
   .Fl M ,
   ignored if
   .Fl l
   is specified.
   .It Ev PAGER
   Specifies the pagination program to use when
   .Ev MANPAGER
   is not defined.
   If neither PAGER nor MANPAGER is defined,
   .Xr less 1
   is used.
   Only used if
   .Fl a
   or
   .Fl l
   is specified.
   .El
   .Sh FILES
   .Bl -tag -width "/etc/man.conf" -compact
   .It Pa mandoc.db
   name of the
   .Xr makewhatis 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 .cf
   as a substring of manual names and descriptions:
   .Pp
   .Dl $ apropos =.cf
   .Pp
   Include matches for
   .Qq .cnf
   and
   .Qq .conf
   as well:
   .Pp
   .Dl $ apropos =.cf =.cnf =.conf
   .Pp
   Search in names and descriptions using a case-sensitive regular expression:
   .Pp
   .Dl $ apropos \(aq\(tiset.?[ug]id\(aq
   .Pp
   Search for manuals in the library section mentioning both the
 .Qq optind  .Qq optind
 as a variable name in the library category:  and the
   .Qq optarg
   variables:
 .Pp  .Pp
 .Dl $ apropos \-tvar \-s 3 optind  .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
 .Pp  .Pp
 Search for all manuals referencing the term  Do exactly the same as calling
 .Qq POSIX  .Nm whatis
 in any letter case:  with the argument
   .Qq ssh :
 .Pp  .Pp
 .Dl $ apropos \-tall \-I posix  .Dl $ apropos \-\- \-i \(aqNm\(ti[[:<:]]ssh[[:>:]]\(aq
 .\" .Sh DIAGNOSTICS  .Pp
 .\" For sections 1, 4, 6, 7, & 8 only.  The following two invocations are equivalent:
 .\" .Sh ERRORS  .Pp
 .\" For sections 2, 3, & 9 only.  .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\(ti^( Ns Ar arch Ns Li |any)$
   .Li -a sec\(ti^ Ns Ar section Ns Li $
   .Ed
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr man 1 ,  .Xr man 1 ,
 .Xr mandoc 1 ,  .Xr re_format 7 ,
 .Xr re_format 7  .Xr makewhatis 8
 .\" .Sh STANDARDS  .Sh STANDARDS
 .\" .Sh HISTORY  
 .Sh AUTHORS  
 The  The
 .Nm  .Nm
 utility was written by  utility is compliant with the
 .An Kristaps Dzonsons ,  .St -p1003.1-2008
 .Mt kristaps@bsd.lv .  specification of
 .\" .Sh CAVEATS  .Xr man 1
 .\" .Sh BUGS  .Fl k .
 .\" .Sh SECURITY CONSIDERATIONS  .Pp
 .\" Not used in OpenBSD.  All options, the
   .Nm whatis
   command, support for logical operators, macro keys,
   substring matching, sorting of results, the environment variables
   .Ev MANPAGER
   and
   .Ev MANPATH ,
   the database format, and the configuration file
   are extensions to that specification.
   .Sh HISTORY
   Part of the functionality of
   .Nm whatis
   was already provided by the former
   .Nm manwhere
   utility in
   .Bx 1 .
   The
   .Nm
   and
   .Nm whatis
   utilities first appeared in
   .Bx 2 .
   They were rewritten from scratch for
   .Ox 5.6 .
   .Pp
   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
   for
   .Nm
   and in
   .Ox 5.6
   for
   .Nm whatis .
   The options
   .Fl acfhIKklOTWw
   appeared in
   .Ox 5.7 .
   .Sh AUTHORS
   .An -nosplit
   .An Bill Joy
   wrote
   .Nm manwhere
   in 1977 and the original
   .Bx
   .Nm
   and
   .Nm whatis
   in February 1979.
   The current version was written by
   .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
   and
   .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
Legend:
Removed from v.1.3  
changed lines
  Added in v.1.50
CVSweb