Bug 34529

David Sieb=F6rger wrote:
> --- usr.sbin/usbd/usbd.conf.5.orig=09Thu Aug 16 17:56:41 2001
> +++ usr.sbin/usbd/usbd.conf.5=09Fri Feb  1 15:57:51 2002
> @@ -64,7 +64,7 @@
>  There are 3 types of fields:
>  descriptive fields, selection criteria and commands to execute on
>  events.
> -The field name is case sensitive and should be all lower case.
> +The field names are case sensitive and should be all lower case.

Mmm, seems ok.

> -Product Id=09> -Vendor Id=09> -Release Id
> +Product ID=09> +Vendor ID=09> +Release ID

Hum, capitalization is prime time flamefest/bikeshed material.
I can't comment on this.  Someone with more 'english style' expertize
will probably know better.

> @@ -156,8 +156,8 @@
>  .Xr usbd 8 ,
>  .Xr usbdevs 8
>  .Sh BUGS
> -It is currently not possible to use a selection criterium more than once=
=2E For
> -example it is not possible to specify more than one vendor Id.
> +It is currently not possible to use a selection criterion more than once=
=2E For
> +example, it is not possible to specify more than one vendor ID.

>  .Sh AUTHORS
> -The man page for the usbd configuration file was written by
> +The manual page for the usbd configuration file was written by
>  .An Nick Hibma Aq n_hibma@FreeBSD.org .

Is this even necessary?  I haven't searched the sources for -all- the
manpages to see which have an 'AUTHORS' section.  Others do have a
section like that (ipfw.8 for instance).  What do others think?

> --- usr.sbin/usbd/usbd.8.orig=09Thu Aug 16 17:56:41 2001
> +++ usr.sbin/usbd/usbd.8=09Fri Feb  1 15:57:51 2002
> @@ -56,7 +56,7 @@
>  Through opening the
>  .Pa /dev/usb0 ,
>  .Pa /dev/usb1 ,
> -etc. devices, it enables the kernel to do handle change requests from
> +etc. devices, it enables the kernel to handle change requests from
>  attached hubs.

Good catch :)

> @@ -80,7 +80,7 @@
>  Whenever a device is attached or
>  detached the list of actions read from
>  .Pa /etc/usbd.conf
> -are searched for a matching entry.
> +is searched for a matching entry.
>  If found, the corresponding action is
>  executed.

`The list .. is searched.'  This is correct as it is IMHO.
I'm not a native speaker, and I might be wrong here, but this would
probably look OK, if written as the following:

=09Whenever a device is attached or detached,
=09the list of actions (which is read from
=09.Pa /etc/usbd.conf )
=09is searched for a matching entry.

or something similar.  What do you think?

--=20
Giorgos Keramidas . . . . . . . . . keramida@{ceid.upatras.gr,freebsd.org}
FreeBSD Documentation Project . . . http://www.freebsd.org/docproj/
FreeBSD: The power to serve . . . . http://www.freebsd.org/

On Fri, Feb 01, 2002 at 09:16:53PM +0200, Giorgos Keramidas wrote:
[snip]
> David Sieborger wrote:
> > -Product Id	> -Vendor Id	> -Release Id
> > +Product ID	> +Vendor ID	> +Release ID
> 
> Hum, capitalization is prime time flamefest/bikeshed material.
> I can't comment on this.  Someone with more 'english style' expertize
> will probably know better.

Thinking about it again (and looking in the dictionary), perhaps
"I.D." might be better.  I guessed that "Id" must've come from the
capitalisation used in variable names like "customerIdNumber".  But
if this is a contentious point, perhaps it should be left unchanged.

[snip]
> >  Whenever a device is attached or
> >  detached the list of actions read from
> >  .Pa /etc/usbd.conf
> > -are searched for a matching entry.
> > +is searched for a matching entry.
> >  If found, the corresponding action is
> >  executed.
> 
> `The list .. is searched.'  This is correct as it is IMHO.
> I'm not a native speaker, and I might be wrong here, but this would
> probably look OK, if written as the following:
> 
> 	Whenever a device is attached or detached,
> 	the list of actions (which is read from
> 	.Pa /etc/usbd.conf )
> 	is searched for a matching entry.
> 
> or something similar.  What do you think?

I agree, I think your suggestion improves that aspect.

Rereading those pages now, I noticed a few more problems that I'd
missed.  And as has been pointed out, my suggestions aren't perfect
either.  I hesitate to suggest wholesale changes for lack of
experience in this, and not wanting to tread on toes.

It seems clear that the English usage in usbd(8) and usbd.conf(5) is
not as good as it could be, and could benefit from some of the
simpler corrections I've suggested and possibly a more thorough
edit by someone more qualified than myself.



-- 
David Siebörger
drs@rucus.ru.ac.za

Comment 3 Tom Rhodes 2003-01-30 22:39:55 UTC

State Changed
From-To: open->patched

Assign this to me.  Slightly different version of the patch applied, mainly 
I've taken the comments offered by keramida.  MFC forthcoming. 

Comment 4 Tom Rhodes 2003-01-30 22:39:55 UTC

Responsible Changed
From-To: freebsd-doc->trhodes

Assign this to me.  Slightly different version of the patch applied, mainly 
I've taken the comments offered by keramida.  MFC forthcoming.

Comment 5 Tom Rhodes 2003-02-02 00:39:44 UTC

State Changed
From-To: patched->closed

Applied to stable!  Thanks for the submission.