From rfg@tristatelogic.com  Sat Dec  8 00:40:54 2012
Return-Path: <rfg@tristatelogic.com>
Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52])
	by hub.freebsd.org (Postfix) with ESMTP id 78F9BE2
	for <FreeBSD-gnats-submit@freebsd.org>; Sat,  8 Dec 2012 00:40:54 +0000 (UTC)
	(envelope-from rfg@tristatelogic.com)
Received: from outgoing.tristatelogic.com (segfault.tristatelogic.com [69.62.255.118])
	by mx1.freebsd.org (Postfix) with ESMTP id 51F298FC13
	for <FreeBSD-gnats-submit@freebsd.org>; Sat,  8 Dec 2012 00:40:54 +0000 (UTC)
Received: by segfault.tristatelogic.com (Postfix, from userid 1237)
	id 999BA5081B; Fri,  7 Dec 2012 16:40:53 -0800 (PST)
Message-Id: <20121208004053.999BA5081B@segfault.tristatelogic.com>
Date: Fri,  7 Dec 2012 16:40:53 -0800 (PST)
From: Ronald F.Guilmette <rfg@tristatelogic.com>
Reply-To: Ronald F.Guilmette <rfg@tristatelogic.com>
To: FreeBSD-gnats-submit@freebsd.org
Cc: rfg@tristatelogic.com
Subject: gpart(8) man page doesn't describe output of "show" command
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         174270
>Category:       docs
>Synopsis:       gpart(8) man page doesn't describe output of "show" command
>Confidential:   no
>Severity:       serious
>Priority:       low
>Responsible:    wblock
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sat Dec 08 00:50:00 UTC 2012
>Closed-Date:    Sat Jan 12 17:01:47 UTC 2013
>Last-Modified:  Sat Jan 12 17:01:47 UTC 2013
>Originator:     Ronald F. Guilmette
>Release:        FreeBSD 8.3-RELEASE amd64
>Organization:
entr0py
>Environment:

FreeBSD 8.3-RELEASE amd64

>Description:

The man page for gpart(8) contains a small section describing options
applicable to the "show" command.  Unfortuantely, the man page utterly
fails to document or describe the meaning and/or proper interpretation
of any of the four columns of output that are generated by the "gpart show"
command.  This is a serious ommission.

>How-To-Repeat:

man gpart

>Fix:

Somebody needs to document what each of the four columns of "gpart show"
output are actually telling the user.
>Release-Note:
>Audit-Trail:

From: Bas Smeelen <b.smeelen@ose.nl>
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/174270: gpart(8) man page doesn't describe output of "show"
 command
Date: Mon, 10 Dec 2012 09:36:19 +0100

 This is a multi-part message in MIME format.
 --------------000701070309040301000003
 Content-Type: text/plain; charset=ISO-8859-1; format=flowed
 Content-Transfer-Encoding: 7bit
 
 On 12/08/2012 01:40 AM, Ronald F.Guilmette wrote:
 >> Number:         174270
 >> Category:       docs
 >> Synopsis:       gpart(8) man page doesn't describe output of "show" command
 
 On a 9.1 machine (FreeBSD cfd 9.1-RELEASE FreeBSD 9.1-RELEASE #1 r243880: 
 Wed Dec  5 08:15:54 CET 2012 root@cfd:/usr/obj/usr/src/sys/GENERIC  i386) I 
 have changed the man page and come up with a patch attached. I have also 
 changed references to ad0 (as stated in another mail to the lists)
 I just can't figure out how to build and install the manpage or the whole 
 gpart. This is different than most other applications, can someone provide 
 some guidelines?
 
 Would something like this do?
 
 
 >> Confidential:   no
 >> Severity:       serious
 >> Priority:       low
 >> Responsible:    freebsd-doc
 >> State:          open
 >> Quarter:
 >> Keywords:
 >> Date-Required:
 >> Class:          doc-bug
 >> Submitter-Id:   current-users
 >> Arrival-Date:   Sat Dec 08 00:50:00 UTC 2012
 >> Closed-Date:
 >> Last-Modified:
 >> Originator:     Ronald F. Guilmette
 >> Release:        FreeBSD 8.3-RELEASE amd64
 >> Organization:
 > entr0py
 >> Environment:
 > FreeBSD 8.3-RELEASE amd64
 >
 >> Description:
 > The man page for gpart(8) contains a small section describing options
 > applicable to the "show" command.  Unfortuantely, the man page utterly
 > fails to document or describe the meaning and/or proper interpretation
 > of any of the four columns of output that are generated by the "gpart show"
 > command.  This is a serious ommission.
 >
 >> How-To-Repeat:
 > man gpart
 >
 >> Fix:
 > Somebody needs to document what each of the four columns of "gpart show"
 > output are actually telling the user.
 >> Release-Note:
 >> Audit-Trail:
 >> Unformatted:
 
 
 
 --------------000701070309040301000003
 Content-Type: text/x-patch;
  name="gpartmanpatch.diff"
 Content-Transfer-Encoding: 7bit
 Content-Disposition: attachment;
  filename="gpartmanpatch.diff"
 
 Index: sbin/geom/class/part/gpart.8
 ===================================================================
 --- sbin/geom/class/part/gpart.8	(revision 244078)
 +++ sbin/geom/class/part/gpart.8	(working copy)
 @@ -455,6 +455,13 @@
  .It Cm show
  Show the current partition information of the specified geoms
  or all geoms if none are specified.
 +Default output shows the following information:
 +The first column shows the logical starting block of the
 +partition. Blocksize is 512 bytes.
 +The second column shows the partition size in blocks.
 +The third column shows the partition index.
 +The fourth column shows the partition type and a human readable
 +partition size.
  Additional options include:
  .Bl -tag -width 10n
  .It Fl l
 @@ -979,14 +986,14 @@
  Exit status is 0 on success, and 1 if the command fails.
  .Sh EXAMPLES
  Create a GPT scheme on
 -.Pa ad0 :
 +.Pa ada0 :
  .Bd -literal -offset indent
 -/sbin/gpart create -s GPT ad0
 +/sbin/gpart create -s GPT ada0
  .Ed
  .Pp
  Embed GPT bootstrap code into a protective MBR:
  .Bd -literal -offset indent
 -/sbin/gpart bootcode -b /boot/pmbr ad0
 +/sbin/gpart bootcode -b /boot/pmbr ada0
  .Ed
  .Pp
  Create a dedicated
 @@ -1011,15 +1018,15 @@
  offset or alignment.
  The boot partition itself is aligned on a 4 kB boundary.
  .Bd -literal -offset indent
 -/sbin/gpart add -b 40 -s 88 -t freebsd-boot ad0
 -/sbin/gpart bootcode -p /boot/gptboot -i 1 ad0
 +/sbin/gpart add -b 40 -s 88 -t freebsd-boot ada0
 +/sbin/gpart bootcode -p /boot/gptboot -i 1 ada0
  .Ed
  .Pp
  Create a 512MB-sized
  .Cm freebsd-ufs
  partition to contain a UFS filesystem from which the system can boot.
  .Bd -literal -offset indent
 -/sbin/gpart add -s 512M -t freebsd-ufs ad0
 +/sbin/gpart add -s 512M -t freebsd-ufs ada0
  .Ed
  .Pp
  Create an MBR scheme on
 
 
 --------------000701070309040301000003--
 

From: Bas Smeelen <b.smeelen@ose.nl>
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/174270: gpart(8) man page doesn't describe output of "show"
 command
Date: Mon, 10 Dec 2012 18:02:46 +0100

 This is a multi-part message in MIME format.
 --------------020101090408090201090207
 Content-Type: text/plain; charset=ISO-8859-1; format=flowed
 Content-Transfer-Encoding: 7bit
 
 Warren Block suggested a much better text, so here is a changed patch.
 
 
 
 
 --------------020101090408090201090207
 Content-Type: text/plain; charset=us-ascii;
  name="gpartmanpatch.diff"
 Content-Transfer-Encoding: 7bit
 Content-Disposition: attachment;
  filename="gpartmanpatch.diff"
 
 Index: sbin/geom/class/part/gpart.8
 ===================================================================
 --- sbin/geom/class/part/gpart.8	(revision 244078)
 +++ sbin/geom/class/part/gpart.8	(working copy)
 @@ -24,7 +24,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd March 19, 2012
 +.Dd December 10, 2012
  .Dt GPART 8
  .Os
  .Sh NAME
 @@ -455,6 +455,10 @@
  .It Cm show
  Show the current partition information of the specified geoms
  or all geoms if none are specified.
 +The default output includes the logical starting block of each
 +partition, the partition size in blocks, the partition index number,
 +the partition type, and a human readable partition size.
 +Block sizes and locations are based on 512-byte logical blocks.
  Additional options include:
  .Bl -tag -width 10n
  .It Fl l
 @@ -979,14 +983,14 @@
  Exit status is 0 on success, and 1 if the command fails.
  .Sh EXAMPLES
  Create a GPT scheme on
 -.Pa ad0 :
 +.Pa ada0 :
  .Bd -literal -offset indent
 -/sbin/gpart create -s GPT ad0
 +/sbin/gpart create -s GPT ada0
  .Ed
  .Pp
  Embed GPT bootstrap code into a protective MBR:
  .Bd -literal -offset indent
 -/sbin/gpart bootcode -b /boot/pmbr ad0
 +/sbin/gpart bootcode -b /boot/pmbr ada0
  .Ed
  .Pp
  Create a dedicated
 @@ -1011,15 +1015,15 @@
  offset or alignment.
  The boot partition itself is aligned on a 4 kB boundary.
  .Bd -literal -offset indent
 -/sbin/gpart add -b 40 -s 88 -t freebsd-boot ad0
 -/sbin/gpart bootcode -p /boot/gptboot -i 1 ad0
 +/sbin/gpart add -b 40 -s 88 -t freebsd-boot ada0
 +/sbin/gpart bootcode -p /boot/gptboot -i 1 ada0
  .Ed
  .Pp
  Create a 512MB-sized
  .Cm freebsd-ufs
  partition to contain a UFS filesystem from which the system can boot.
  .Bd -literal -offset indent
 -/sbin/gpart add -s 512M -t freebsd-ufs ad0
 +/sbin/gpart add -s 512M -t freebsd-ufs ada0
  .Ed
  .Pp
  Create an MBR scheme on
 
 --------------020101090408090201090207--
 
Responsible-Changed-From-To: freebsd-doc->wblock 
Responsible-Changed-By: wblock 
Responsible-Changed-When: Fri Dec 14 14:34:07 UTC 2012 
Responsible-Changed-Why:  
Take. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=174270 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/174270: commit references a PR
Date: Thu,  3 Jan 2013 21:58:41 +0000 (UTC)

 Author: wblock (doc committer)
 Date: Thu Jan  3 21:58:28 2013
 New Revision: 245012
 URL: http://svnweb.freebsd.org/changeset/base/245012
 
 Log:
   Document the output of the show command.  Modified version of patch
   provided by Bas Smeelen <b.smeelen@ose.nl>.  Use of 'gpart list'
   suggested by by Andrey V. Elsukov <ae@FreeBSD.org>.
   
   PR:		docs/174270
   Submitted by:	Ronald F.Guilmette <rfg@tristatelogic.com>
   Reviewed by:	ae (block sizes)
   MFC after:	1 week
 
 Modified:
   head/sbin/geom/class/part/gpart.8
 
 Modified: head/sbin/geom/class/part/gpart.8
 ==============================================================================
 --- head/sbin/geom/class/part/gpart.8	Thu Jan  3 21:54:44 2013	(r245011)
 +++ head/sbin/geom/class/part/gpart.8	Thu Jan  3 21:58:28 2013	(r245012)
 @@ -24,7 +24,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd March 19, 2012
 +.Dd January 3, 2013
  .Dt GPART 8
  .Os
  .Sh NAME
 @@ -453,8 +453,14 @@ about its use.
  .El
  .\" ==== SHOW ====
  .It Cm show
 -Show the current partition information of the specified geoms
 -or all geoms if none are specified.
 +Show current partition information for the specified geoms, or all
 +geoms if none are specified.
 +The default output includes the logical starting block of each
 +partition, the partition size in blocks, the partition index number,
 +the partition type, and a human readable partition size.
 +Block sizes and locations are based on the device's Sectorsize
 +as shown by
 +.Cm gpart list .
  Additional options include:
  .Bl -tag -width 10n
  .It Fl l
 @@ -919,7 +925,7 @@ and
  .Cm list
  will report about corrupt tables.
  .Pp
 -If the size of the device has changed (e.g.\& volume expansion) the
 +If the size of the device has changed (e.g.,\& volume expansion) the
  secondary GPT header will no longer be located in the last sector.
  This is not a metadata corruption, but it is dangerous because any
  corruption of the primary GPT will lead to loss of the partition table.
 @@ -979,14 +985,14 @@ This may break a mirrored volume and lea
  Exit status is 0 on success, and 1 if the command fails.
  .Sh EXAMPLES
  Create a GPT scheme on
 -.Pa ad0 :
 +.Pa ada0 :
  .Bd -literal -offset indent
 -/sbin/gpart create -s GPT ad0
 +/sbin/gpart create -s GPT ada0
  .Ed
  .Pp
  Embed GPT bootstrap code into a protective MBR:
  .Bd -literal -offset indent
 -/sbin/gpart bootcode -b /boot/pmbr ad0
 +/sbin/gpart bootcode -b /boot/pmbr ada0
  .Ed
  .Pp
  Create a dedicated
 @@ -1011,15 +1017,15 @@ aligned on a 64 kB boundary without the 
  offset or alignment.
  The boot partition itself is aligned on a 4 kB boundary.
  .Bd -literal -offset indent
 -/sbin/gpart add -b 40 -s 88 -t freebsd-boot ad0
 -/sbin/gpart bootcode -p /boot/gptboot -i 1 ad0
 +/sbin/gpart add -b 40 -s 88 -t freebsd-boot ada0
 +/sbin/gpart bootcode -p /boot/gptboot -i 1 ada0
  .Ed
  .Pp
  Create a 512MB-sized
  .Cm freebsd-ufs
  partition to contain a UFS filesystem from which the system can boot.
  .Bd -literal -offset indent
 -/sbin/gpart add -s 512M -t freebsd-ufs ad0
 +/sbin/gpart add -s 512M -t freebsd-ufs ada0
  .Ed
  .Pp
  Create an MBR scheme on
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/174270: commit references a PR
Date: Thu, 10 Jan 2013 23:06:39 +0000 (UTC)

 Author: wblock (doc committer)
 Date: Thu Jan 10 23:06:32 2013
 New Revision: 245270
 URL: http://svnweb.freebsd.org/changeset/base/245270
 
 Log:
   MFC r245012:
   
   Document the output of the show command.  Modified version of patch
   provided by Bas Smeelen <b.smeelen@ose.nl>.  Use of 'gpart list'
   suggested by by Andrey V. Elsukov <ae@FreeBSD.org>.
   
   PR:		docs/174270
   Submitted by:	Ronald F.Guilmette <rfg@tristatelogic.com>
   Reviewed by:	ae (block sizes)
 
 Modified:
   stable/9/sbin/geom/class/part/gpart.8
 Directory Properties:
   stable/9/sbin/geom/class/part/   (props changed)
 
 Modified: stable/9/sbin/geom/class/part/gpart.8
 ==============================================================================
 --- stable/9/sbin/geom/class/part/gpart.8	Thu Jan 10 22:44:19 2013	(r245269)
 +++ stable/9/sbin/geom/class/part/gpart.8	Thu Jan 10 23:06:32 2013	(r245270)
 @@ -24,7 +24,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd March 19, 2012
 +.Dd January 3, 2013
  .Dt GPART 8
  .Os
  .Sh NAME
 @@ -453,8 +453,14 @@ about its use.
  .El
  .\" ==== SHOW ====
  .It Cm show
 -Show the current partition information of the specified geoms
 -or all geoms if none are specified.
 +Show current partition information for the specified geoms, or all
 +geoms if none are specified.
 +The default output includes the logical starting block of each
 +partition, the partition size in blocks, the partition index number,
 +the partition type, and a human readable partition size.
 +Block sizes and locations are based on the device's Sectorsize
 +as shown by
 +.Cm gpart list .
  Additional options include:
  .Bl -tag -width 10n
  .It Fl l
 @@ -919,7 +925,7 @@ and
  .Cm list
  will report about corrupt tables.
  .Pp
 -If the size of the device has changed (e.g.\& volume expansion) the
 +If the size of the device has changed (e.g.,\& volume expansion) the
  secondary GPT header will no longer be located in the last sector.
  This is not a metadata corruption, but it is dangerous because any
  corruption of the primary GPT will lead to loss of the partition table.
 @@ -979,14 +985,14 @@ This may break a mirrored volume and lea
  Exit status is 0 on success, and 1 if the command fails.
  .Sh EXAMPLES
  Create a GPT scheme on
 -.Pa ad0 :
 +.Pa ada0 :
  .Bd -literal -offset indent
 -/sbin/gpart create -s GPT ad0
 +/sbin/gpart create -s GPT ada0
  .Ed
  .Pp
  Embed GPT bootstrap code into a protective MBR:
  .Bd -literal -offset indent
 -/sbin/gpart bootcode -b /boot/pmbr ad0
 +/sbin/gpart bootcode -b /boot/pmbr ada0
  .Ed
  .Pp
  Create a dedicated
 @@ -1011,15 +1017,15 @@ aligned on a 64 kB boundary without the 
  offset or alignment.
  The boot partition itself is aligned on a 4 kB boundary.
  .Bd -literal -offset indent
 -/sbin/gpart add -b 40 -s 88 -t freebsd-boot ad0
 -/sbin/gpart bootcode -p /boot/gptboot -i 1 ad0
 +/sbin/gpart add -b 40 -s 88 -t freebsd-boot ada0
 +/sbin/gpart bootcode -p /boot/gptboot -i 1 ada0
  .Ed
  .Pp
  Create a 512MB-sized
  .Cm freebsd-ufs
  partition to contain a UFS filesystem from which the system can boot.
  .Bd -literal -offset indent
 -/sbin/gpart add -s 512M -t freebsd-ufs ad0
 +/sbin/gpart add -s 512M -t freebsd-ufs ada0
  .Ed
  .Pp
  Create an MBR scheme on
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/174270: commit references a PR
Date: Thu, 10 Jan 2013 23:39:41 +0000 (UTC)

 Author: wblock (doc committer)
 Date: Thu Jan 10 23:39:28 2013
 New Revision: 245273
 URL: http://svnweb.freebsd.org/changeset/base/245273
 
 Log:
   MFC r245012:
   
   Document the output of the show command.  Modified version of patch
   provided by Bas Smeelen <b.smeelen@ose.nl>.  Use of 'gpart list'
   suggested by by Andrey V. Elsukov <ae@FreeBSD.org>.
   
   PR:		docs/174270
   Submitted by:	Ronald F.Guilmette <rfg@tristatelogic.com>
   Reviewed by:	ae (block sizes)
 
 Modified:
   stable/8/sbin/geom/class/part/gpart.8
 Directory Properties:
   stable/8/sbin/geom/class/part/   (props changed)
 
 Modified: stable/8/sbin/geom/class/part/gpart.8
 ==============================================================================
 --- stable/8/sbin/geom/class/part/gpart.8	Thu Jan 10 23:36:02 2013	(r245272)
 +++ stable/8/sbin/geom/class/part/gpart.8	Thu Jan 10 23:39:28 2013	(r245273)
 @@ -24,7 +24,7 @@
  .\"
  .\" $FreeBSD$
  .\"
 -.Dd March 19, 2012
 +.Dd January 3, 2013
  .Dt GPART 8
  .Os
  .Sh NAME
 @@ -453,8 +453,14 @@ about its use.
  .El
  .\" ==== SHOW ====
  .It Cm show
 -Show the current partition information of the specified geoms
 -or all geoms if none are specified.
 +Show current partition information for the specified geoms, or all
 +geoms if none are specified.
 +The default output includes the logical starting block of each
 +partition, the partition size in blocks, the partition index number,
 +the partition type, and a human readable partition size.
 +Block sizes and locations are based on the device's Sectorsize
 +as shown by
 +.Cm gpart list .
  Additional options include:
  .Bl -tag -width 10n
  .It Fl l
 @@ -919,7 +925,7 @@ and
  .Cm list
  will report about corrupt tables.
  .Pp
 -If the size of the device has changed (e.g.\& volume expansion) the
 +If the size of the device has changed (e.g.,\& volume expansion) the
  secondary GPT header will no longer be located in the last sector.
  This is not a metadata corruption, but it is dangerous because any
  corruption of the primary GPT will lead to loss of the partition table.
 @@ -979,14 +985,14 @@ This may break a mirrored volume and lea
  Exit status is 0 on success, and 1 if the command fails.
  .Sh EXAMPLES
  Create a GPT scheme on
 -.Pa ad0 :
 +.Pa ada0 :
  .Bd -literal -offset indent
 -/sbin/gpart create -s GPT ad0
 +/sbin/gpart create -s GPT ada0
  .Ed
  .Pp
  Embed GPT bootstrap code into a protective MBR:
  .Bd -literal -offset indent
 -/sbin/gpart bootcode -b /boot/pmbr ad0
 +/sbin/gpart bootcode -b /boot/pmbr ada0
  .Ed
  .Pp
  Create a dedicated
 @@ -1002,19 +1008,19 @@ or the GPT boot you are planning to writ
  A size of 15 blocks (7680 bytes) would be sufficient for
  booting from UFS but 128 blocks (64 KB) is used in
  this example to reserve some space for potential
 -future need (e.g.\& a larger
 +future need (e.g.,\& a larger
  .Pa /boot/gptzfsboot
  for booting from a ZFS partition).
  .Bd -literal -offset indent
 -/sbin/gpart add -b 34 -s 128 -t freebsd-boot ad0
 -/sbin/gpart bootcode -p /boot/gptboot -i 1 ad0
 +/sbin/gpart add -b 34 -s 128 -t freebsd-boot ada0
 +/sbin/gpart bootcode -p /boot/gptboot -i 1 ada0
  .Ed
  .Pp
  Create a 512MB-sized
  .Cm freebsd-ufs
  partition to contain a UFS filesystem from which the system can boot.
  .Bd -literal -offset indent
 -/sbin/gpart add -b 162 -s 1048576 -t freebsd-ufs ad0
 +/sbin/gpart add -b 162 -s 1048576 -t freebsd-ufs ada0
  .Ed
  .Pp
  Create an MBR scheme on
 _______________________________________________
 svn-src-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-src-all
 To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: open->closed 
State-Changed-By: wblock 
State-Changed-When: Sat Jan 12 17:00:59 UTC 2013 
State-Changed-Why:  
Changes committed and MFCed to FreeBSD 9-STABLE and FreeBSD 8-STABLE. 

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