new bug report from wiz@ regarding Tcl*(3)

[mandoc.git] / apropos.1

diff --git a/apropos.1 b/apropos.1
index bff583dfd2438701ae997dba40bf412af6f51471..09094a465437e29d44dcd53cee764ff453f4d4d7 100644 (file)
--- a/apropos.1
+++ b/apropos.1
@@ -1,6 +1,6 @@
-.\"    $Id: apropos.1,v 1.14 2011/12/24 22:37:16 kristaps Exp $
+.\"    $Id: apropos.1,v 1.22 2013/10/01 20:56:18 schwarze Exp $

 .\"
 .\"

-.\" 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
 .\" purpose with or without fee is hereby granted, provided that the above
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above


@@ -14,28 +14,44 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: December 24 2011 $
+.Dd $Mdocdate: October 1 2013 $

 .Dt APROPOS 1
 .Os
 .Sh NAME
 .Dt APROPOS 1
 .Os
 .Sh NAME

-.Nm apropos
+.Nm apropos ,
+.Nm whatis

 .Nd search manual page databases
 .Sh SYNOPSIS
 .Nm
 .Op Fl C Ar file
 .Nd search manual page databases
 .Sh SYNOPSIS
 .Nm
 .Op Fl C Ar file

-.Op Fl M Ar manpath
-.Op Fl m Ar manpath
+.Op Fl M Ar path
+.Op Fl m Ar path

 .Op Fl S Ar arch
 .Op Fl s Ar section
 .Ar expression ...
 .Sh DESCRIPTION
 The
 .Op Fl S Ar arch
 .Op Fl s Ar section
 .Ar expression ...
 .Sh DESCRIPTION
 The

-.Nm
-utility queries manual page databases generated by
+.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.
 .Xr mandocdb 8 ,
 evaluating on
 .Ar expression
 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:
 .Bl -tag -width Ds
 .It Fl C Ar file
 Its arguments are as follows:
 .Bl -tag -width Ds
 .It Fl C Ar file


@@ -44,13 +60,13 @@ Specify an alternative configuration
 in
 .Xr man.conf 5
 format.
 in
 .Xr man.conf 5
 format.

-.It Fl M Ar manpath
+.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.
 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 path

 Prepend the colon-separated paths to the list of paths searched
 for
 .Xr mandocdb 8
 Prepend the colon-separated paths to the list of paths searched
 for
 .Xr mandocdb 8


@@ -65,43 +81,15 @@ See
 for a listing of manual sections.
 .El
 .Pp
 for a listing of manual sections.
 .El
 .Pp

-An
+.Nm whatis
+considers an

 .Ar expression
 .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
-.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
+to consist of an opaque keyword.
+.Nm apropos
+parses a
+.Ar expression
+into type and keyword pairs.
+This pair syntax

 .Li [key[,key]*(=~)]?val ,
 where operand
 .Cm key
 .Li [key[,key]*(=~)]?val ,
 where operand
 .Cm key


@@ -115,34 +103,15 @@ See
 for a list of available keys.
 Operator
 .Li \&=
 for a list of available keys.
 Operator
 .Li \&=

-evaluates a substring, while
+evaluates a full string, while

 .Li \&~
 .Li \&~

-evaluates a 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
+evaluates a
+.Xr glob 7
+pattern.

 .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 macro keys .
-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
-.D1 title(sec) \- description
-.Pp
-Where
+.Qq title(sec) \- description
+where

 .Qq title
 is the manual's title (note multiple manual names may exist for one
 title),
 .Qq title
 is the manual's title (note multiple manual names may exist for one
 title),


@@ -151,18 +120,10 @@ is the manual section, and
 .Qq description
 is the manual's short description.
 If an architecture is specified for the manual, it is displayed as
 .Qq description
 is the manual's short description.
 If an architecture is specified for the manual, it is displayed as

-.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
+.Qq title(cat/arch) \- description .

 .Ss Macro Keys
 .Ss Macro Keys

-Queries evaluate over a subset of
+.Nm apropos
+queries evaluate over a subset of

 .Xr mdoc 7
 macros indexed by
 .Xr mandocdb 8 .
 .Xr mdoc 7
 macros indexed by
 .Xr mandocdb 8 .


@@ -262,10 +223,6 @@ If none of these conditions are met, it overrides the default list.
 name of the
 .Xr mandocdb 8
 keyword database
 name of the
 .Xr mandocdb 8
 keyword database

-.It Pa mandoc.index
-name of the
-.Xr mandocdb 8
-filename database

 .It Pa /etc/man.conf
 default
 .Xr man 1
 .It Pa /etc/man.conf
 default
 .Xr man 1


@@ -276,35 +233,33 @@ configuration file
 .Sh EXAMPLES
 Search for
 .Qq mdoc
 .Sh EXAMPLES
 Search for
 .Qq mdoc

-as a substring and regular expression
-within each manual name and description:
+as a word or
+.Xr glob 7
+expression:

 .Pp
 .Dl $ apropos mdoc
 .Pp
 .Dl $ apropos mdoc

-.Dl $ apropos ~^mdoc$
+.Dl $ apropos any~mdoc*

 .Pp
 Include matches for
 .Qq roff
 and
 .Qq man
 .Pp
 Include matches for
 .Qq roff
 and
 .Qq man

-for the regular expression case:
+using
+.Xr glob 7
+expressions:

 .Pp
 .Pp

-.Dl $ apropos ~^mdoc$ roff man
-.Dl $ apropos ~^mdoc$ \-o roff \-o man
+.Dl $ apropos ~*mdoc* ~*roff*

 .Pp
 Search for
 .Pp
 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 Va~^optind \-a Va~^optarg$
+.Dl $ apropos \-s 3 Va=optarg

 .Sh SEE ALSO
 .Sh SEE ALSO

-.Xr man 1 ,
-.Xr re_format 7 ,
+.Xr glob 7 ,

 .Xr mandocdb 8
 .Sh AUTHORS
 The
 .Nm
 utility was written by
 .Xr mandocdb 8
 .Sh AUTHORS
 The
 .Nm
 utility was written by

-.An Kristaps Dzonsons ,
-.Mt kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .