Re: Showing all possible apropls keys.

[Kristaps Dzonsons <kristaps@bsd.lv>]

[-- Attachment #1: Type: text/plain, Size: 3315 bytes --]

>> My initial thought, however, was just to cut out parts of your macro
>> synopsis documentation for a two-column display, e.g.,
>>
>>   Accepted keywords are as follows:
>>
>>   Nd         description of manual page
>>   Nm         name of manual page
>>   Fn         a function name
>>   ...
>>
>> Better?
>
> Yes.
> I'd probably try to help people by giving acronyms as much as possible,
> then pointing to mdoc(7) afterwards.  A bit like:
>
>    The following search keywords are available:
>
>    NAME section content:
>      Nm   name of the manual page (defined in each page)
>      Nd   one-line description (defined in each page)
>
>    Information about command line utilities:
>      Nm   name of the command
>      Fl   flag (command line option)
>      Cm   command modifier
>      Ar   argument on the command line
>      Ic   internal or interactive command
>      Ev   environment variable
>      Pa   path name in the file system
>
>    Information about function libraries:
>      Lb   library name
>      In   include file
>      Ft   function return type
>      Fn   function name
>      Fa   function argument type and argument name
>      Vt   variable type
>      Va   variable name
>      Dv   defined variable or preprocessor constant
>      Er   error constant
>
>    Various information:
>      An   author name
>      Lk   hyperlink
>      Mt   mailto hyperlink
>      Cd   configuration declaration for kernel devices
>      Ms   mathematical symbol
>      Tn   tradename
>
>    Physical markup:
>      Em   emphasised text (italic or underlined)
>      Li   literal text (constant width)
>      Sy   symbolic text (bold face)
>
>    Section headers and cross references:
>      Sh   section header (standard section headers are not indexed)
>      Ss   subsection header
>      Xr   cross reference to another manual page
>      Rs   reference start (bibliographic block)
>      St   standards reference
>      At   AT&T UNIX version reference
>      Bx   BSD version reference
>      Bsx  BSD/OS version reference
>      Nx   NetBSD version reference
>      Fx   FreeBSD version reference
>      Ox   OpenBSD version reference
>      Dx   DragonFly version reference
>
>    These search keywords follow mdoc(7) macro names,
>    even when the manual page is written using the man(7) language
>    and even when only a formatted version of the manual is available.
>    Even in the latter two cases, searching by `Nm' and `Nd' is
>    possible, but most other search keys are not going to return
>    the page.
>
> Well, something like that.
>
> Note that in some places, i deliberately chose a different
> wording compared to mdoc(7), for two reasons:  The audience
> is different, people reading apropos(1) will use these keys
> less often than people using mdoc(7), so acronyms are more
> important.  And the purpose is slightly different, people
> using apropos(1) just need a rough understanding what the keys
> will probably return, while people reading mdoc(7) are manual
> authors or maintainers and have to understand some finer points
> about when and how to use individual macros.

Ingo,

Getting the ball rolling with this... thoughts on the enclosed patch? 
It's more or less what appears above, with most verbiage snatched 
directly from mdoc(7).

Thoughts?

Kristaps



[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 3336 bytes --]

Index: apropos.1
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/apropos.1,v
retrieving revision 1.9
diff -u -r1.9 apropos.1
--- apropos.1	26 Nov 2011 22:38:11 -0000	1.9
+++ apropos.1	28 Nov 2011 20:36:47 -0000
@@ -103,6 +103,9 @@
 macro to query and
 .Li val
 is its value.
+See
+.Sx Macro Keys
+for a list of available terms.
 Operator
 .Li \&=
 evaluates a substring, while
@@ -125,7 +128,7 @@
 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 .
+.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 @@
 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 .
+These may be any of the following or
+.Li any
+for any macro key.
+.Pp
+Names and description:
+.Bl -offset indent -compact -column "Brq, Bro, Brc" description
+.It Li \&Nm Ta manual name
+.It Li \&Nd Ta one-line manual description
+.El
+.Pp
+Sections and cross references:
+.Bl -offset indent -compact -column "Brq, Bro, Brc" description
+.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 references
+.El
+.Pp
+Semantic markup for command line utilities:
+.Bl -offset indent -compact -column "Brq, Bro, Brc" description
+.It Li \&Fl Ta command line options (flags)
+.It Li \&Cm Ta command modifier
+.It Li \&Ar Ta command arguments
+.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 -offset indent -compact -column "Brq, Bro, Brc" description
+.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 -offset indent -compact -column "Brq, Bro, Brc" description
+.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 -offset indent -compact -column "Brq, Bro, Brc" description
+.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 -offset indent -compact -column "Brq, Bro, Brc" description
+.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