Showing all possible apropls keys.

Showing all possible apropls keys.

[Kristaps Dzonsons]

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

Hi,

Enclosed is a patch to show all possible apropos keys with apropos -k. 
I chose "-k" more or less arbitrarily.

Thoughts?

Kristaps

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

Index: apropos.1
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/apropos.1,v
retrieving revision 1.7
diff -u -r1.7 apropos.1
--- apropos.1	20 Nov 2011 21:36:00 -0000	1.7
+++ apropos.1	21 Nov 2011 17:00:59 -0000
@@ -22,6 +22,7 @@
 .Nd search manual page databases
 .Sh SYNOPSIS
 .Nm
+.Op Fl k
 .Op Fl M Ar manpath
 .Op Fl m Ar manpath
 .Op Fl S Ar arch
@@ -56,6 +57,11 @@
 See
 .Xr man 1
 for a listing of manual sections.
+.It Fl k
+List all
+.Xr mdoc 7
+keywords accepted by
+.Nm .
 .El
 .Pp
 An
Index: apropos.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/apropos.c,v
retrieving revision 1.17
diff -u -r1.17 apropos.c
--- apropos.c	20 Nov 2011 21:36:00 -0000	1.17
+++ apropos.c	21 Nov 2011 17:00:59 -0000
@@ -50,6 +50,7 @@
 static	void	 manpath_add(struct manpaths *, const char *);
 static	void	 manpath_parse(struct manpaths *, char *);
 static	void	 manpath_parseconf(struct manpaths *);
+static	void	 showkey(const char * const *, size_t, void *);
 static	void	 usage(void);
 
 static	char	*progname;
@@ -79,8 +80,11 @@
 	e = NULL;
 	rc = 0;
 
-	while (-1 != (ch = getopt(argc, argv, "M:m:S:s:"))) 
+	while (-1 != (ch = getopt(argc, argv, "kM:m:S:s:"))) 
 		switch (ch) {
+		case ('k'):
+			apropos_keys(NULL, showkey);
+			return(EXIT_SUCCESS);
 		case ('M'):
 			defpaths = optarg;
 			break;
@@ -95,7 +99,7 @@
 			break;
 		default:
 			usage();
-			goto out;
+			return(EXIT_FAILURE);
 		}
 
 	argc -= optind;
@@ -168,6 +172,7 @@
 {
 
 	fprintf(stderr, "usage: %s "
+			"[-k] "
 			"[-M dirs] "
 			"[-m dirs] "
 			"[-S arch] "
@@ -273,4 +278,13 @@
 
 	fclose(stream);
 #endif
+}
+
+static void
+showkey(const char * const *res, size_t sz, void *arg)
+{
+	int		 i;
+
+	for (i = 0; i < (int)sz; i++)
+		puts(res[i]);
 }
Index: apropos_db.c
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/apropos_db.c,v
retrieving revision 1.10
diff -u -r1.10 apropos_db.c
--- apropos_db.c	20 Nov 2011 16:29:50 -0000	1.10
+++ apropos_db.c	21 Nov 2011 17:00:59 -0000
@@ -373,6 +373,25 @@
 	return(1);
 }
 
+void
+apropos_keys(void *arg, 
+		void (*res)(const char * const *, size_t, void *))
+{
+	int		  i, len;
+	const char 	**buf;
+
+	for (len = 0; types[len].mask; len++)
+		/* Count records. */ ;
+
+	buf = mandoc_malloc(len * sizeof(char *));
+
+	for (i = 0; i < len; i++)
+		buf[i] = types[i].name;
+
+	(*res)(buf, len, arg);
+	free(buf);
+}
+
 /*
  * Search mandocdb databases in paths for expression "expr".
  * Filter out by "opts".
Index: apropos_db.h
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/apropos_db.h,v
retrieving revision 1.6
diff -u -r1.6 apropos_db.h
--- apropos_db.h	20 Nov 2011 15:43:14 -0000	1.6
+++ apropos_db.h	21 Nov 2011 17:00:59 -0000
@@ -38,6 +38,8 @@
 int	 	 apropos_search(int, char **, const struct opts *, 
 			const struct expr *, size_t, void *, 
 			void (*)(struct res *, size_t, void *));
+void		 apropos_keys(void *, void (*)(const char * const *, 
+			size_t, void *));
 struct	expr	*exprcomp(int, char *[], size_t *);
 void		 exprfree(struct expr *);
 

Re: Showing all possible apropls keys.

[Ingo Schwarze]

Hi Kristaps,

Kristaps Dzonsons wrote on Mon, Nov 21, 2011 at 06:13:44PM +0100:

> Enclosed is a patch to show all possible apropos keys with apropos
> -k. I chose "-k" more or less arbitrarily.
> 
> Thoughts?

I think that shouldn't go in.
This information doesn't belong into the program, but into the manual.

Usage() as a reaction to an unsupported option is ok, but any
additional user documentation in a program is seriously misplaced.
Well, maybe with the exception of programs intended for use in an
environment where man(1) is not available, like fdisk(8) in an
installation ramdisk.

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

Re: Showing all possible apropls keys.

[Kristaps Dzonsons]

>> Enclosed is a patch to show all possible apropos keys with apropos
>> -k. I chose "-k" more or less arbitrarily.
>>
>> Thoughts?
>
> I think that shouldn't go in.
> This information doesn't belong into the program, but into the manual.
>
> Usage() as a reaction to an unsupported option is ok, but any
> additional user documentation in a program is seriously misplaced.
> Well, maybe with the exception of programs intended for use in an
> environment where man(1) is not available, like fdisk(8) in an
> installation ramdisk.

Ingo,

I'm also more comfortable with this being in the manual -- the patch 
came about in my hesitation on just how to encode the information in a 
meaningful way, where there's bound to be many possibilities that might 
overwhelm the user for such a simple utility.

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?

Kristaps

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

Re: Showing all possible apropls keys.

[Ingo Schwarze]

Hi Kristaps,

Kristaps Dzonsons wrote on Tue, Nov 22, 2011 at 09:58:46AM +0100:

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

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

Re: Showing all possible apropls keys.

[Kristaps Dzonsons]

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

Re: Showing all possible apropls keys.

[Ingo Schwarze]

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

Re: Showing all possible apropls keys.

[Kristaps Dzonsons]

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

Ingo,

I'm merging your other comments, but this gives me pause.  The `-i' 
flips on case insensitivity: following exprcomp() into exprterm(), the 
"cs" (case-sensitive) field is 1 by default (or 0 if `-i' is specified). 
  Then in exprmark(), "cs" is acted upon with strstr() if 1, 
strcasestr() if 0.  This behaviour may have changed from the original 
version, so let's nip it if that's so.

However, the current behaviour seems consistent to me: if we want "-i" 
to mean case-insensitive, it should mean that for the following term, 
whether `~' or `=', with the opposite (sensitivity) being the default. 
No?  It seems confusing to have an `-i' but have `=' be insensitive.

Thanks again,

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

Re: Showing all possible apropls keys.

[Ingo Schwarze]

Hi Kristaps,

Kristaps Dzonsons wrote on Tue, Nov 29, 2011 at 01:34:54AM +0100:

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

> I'm merging your other comments, but this gives me pause.  The `-i'
> flips on case insensitivity: following exprcomp() into exprterm(),
> the "cs" (case-sensitive) field is 1 by default (or 0 if `-i' is
> specified).  Then in exprmark(), "cs" is acted upon with strstr() if
> 1, strcasestr() if 0.  This behaviour may have changed from the
> original version, so let's nip it if that's so.

Hum.
Indeed, "apropos.m -- -i mAnDoC" gives me results,
but "propos.m mAnDoC" doesn't.
Strange, i thought it did.

> However, the current behaviour seems consistent to me: if we want
> "-i" to mean case-insensitive, it should mean that for the following
> term, whether `~' or `=', with the opposite (sensitivity) being the
> default. No?

Yes, that would seem more consistent on first sight.

> It seems confusing to have an `-i' but have `=' be insensitive.

Well, in general, simplicity is key, and in apropos(1) in
particular.  Most of the time, you will type

  apropos something

and without much doubt, you hope to find both the legacy
something.pm Perl module and the object orient Foo::SomeThing.
Nobody will remember to type

  apropos -- -i something

and people will yell at us for not finding manuals any more and
for changing established behaviour:  apropos(1) has always been
case-insensitive.

So we can't change that for reasons of both tradition and
simplicity.  But we are free regarding regular expressions,
and people are used to the fact that regular expressions are
case sensitive by default.  Besides, when you choose REs,
you want power, and case sensitive ones are more powerful
than case-insensitive ones, so again, case-sensitive should
be the default.

Having = always case insensitive and ~ case sensitive by default
is asymmetric, but i think it's still better than having REs
case-insensitive by default and inventing a *very* non-standard
and thus even more confusion option for "case sensitive".
And changing the default for plain old apropos(1) to
case-sensitive looks completely impractical.

Sure, that means we won't have case-sensitive substring matching
at all.  But that's no problem.  It ididn't exist in the past either,
it will be needed rarely and it can easily be expressed by regular
expressions.

So we just have to fix the code and change the documentation
to read:

  =   case-insensitive substring match
  ~   case-sensitive regular expressions
  -i  make the following RE case-insensitive

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