Re: Showing all possible apropls keys.

[Ingo Schwarze <schwarze@usta.de>]

Hi Kristaps,

Kristaps Dzonsons wrote on Mon, Nov 28, 2011 at 09:37:46PM +0100:

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

Yes, that's fine with me.

If you want, feel free to use the comments below.

Thanks,
  Ingo


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

Maybe "... of available keys" would be more precise?

>  Operator
>  .Li \&=
>  evaluates a substring, while
> @@ -125,7 +128,7 @@
>  parses terms as case-sensitive regular expressions
>  .Pq the Li \&~ operator

While here, you could fix that statement.
The default is exactly the opposite:
Case-insensitive substrings.

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

Any one will be confused.  ;-)

Maybe:

  In addition to the macro keys listed below, the special key
  .Cm any
  may be used to match the contents of arbitrary macros.

> +.Pp
> +Names and description:
> +.Bl -offset indent -compact -column "Brq, Bro, Brc" description

This would probably look better by reducing the width of the
first column.

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

I think in most cases, the singular sounds better, so:

  bibliographic reference

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

That's s aspecial case, i'm OK with the plural.

> +.It Li \&Cm Ta command modifier
> +.It Li \&Ar Ta command arguments

  command argument

--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv