From root@starfury.scode.org  Sun Jun 11 11:13:01 2006
Return-Path: <root@starfury.scode.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id D69EE16A41F
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 11 Jun 2006 11:13:01 +0000 (UTC)
	(envelope-from root@starfury.scode.org)
Received: from starfury.scode.org (starfury.scode.org [194.145.249.108])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 7E7B843D45
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 11 Jun 2006 11:13:01 +0000 (GMT)
	(envelope-from root@starfury.scode.org)
Received: by starfury.scode.org (Postfix, from userid 0)
	id 4B1E79A885E; Sun, 11 Jun 2006 13:12:59 +0200 (CEST)
Message-Id: <20060611111259.4B1E79A885E@starfury.scode.org>
Date: Sun, 11 Jun 2006 13:12:59 +0200 (CEST)
From: Peter Schuller <peter.schuller@infidyne.com>
Reply-To: Peter Schuller <peter.schuller@infidyne.com>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: gmirror(8) and glabel(8) manpages should mention geom_{mirror,label}_load
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         98801
>Category:       docs
>Synopsis:       [patch] gmirror(8) and glabel(8) manpages should mention geom_{mirror,label}_load
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Sun Jun 11 11:20:17 GMT 2006
>Closed-Date:    Thu Oct 12 11:21:28 GMT 2006
>Last-Modified:  Thu Oct 12 11:21:28 GMT 2006
>Originator:     Peter Schuller <peter.schuller@infidyne.com>
>Release:        FreeBSD 6.0-RELEASE-p4 i386
>Organization:
>Environment:
System: FreeBSD starfury.scode.org 6.0-RELEASE-p4 FreeBSD 6.0-RELEASE-p4 #1: Thu Feb 23 16:56:26 CET 2006 scode@starfury.scode.org:/usr/obj/usr/src/sys/STARFURY i386


>Description:
	The geom_mirror_load and geom_label_load sysctl variables should be
	mentioned in their classes' respective manpages. I suspect the same
	is true for the other classes, but I have not personally tried it
	so I am not including it in the patch.
>How-To-Repeat:
>Fix:

--- sbin/geom/class/mirror/gmirror.8.orig	Sun Jun 11 12:44:23 2006
+++ sbin/geom/class/mirror/gmirror.8	Sun Jun 11 13:05:08 2006
@@ -229,6 +229,19 @@
 .It Fl v
 Be more verbose.
 .El
+.Sh SYSCTL VARIABLES
+The following
+.Xr sysctl 8
+variables can be used to control the behavior of
+the
+.Nm MIRROR
+GEOM class. The default value is shown next to each variable.
+.Bl -tag -width indent
+.It Va geom_mirror_load : No 0
+When set to 1, instructs the kernel to automatically load the
+.Nm MIRROR
+GEOM class on boot.
+.El
 .Sh EXIT STATUS
 Exit status is 0 on success, and 1 if the command fails.
 .Sh EXAMPLES
--- sbin/geom/class/label/glabel.8.orig	Sun Jun 11 13:05:42 2006
+++ sbin/geom/class/label/glabel.8	Sun Jun 11 13:06:29 2006
@@ -184,6 +184,10 @@
 This can be set to a number between 0 and 2 inclusive.
 If set to 0 minimal debug information is printed, and if set to 2 the
 maximum amount of debug information is printed.
+.It Va geom_label_load : No 0
+When set to 1, instructs the kernel to automatically load the
+.Nm LABEL
+GEOM class on boot.
 .El
 .Sh EXIT STATUS
 Exit status is 0 on success, and 1 if the command fails.



>Release-Note:
>Audit-Trail:

From: Christian Brueffer <brueffer@FreeBSD.org>
To: Peter Schuller <peter.schuller@infidyne.com>
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/98801: gmirror(8) and glabel(8) manpages should mention
 geom_{mirror, label}_load
Date: Sun, 11 Jun 2006 13:49:50 +0200

 --WIyZ46R2i8wDzkSu
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 Content-Transfer-Encoding: quoted-printable
 
 On Sun, Jun 11, 2006 at 01:12:59PM +0200, Peter Schuller wrote:
 >=20
 > >Number:         98801
 > >Category:       docs
 > >Synopsis:       gmirror(8) and glabel(8) manpages should mention geom_{m=
 irror,label}_load
 > >Confidential:   no
 > >Severity:       non-critical
 > >Priority:       medium
 > >Responsible:    freebsd-doc
 > >State:          open
 > >Quarter:       =20
 > >Keywords:      =20
 > >Date-Required:
 > >Class:          change-request
 > >Submitter-Id:   current-users
 > >Arrival-Date:   Sun Jun 11 11:20:17 GMT 2006
 > >Closed-Date:
 > >Last-Modified:
 > >Originator:     Peter Schuller <peter.schuller@infidyne.com>
 > >Release:        FreeBSD 6.0-RELEASE-p4 i386
 > >Organization:
 > >Environment:
 > System: FreeBSD starfury.scode.org 6.0-RELEASE-p4 FreeBSD 6.0-RELEASE-p4 =
 #1: Thu Feb 23 16:56:26 CET 2006 scode@starfury.scode.org:/usr/obj/usr/src/=
 sys/STARFURY i386
 >=20
 >=20
 > >Description:
 > 	The geom_mirror_load and geom_label_load sysctl variables should be
 > 	mentioned in their classes' respective manpages. I suspect the same
 > 	is true for the other classes, but I have not personally tried it
 > 	so I am not including it in the patch.
 > >How-To-Repeat:
 > >Fix:
 >=20
 > --- sbin/geom/class/mirror/gmirror.8.orig	Sun Jun 11 12:44:23 2006
 > +++ sbin/geom/class/mirror/gmirror.8	Sun Jun 11 13:05:08 2006
 > @@ -229,6 +229,19 @@
 >  .It Fl v
 >  Be more verbose.
 >  .El
 > +.Sh SYSCTL VARIABLES
 > +The following
 > +.Xr sysctl 8
 > +variables can be used to control the behavior of
 > +the
 > +.Nm MIRROR
 > +GEOM class. The default value is shown next to each variable.
 > +.Bl -tag -width indent
 > +.It Va geom_mirror_load : No 0
 > +When set to 1, instructs the kernel to automatically load the
 > +.Nm MIRROR
 > +GEOM class on boot.
 > +.El
 >  .Sh EXIT STATUS
 >  Exit status is 0 on success, and 1 if the command fails.
 >  .Sh EXAMPLES
 > --- sbin/geom/class/label/glabel.8.orig	Sun Jun 11 13:05:42 2006
 > +++ sbin/geom/class/label/glabel.8	Sun Jun 11 13:06:29 2006
 > @@ -184,6 +184,10 @@
 >  This can be set to a number between 0 and 2 inclusive.
 >  If set to 0 minimal debug information is printed, and if set to 2 the
 >  maximum amount of debug information is printed.
 > +.It Va geom_label_load : No 0
 > +When set to 1, instructs the kernel to automatically load the
 > +.Nm LABEL
 > +GEOM class on boot.
 >  .El
 >  .Sh EXIT STATUS
 >  Exit status is 0 on success, and 1 if the command fails.
 >=20
 >=20
 
 These are not sysctl variables, but loader instructions.  Also IMHO they
 don't really belong in section 8 manpages.  Instead short section 4
 manpages for each geom module should be written (some of the information
 in the section 8 manpages should probably be moved there then).
 
 - Christian
 
 --=20
 Christian Brueffer	chris@unixpages.org	brueffer@FreeBSD.org
 GPG Key:	 http://people.freebsd.org/~brueffer/brueffer.key.asc
 GPG Fingerprint: A5C8 2099 19FF AACA F41B  B29B 6C76 178C A0ED 982D
 
 --WIyZ46R2i8wDzkSu
 Content-Type: application/pgp-signature
 Content-Disposition: inline
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.2.2 (FreeBSD)
 
 iD8DBQFEjANebHYXjKDtmC0RAmu4AJ90JlVLvNoFleMuz1NDrJEdZAJwCwCfTyms
 LOq1cwwH5loXKHHCciIZC0U=
 =oRDF
 -----END PGP SIGNATURE-----
 
 --WIyZ46R2i8wDzkSu--
 

From: Peter Schuller <peter.schuller@infidyne.com>
To: Christian Brueffer <brueffer@freebsd.org>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/98801: gmirror(8) and glabel(8) manpages should mention geom_{mirror, label}_load
Date: Sun, 11 Jun 2006 15:11:14 +0200

 > These are not sysctl variables, but loader instructions. 
 
 I was not sure about the nomenclature. I ended up doing what I did based on 
 gstripe(8), which lists loader variables under sysctl variables, but with a 
 note saying they cannot be changed after boot (though I realize I forgot to 
 do the latter).
 
 > Also IMHO they 
 > don't really belong in section 8 manpages.  Instead short section 4
 > manpages for each geom module should be written (some of the information
 > in the section 8 manpages should probably be moved there then).
 
 On the other hand it is very relevant to anyone reading gmirror(8) or 
 glabel(8).  At the very least it seems adding it to (8) is better than 
 leaving it as-is, not documented at all.
 
 I can propose new section 4 manpages, but I am not sure how much from their 
 corresponding section 8 manpages really belong there. Would you feel a 
 separate manpage is warranted even if it essentially only contains the 
 relevant loader instructions?
 
 While there is some information in gmirror(8)/gmirror(9) that refer to the 
 workings of the geom class itself, rather than the tool, I don't know how 
 much sense it makes to try to strip those pages of that information given 
 that it is so directly relevant to operation of the tool. Perhaps the 
 introductory general information on meta-data layout and general operations.
 
 I presume the section for manpages would preferably be named geom_XXX (in 
 keeping with geom(4)).
 
 -- 
 / Peter Schuller, InfiDyne Technologies HB
 
 PGP userID: 0xE9758B7D or 'Peter Schuller <peter.schuller@infidyne.com>'
 Key retrieval: Send an E-Mail to getpgpkey@scode.org
 E-Mail: peter.schuller@infidyne.com Web: http://www.scode.org
 

From: Christian Brueffer <chris@unixpages.org>
To: Peter Schuller <peter.schuller@infidyne.com>,
 FreeBSD-gnats-submit@freebsd.org
Cc:  
Subject: Re: docs/98801: gmirror(8) and glabel(8) manpages should mention
 geom_{mirror, label}_load
Date: Wed, 14 Jun 2006 16:43:12 +0200

 --TakKZr9L6Hm6aLOc
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 Content-Transfer-Encoding: quoted-printable
 
 On Sun, Jun 11, 2006 at 03:11:14PM +0200, Peter Schuller wrote:
 > > These are not sysctl variables, but loader instructions.=20
 >=20
 > I was not sure about the nomenclature. I ended up doing what I did based =
 on=20
 > gstripe(8), which lists loader variables under sysctl variables, but with=
  a=20
 > note saying they cannot be changed after boot (though I realize I forgot =
 to=20
 > do the latter).
 >=20
 > > Also IMHO they=20
 > > don't really belong in section 8 manpages.  Instead short section 4
 > > manpages for each geom module should be written (some of the information
 > > in the section 8 manpages should probably be moved there then).
 >=20
 > On the other hand it is very relevant to anyone reading gmirror(8) or=20
 > glabel(8).  At the very least it seems adding it to (8) is better than=20
 > leaving it as-is, not documented at all.
 >=20
 > I can propose new section 4 manpages, but I am not sure how much from the=
 ir=20
 > corresponding section 8 manpages really belong there. Would you feel a=20
 > separate manpage is warranted even if it essentially only contains the=20
 > relevant loader instructions?
 >=20
 > While there is some information in gmirror(8)/gmirror(9) that refer to th=
 e=20
 > workings of the geom class itself, rather than the tool, I don't know how=
 =20
 > much sense it makes to try to strip those pages of that information given=
 =20
 > that it is so directly relevant to operation of the tool. Perhaps the=20
 > introductory general information on meta-data layout and general operatio=
 ns.
 >=20
 
 IMHO all information about the implementation of the class should go
 into section 4 manpage as well.
 
 "Would it make sense to just put the module information in there if nothing
 else is available?"
 
 IMHO yes, together with one or two lines about what the module does.
 One of our aims is actually to have a manpage for every kernel
 driver/option/whatever (or an MLINK to a relevant manpage).
 
 > I presume the section for manpages would preferably be named geom_XXX (in=
 =20
 > keeping with geom(4)).
 >=20
 
 Yes, probably with an MLINK to e.g. gmirror(4).
 
 - Christian
 
 --=20
 Christian Brueffer	chris@unixpages.org	brueffer@FreeBSD.org
 GPG Key:	 http://people.freebsd.org/~brueffer/brueffer.key.asc
 GPG Fingerprint: A5C8 2099 19FF AACA F41B  B29B 6C76 178C A0ED 982D
 
 --TakKZr9L6Hm6aLOc
 Content-Type: application/pgp-signature
 Content-Disposition: inline
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.2.2 (FreeBSD)
 
 iD8DBQFEkCCAbHYXjKDtmC0RAiTeAKCYq1kJXUn7BJB896xzk0uCqQOdvgCgl3jI
 s5hba23A4GZ74EFyinbubWY=
 =cSA6
 -----END PGP SIGNATURE-----
 
 --TakKZr9L6Hm6aLOc--
 
State-Changed-From-To: open->closed 
State-Changed-By: ru 
State-Changed-When: Thu Oct 12 11:16:11 UTC 2006 
State-Changed-Why:  
As Christian said, *_load loader variables don't belong in section 
8; they are documented in the loader.conf(5) manpage (the general 
synopsis), with defaults available in /boot/defaults/loader.conf 
that in -CURRENT even lists GEOM modules.  The gstripe(8) manpage 
that you're referring to documents sysctls; some of them may also 
be loader tunables which is a common practice. 

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