From drs@foundation.org.za  Fri Feb  1 06:15:06 2002
Return-Path: <drs@foundation.org.za>
Received: from turnip.foundation.org.za (turnip.foundation.org.za [196.7.160.2])
	by hub.freebsd.org (Postfix) with SMTP id 60C2137B400
	for <FreeBSD-gnats-submit@freebsd.org>; Fri,  1 Feb 2002 06:15:01 -0800 (PST)
Received: (qmail 50694 invoked by uid 1001); 1 Feb 2002 14:15:29 -0000
Message-Id: <20020201141529.50693.qmail@foundation.org.za>
Date: 1 Feb 2002 14:15:29 -0000
From: David "Siebrger" <drs@rucus.ru.ac.za>
Reply-To: David "Siebrger" <drs@rucus.ru.ac.za>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [patch] Grammar nits in usbd.conf(5) and usbd(8)
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         34529
>Category:       docs
>Synopsis:       [patch] Grammar nits in usbd.conf(5) and usbd(8)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Feb 01 06:20:01 PST 2002
>Closed-Date:    Sat Feb 01 16:40:09 PST 2003
>Last-Modified:  Sat Feb 01 16:40:09 PST 2003
>Originator:     David Siebrger
>Release:        FreeBSD 4.5-RELEASE i386
>Organization:
Rhodes University Computer Users Society
>Environment:
System: FreeBSD bashir.dsl.ru.ac.za 4.5-RELEASE FreeBSD 4.5-RELEASE #1: Tue Jan 29 19:22:38 SAST 2002 drs@bashir.dsl.ru.ac.za:/usr/obj/usr/src/sys/BASHIR i386

>Description:
Fixes for a few grammar mistakes in usbd manual pages.

>How-To-Repeat:
man 5 usbd.conf
man 8 usbd

>Fix:

--- usr.sbin/usbd/usbd.conf.5.orig	Thu Aug 16 17:56:41 2001
+++ usr.sbin/usbd/usbd.conf.5	Fri 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.
 Each field can have one or more arguments.
 .Pp
 The following fields are available:
@@ -74,11 +74,11 @@
 .Ar string
 is an arbitrary string used for pretty printing.
 .It product Ar id
-Product Id
+Product ID
 .It vendor Ar id
-Vendor Id
+Vendor ID
 .It release Ar id
-Release Id, also called revision Id sometimes.
+Release ID, also called revision ID sometimes.
 .It class Ar id
 Device Class
 .It subclass Ar id
@@ -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. 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. 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 .
--- usr.sbin/usbd/usbd.8.orig	Thu Aug 16 17:56:41 2001
+++ usr.sbin/usbd/usbd.8	Fri 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.
 This functionality will be removed when the kernel has
 kernel threads.
@@ -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.
 .Pp
>Release-Note:
>Audit-Trail:

From: Giorgos Keramidas <keramida@ceid.upatras.gr>
To: =?ISO-8859-7?Q?David_Sieb=F6rger?= <drs@rucus.ru.ac.za>
Cc: bug-followup@freebsd.org
Subject: Re: docs/34529: [patch] Grammar nits in usbd.conf(5) and usbd(8)
Date: Fri, 1 Feb 2002 21:16:53 +0200 (EET)

 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/
 

From: =?iso-8859-1?Q?David_Sieb=F6rger?= <drs@rucus.ru.ac.za>
To: freebsd-doc@freebsd.org
Cc: bug-followup@freebsd.org
Subject: Re: docs/34529: [patch] Grammar nits in usbd.conf(5) and usbd(8)
Date: Tue, 5 Feb 2002 00:12:40 +0200

 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 Siebrger
 drs@rucus.ru.ac.za
State-Changed-From-To: open->patched 
State-Changed-By: trhodes 
State-Changed-When: Thu Jan 30 14:39:55 PST 2003 
State-Changed-Why:  
Assign this to me.  Slightly different version of the patch applied, mainly 
I've taken the comments offered by keramida.  MFC forthcoming. 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Thu Jan 30 14:39:55 PST 2003 
Responsible-Changed-Why:  
Assign this to me.  Slightly different version of the patch applied, mainly 
I've taken the comments offered by keramida.  MFC forthcoming. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=34529 
State-Changed-From-To: patched->closed 
State-Changed-By: trhodes 
State-Changed-When: Sat Feb 1 16:39:44 PST 2003 
State-Changed-Why:  
Applied to stable!  Thanks for the submission. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=34529 
>Unformatted:
