From rsmith@xs4all.nl  Tue Dec 13 21:40:15 2005
Return-Path: <rsmith@xs4all.nl>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 276D816A420
	for <FreeBSD-gnats-submit@freebsd.org>; Tue, 13 Dec 2005 21:40:15 +0000 (GMT)
	(envelope-from rsmith@xs4all.nl)
Received: from smtp-vbr7.xs4all.nl (smtp-vbr7.xs4all.nl [194.109.24.27])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 1B8F743D88
	for <FreeBSD-gnats-submit@freebsd.org>; Tue, 13 Dec 2005 21:40:12 +0000 (GMT)
	(envelope-from rsmith@xs4all.nl)
Received: from slackbox.xs4all.nl (slackbox.xs4all.nl [213.84.242.160])
	by smtp-vbr7.xs4all.nl (8.13.3/8.13.3) with ESMTP id jBDLeBSA018553
	for <FreeBSD-gnats-submit@freebsd.org>; Tue, 13 Dec 2005 22:40:11 +0100 (CET)
	(envelope-from rsmith@xs4all.nl)
Received: by slackbox.xs4all.nl (Postfix, from userid 1001)
	id 2BBACB827; Tue, 13 Dec 2005 22:40:11 +0100 (CET)
Message-Id: <20051213214011.2BBACB827@slackbox.xs4all.nl>
Date: Tue, 13 Dec 2005 22:40:11 +0100 (CET)
From: Roland Smith <rsmith@xs4all.nl>
Reply-To: Roland Smith <rsmith@xs4all.nl>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [patch] enhancement of devfs.rules manpage.
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         90362
>Category:       docs
>Synopsis:       [patch] enhancement of devfs.rules(5) manpage.
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    keramida
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Tue Dec 13 21:50:02 GMT 2005
>Closed-Date:    Thu Apr 27 15:46:56 GMT 2006
>Last-Modified:  Thu Apr 27 15:46:56 GMT 2006
>Originator:     Roland Smith
>Release:        FreeBSD 6.0-STABLE amd64
>Organization:
>Environment:
System: FreeBSD slackbox.xs4all.nl 6.0-STABLE FreeBSD 6.0-STABLE #0: Sun Nov 20 02:27:45 CET 2005 root@slackbox.xs4all.nl:/usr/obj/usr/src/sys/RFS amd64


	
>Description:
	As a result of recent postings on -questions, it became clear that
	the manpage for devfs.rules could be improved, especially
	mentioning that a ruleset needs to be activated in
	/etc/rc.conf. This patch tries to provide such improvement.

>How-To-Repeat:
	
>Fix:

See enclosed patch. Feel free to improve the tags used, I'm still learning
mdoc. :-)
----------------------- patch ----------------------------
--- devfs.rules.5	2005/12/13 19:59:29	1.6
+++ devfs.rules.5	2005/12/13 21:19:53
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD: /repoman/r/ncvs/src/share/man/man5/devfs.rules.5,v 1.2.4.1 2005/07/27 12:03:48 keramida Exp $
 .\"
-.Dd May 17, 2005
+.Dd Dec 13, 2005
 .Dt DEVFS.RULES 5
 .Os
 .Sh NAME
@@ -72,8 +72,23 @@
 .Dq Li usb
 group, the following rule may be used:
 .Pp
+.Dl "[localrules=10]"
 .Dl "add path 'da*s*' mode 0660 group usb"
 .Pp
+The first line declares and starts a new ruleset, with the name
+.Va localrules
+and the number 10. Rulesets should have a unique name and number.  All
+rules that follow a ruleset declaration belong to that ruleset, untill a
+new ruleset is started. This ruleset has to be enabled in
+.Pa /etc/rc.conf 
+to be the ruleset for the 
+.Pa /dev 
+filesystem. This is done by putting the following line in 
+.Pa /etc/rc.conf :
+.Bd -literal
+devfs_system_ruleset="localrules"
+.Ed
+.Pp
 To make all the
 .Xr uscanner 4
 devices accessible to their owner and the
@@ -81,6 +96,7 @@
 group, a similar rule may be used:
 .Pp
 .Dl "add path 'uscanner*' mode 0660 group usb"
+.Pp
 .Sh SEE ALSO
 .Xr glob 3 ,
 .Xr devfs 5 ,
----------------------- patch ----------------------------


>Release-Note:
>Audit-Trail:

From: Giorgos Keramidas <keramida@freebsd.org>
To: Roland Smith <rsmith@xs4all.nl>
Cc: bug-followup@freebsd.org
Subject: Re: docs/90362: [patch] enhancement of devfs.rules manpage.
Date: Mon, 23 Jan 2006 03:30:02 +0200

 > --- devfs.rules.5	2005/12/13 19:59:29	1.6
 > +++ devfs.rules.5	2005/12/13 21:19:53
 
 >  .Pp
 > +.Dl "[localrules=10]"
 >  .Dl "add path 'da*s*' mode 0660 group usb"
 >  .Pp
 > +The first line declares and starts a new ruleset, with the name
 > +.Va localrules
 > +and the number 10. Rulesets should have a unique name and number.  All
 
 "Rulesets should have a unique name and number" is duplicated here,
 since it's also mentioned higher up, in the DESCRIPTION section.
 
 > +rules that follow a ruleset declaration belong to that ruleset, untill a
 
 "untill" is a minor typo.
 
 Overall this is a great idea though, but I'd probably move the general
 ruleset description items in the DESCRIPTION section.  If the following
 looks ok to you too Roland, it would be nice to have it committed I
 guess:
 
 %%%
 Index: devfs.rules.5
 ===================================================================
 RCS file: /home/ncvs/src/share/man/man5/devfs.rules.5,v
 retrieving revision 1.2
 diff -u -r1.2 devfs.rules.5
 --- devfs.rules.5	16 Jun 2005 18:46:17 -0000	1.2
 +++ devfs.rules.5	23 Jan 2006 01:29:23 -0000
 @@ -24,7 +24,7 @@
  .\"
  .\" $FreeBSD: src/share/man/man5/devfs.rules.5,v 1.2 2005/06/16 18:46:17 ru Exp $
  .\"
 -.Dd May 17, 2005
 +.Dd Jan 23, 2006
  .Dt DEVFS.RULES 5
  .Os
  .Sh NAME
 @@ -60,6 +60,27 @@
  It is important to put path elements that contain
  .Xr glob 3
  special characters between quotes.
 +.Pp
 +Rulesets should have a unique name and number.
 +.Pp
 +All rules that follow a ruleset declaration belong to that ruleset, until a
 +new ruleset is started.
 +.Pp
 +All custom rulesets have to be enabled in
 +.Pa /etc/rc.conf ,
 +otherwise they won't be applied to the
 +.Pa /dev
 +file system by the default system startup process.
 +For example, to enable a
 +.Dq Li localrules
 +ruleset for the
 +.Pa /dev
 +file system, you would have to use something like this in your
 +.Pa rc.conf
 +file:
 +.Bd -literal -offset indent
 +devfs_system_ruleset="localrules"
 +.Ed
  .Sh FILES
  .Bl -tag -compact
  .It Pa /etc/devfs.rules
 @@ -72,14 +93,20 @@
  .Dq Li usb
  group, the following rule may be used:
  .Pp
 +.Dl "[localrules=10]"
  .Dl "add path 'da*s*' mode 0660 group usb"
  .Pp
 +The first line declares and starts a new ruleset, with the name
 +.Va localrules
 +and the number 10.
 +.Pp
  To make all the
  .Xr uscanner 4
  devices accessible to their owner and the
  .Dq Li usb
  group, a similar rule may be used:
  .Pp
 +.Dl "[uscanner=20]"
  .Dl "add path 'uscanner*' mode 0660 group usb"
  .Sh SEE ALSO
  .Xr glob 3 ,
 %%%

From: Roland Smith <rsmith@xs4all.nl>
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: docs/90362: [patch] enhancement of devfs.rules manpage.
Date: Mon, 23 Jan 2006 19:39:01 +0100

 --6c2NcOVqGQ03X4Wi
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 Content-Transfer-Encoding: quoted-printable
 
 On Mon, Jan 23, 2006 at 03:30:02AM +0200, Giorgos Keramidas wrote:
 > > --- devfs.rules.5	2005/12/13 19:59:29	1.6
 > > +++ devfs.rules.5	2005/12/13 21:19:53
 >=20
 > >  .Pp
 > > +.Dl "[localrules=3D10]"
 > >  .Dl "add path 'da*s*' mode 0660 group usb"
 > >  .Pp
 > > +The first line declares and starts a new ruleset, with the name
 > > +.Va localrules
 > > +and the number 10. Rulesets should have a unique name and number.  All
 >=20
 > "Rulesets should have a unique name and number" is duplicated here,
 > since it's also mentioned higher up, in the DESCRIPTION section.
 
 Ok.
 
 > > +rules that follow a ruleset declaration belong to that ruleset, untill=
  a
 >=20
 > "untill" is a minor typo.
 
 Oops.
 
 > Overall this is a great idea though, but I'd probably move the general
 > ruleset description items in the DESCRIPTION section.  If the following
 > looks ok to you too Roland, it would be nice to have it committed I
 > guess:
 
 It's mostly OK, except for some small remarks below:
 =20
 > %%%
 > Index: devfs.rules.5
 > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
 > RCS file: /home/ncvs/src/share/man/man5/devfs.rules.5,v
 > retrieving revision 1.2
 > diff -u -r1.2 devfs.rules.5
 > --- devfs.rules.5	16 Jun 2005 18:46:17 -0000	1.2
 > +++ devfs.rules.5	23 Jan 2006 01:29:23 -0000
 > @@ -24,7 +24,7 @@
 >  .\"
 >  .\" $FreeBSD: src/share/man/man5/devfs.rules.5,v 1.2 2005/06/16 18:46:17=
  ru Exp $
 >  .\"
 > -.Dd May 17, 2005
 > +.Dd Jan 23, 2006
 >  .Dt DEVFS.RULES 5
 >  .Os
 >  .Sh NAME
 > @@ -60,6 +60,27 @@
 >  It is important to put path elements that contain
 >  .Xr glob 3
 >  special characters between quotes.
 > +.Pp
 > +Rulesets should have a unique name and number.
 > +.Pp
 > +All rules that follow a ruleset declaration belong to that ruleset, unti=
 l a
 > +new ruleset is started.
 > +.Pp
 
 This should be singular, not plural, since only one ruleset can be
 enabled for /dev, so:
 
 -All custom rulesets have to be enabled in
 +One custom ruleset has to be enabled in
 
 > +.Pa /etc/rc.conf ,
 
 -otherwise they won't be applied to the
 +otherwise it won't be applied to the
 
 > +.Pa /dev
 > +file system by the default system startup process.
 > +For example, to enable a
 > +.Dq Li localrules
 > +ruleset for the
 > +.Pa /dev
 > +file system, you would have to use something like this in your
 > +.Pa rc.conf
 > +file:
 > +.Bd -literal -offset indent
 > +devfs_system_ruleset=3D"localrules"
 > +.Ed
 >  .Sh FILES
 >  .Bl -tag -compact
 >  .It Pa /etc/devfs.rules
 > @@ -72,14 +93,20 @@
 >  .Dq Li usb
 >  group, the following rule may be used:
 >  .Pp
 > +.Dl "[localrules=3D10]"
 >  .Dl "add path 'da*s*' mode 0660 group usb"
 >  .Pp
 > +The first line declares and starts a new ruleset, with the name
 > +.Va localrules
 > +and the number 10.
 > +.Pp
 >  To make all the
 >  .Xr uscanner 4
 >  devices accessible to their owner and the
 >  .Dq Li usb
 >  group, a similar rule may be used:
 >  .Pp
 > +.Dl "[uscanner=3D20]"
 
 You should not start an extra ruleset here. The following rule is for
 the /dev filesystem, and should therefore belong to the "localrules"
 set. AFAIK, you can activate only _one_ ruleset for /dev in /etc/rc.conf
 via devfs_system_ruleset (see /etc/rc.d/devfs).=20
 
 The variable devfs_set_rulesets is meant for other mountpoints.
 
 >  .Dl "add path 'uscanner*' mode 0660 group usb"
 >  .Sh SEE ALSO
 >  .Xr glob 3 ,
 > %%%
 
 The rest of the patch looks OK.
 
 Roland
 --=20
 R.F.Smith (http://www.xs4all.nl/~rsmith/) Please send e-mail as plain text.
 public key: http://www.xs4all.nl/~rsmith/pubkey.txt
 
 --6c2NcOVqGQ03X4Wi
 Content-Type: application/pgp-signature
 Content-Disposition: inline
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.2 (FreeBSD)
 
 iD8DBQFD1SLFEnfvsMMhpyURAkTlAJ4oPOreen+QpI8nS9jAJzlw5fqhYQCfYk0f
 jXpALGNWROBp1I0h497TeWw=
 =wILh
 -----END PGP SIGNATURE-----
 
 --6c2NcOVqGQ03X4Wi--
State-Changed-From-To: open->patched 
State-Changed-By: keramida 
State-Changed-When: Mon Jan 30 13:28:49 UTC 2006 
State-Changed-Why:  
I've committed the changes, including the latest clarifications of 
Roland to CURRENT. 


Responsible-Changed-From-To: freebsd-doc->keramida 
Responsible-Changed-By: keramida 
Responsible-Changed-When: Mon Jan 30 13:28:49 UTC 2006 
Responsible-Changed-Why:  
I'll take care of MFC'ing this. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=90362 
State-Changed-From-To: patched->closed 
State-Changed-By: keramida 
State-Changed-When: Thu Apr 27 15:46:11 UTC 2006 
State-Changed-Why:  
Merged to RELENG_6 after approval from re@ (hrs) 

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