Add tables of matchable keys into apropos.1. Ok and with feedback by

schwarze@.

1 files changed, 82 insertions, 4 deletions

diff --git a/apropos.1 b/apropos.1
index 91c213c4..e393d6c7 100644
--- a/apropos.1
+++ b/apropos.1
@@ -97,12 +97,15 @@ is satisfied.
 This has syntax
 .Li [key[,key]*(=~)]?val ,
 where operand
-.Li key
+.Cm key
 is an
 .Xr mdoc 7
 macro to query and
-.Li val
+.Cm val
 is its value.
+See
+.Sx Macro Keys
+for a list of available keys.
 Operator
 .Li \&=
 evaluates a substring, while
@@ -122,10 +125,10 @@ searches for
 .Xr mandocdb 8
 databases in the default paths stipulated by
 .Xr man 1 ,
-parses terms as case-sensitive regular expressions
+parses terms as case-insensitive regular expressions
 .Pq the Li \&~ operator
 over manual names and descriptions
-.Pq the Li \&Nm No and Li \&Nd No macros .
+.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
@@ -151,6 +154,81 @@ Resulting manuals may be accessed as
 If an architecture is specified in the output, use
 .Pp
 .Dl $ man \-s sec \-S arch title
+.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
+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
+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
 .Sh ENVIRONMENT
 .Bl -tag -width Ds
 .It Ev MANPATH