Bug 90362

Summary: [patch] enhancement of devfs.rules(5) manpage.
Product: Documentation Reporter: rsmith
Component: Books & ArticlesAssignee: Giorgos Keramidas <keramida>
Status: Closed FIXED    
Severity: Affects Only Me    
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   

Description rsmith 2005-12-13 21:50:02 UTC 
	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.

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 ----------------------------
Comment 1 Giorgos Keramidas freebsd_committer freebsd_triage 2006-01-23 01:30:02 UTC 
> --- 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 ,
%%%
Comment 2 rsmith 2006-01-23 18:39:01 UTC 
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
> 
> >  .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.


Ok.

> > +rules that follow a ruleset declaration belong to that ruleset, untill a
> 
> "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:
 
> %%%
> 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


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="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]"


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

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
-- 
R.F.Smith (http://www.xs4all.nl/~rsmith/) Please send e-mail as plain text.
public key: http://www.xs4all.nl/~rsmith/pubkey.txt
Comment 3 Giorgos Keramidas freebsd_committer freebsd_triage 2006-01-30 13:28:49 UTC 
State Changed
From-To: open->patched

I've committed the changes, including the latest clarifications of 
Roland to CURRENT.
Comment 4 Giorgos Keramidas freebsd_committer freebsd_triage 2006-01-30 13:28:49 UTC 
Responsible Changed
From-To: freebsd-doc->keramida

I'll take care of MFC'ing this.
Comment 5 Giorgos Keramidas freebsd_committer freebsd_triage 2006-04-27 16:46:11 UTC 
State Changed
From-To: patched->closed

Merged to RELENG_6 after approval from re@ (hrs)