implement -Tman .An

[mandoc.git] / apropos.1

diff --git a/apropos.1 b/apropos.1
index 027ea3f7bfab09bf1d0b9645cdc704c6aba981cd..71868aeef970d01d126c3dad43226ea5d84f9fbe 100644 (file)
--- a/apropos.1
+++ b/apropos.1
@@ -1,6 +1,6 @@
-.\"    $Id: apropos.1,v 1.5 2011/11/20 15:43:14 kristaps Exp $
+.\"    $Id: apropos.1,v 1.19 2012/06/09 14:11:15 kristaps 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,33 +14,64 @@
 .\" 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: November 20 2011 $
+.Dd $Mdocdate: June 9 2012 $

 .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
 .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 S Ar arch
 .Op Fl s Ar section
 .Op Fl m Ar manpath
 .Op Fl S Ar arch
 .Op Fl s Ar section

-.Ar expression...
+.Ar expression ...

 .Sh DESCRIPTION
 The
 .Sh DESCRIPTION
 The

-.Nm
-utility queries manual page databases generated by
-.Xr mandocdb 8 , 
+.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.
 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
 Its arguments are as follows:
 .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
 databases.
 .Xr mandocdb 8
 databases.

-Paths may be relative or absolute.
+Invalid paths, or paths without manual databases, are ignored.

 .It Fl S Ar arch
 Search only for a particular architecture.
 .It Fl s Ar cat
 .It Fl S Ar arch
 Search only for a particular architecture.
 .It Fl s Ar cat


@@ -50,81 +81,37 @@ 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.
-.Pp
-.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
 .Li [key[,key]*(=~)]?val ,
 where operand

-.Li key
+.Cm key

 is an
 .Xr mdoc 7
 macro to query and
 is an
 .Xr mdoc 7
 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
 .Li \&=
 Operator
 .Li \&=

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

 .Li \&~
 .Li \&~

-evaluates a regular expression.
-.It Fl i Ar term
-Same as
-.Ar term ,
-but
-.Ar term
-is evaluated case-insensitively.
-.El
+evaluates a
+.Xr glob 7
+pattern.

 .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
-.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),


@@ -133,72 +120,147 @@ 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

+.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
+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

-.Dl $ man \-s sec title
+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

-If an architecture is specified in the output, use
+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
 .Pp

-.Dl $ man \-s sec \-S arch title
-.\" .Sh IMPLEMENTATION NOTES
-.\" Not used in OpenBSD.
-.\" .Sh RETURN VALUES
-.\" For sections 2, 3, & 9 only.
-.\" .Sh ENVIRONMENT
-.\" For sections 1, 6, 7, & 8 only.
-.\" .Sh FILES
+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 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
 .Ex -std
 .Sh EXAMPLES
 Search for
 .Qq mdoc
 .Sh EXIT STATUS
 .Ex -std
 .Sh EXAMPLES
 Search for
 .Qq mdoc

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

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

+.Dl $ apropos any~mdoc*

 .Pp
 .Pp

-Two variants of searching for
-.Qq mdoc ,
-.Qq roff ,
-or
+Include matches for
+.Qq roff
+and

 .Qq man
 .Qq man

-within manual names and descriptions:
+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 \(dqVa~^optind$\(dq -a \(dqVa~^optarg$\(dq
-.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.
+.Dl $ apropos \-s 3 Va=optarg

 .Sh SEE ALSO
 .Sh SEE ALSO

-.Xr man 1 ,
-.Xr mandoc 1 ,
-.Xr re_format 7
-.\" .Sh STANDARDS
-.\" .Sh HISTORY
+.Xr glob 7 ,
+.Xr mandocdb 8

 .Sh AUTHORS
 The
 .Nm
 utility was written by
 .An Kristaps Dzonsons ,
 .Mt kristaps@bsd.lv .
 .Sh AUTHORS
 The
 .Nm
 utility was written by
 .An Kristaps Dzonsons ,
 .Mt kristaps@bsd.lv .

-.\" .Sh CAVEATS
-.\" .Sh BUGS
-.\" .Sh SECURITY CONSIDERATIONS
-.\" Not used in OpenBSD.