The mdoc(7) \*(Ba predefined string actually forces roman font;

[mandoc.git] / apropos.1

diff --git a/apropos.1 b/apropos.1
index fb24b60d6390da1bde012f42b57f5410288df9aa..71868aeef970d01d126c3dad43226ea5d84f9fbe 100644 (file)
--- a/apropos.1
+++ b/apropos.1
@@ -1,6 +1,6 @@
-.\"    $Id: apropos.1,v 1.1 2011/10/06 23:00:54 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,156 +14,253 @@
 .\" 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: October 6 2011 $
+.Dd $Mdocdate: June 9 2012 $

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

-.Nm apropos
-.Nd search the manual page database
+.Nm apropos ,
+.Nm whatis
+.Nd search manual page databases

 .Sh SYNOPSIS
 .Nm
 .Sh SYNOPSIS
 .Nm

-.Op Fl eIr
-.Op Fl a Ar arch
-.Op Fl c Ar cat
-.Op Fl s Ar sort
-.Op Fl t Ar types
-.Ar key
+.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
+.Ar expression ...

 .Sh DESCRIPTION
 The
 .Sh DESCRIPTION
 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:
 .Bl -tag -width Ds
 Its arguments are as follows:
 .Bl -tag -width Ds

-.It Fl a Ar arch
+.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
+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

 Search only for a particular architecture.
 Search only for a particular architecture.

-.It Fl c Ar cat
-Search only for a category (manual section).
+.It Fl s Ar cat
+Search only for a manual section.

 See
 .Xr man 1
 See
 .Xr man 1

-for a listing of categories.
-.It Fl e
-Search only for exact matches (subject to
-.Fl I ) .
-.It Fl I
-Case-insensitive matching.
-.It Fl r
-Consider
-.Ar key
-to be a POSIX regular expression (subject to
-.Fl I ) .
-See
-.Xr re_format 7
-for a description of regular expressions.
-.It Fl s Ar sort
-Sorting type.
-Accepts
-.Ar cat
-to sort by category and then by title or
-.Ar title
-to sort by title (which is the default).
-.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.
+for a listing of manual sections.

 .El
 .Pp
 .El
 .Pp

-By default,
-.Nm
-searches for substring matches of
-.Ar key
-in manual names and descriptions
-and displays results by manual title.
-Output is formatted as
-.Pp
-.D1 title(cat) \- description
+.Nm whatis
+considers an
+.Ar expression
+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
+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

-Where
+Results are sorted by manual title, with output formatted as
+.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),

-.Qq cat
-is the category, and
+.Qq sec
+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
 .Pp

-.Dl $ man -s cat 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
+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
 .Pp

-.Dl $ man -s cat -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
+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
 .Sh EXIT STATUS
 .Ex -std
 .Sh EXAMPLES
 Search for

-.Qq optind
-as a variable name in the library category:
+.Qq mdoc
+as a word or
+.Xr glob 7
+expression:
+.Pp
+.Dl $ apropos mdoc
+.Dl $ apropos any~mdoc*

 .Pp
 .Pp

-.Dl $ apropos -tvar -c 3 optind
+Include matches for
+.Qq roff
+and
+.Qq man
+using
+.Xr glob 7
+expressions:

 .Pp
 .Pp

-Search for all manuals referencing the term
-.Qq POSIX
-in any letter case:
+.Dl $ apropos ~*mdoc* ~*roff*
+.Pp
+Search for
+.Qq optarg
+as a variable name in the library category:

 .Pp
 .Pp

-.Dl $ apropos -tall -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
 .Sh AUTHORS
 The
 .Nm
 utility was written by

-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
-.\" .Sh CAVEATS
-.\" .Sh BUGS
-.\" .Sh SECURITY CONSIDERATIONS
-.\" Not used in OpenBSD.
+.An Kristaps Dzonsons ,
+.Mt kristaps@bsd.lv .