Bug 174270

Summary: gpart(8) man page doesn't describe output of "show" command
Product: Documentation Reporter: Ronald F. Guilmette <rfg>
Component: Books & ArticlesAssignee: Warren Block <wblock>
Status: Closed FIXED    
Severity: Affects Only Me CC: rfg
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   
Attachments:
Description Flags
gpartmanpatch.diff
none
gpartmanpatch.diff none

Description Ronald F. Guilmette 2012-12-08 00:50:00 UTC 
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.

Fix: 

Somebody needs to document what each of the four columns of "gpart show"
output are actually telling the user.
How-To-Repeat: 
man gpart
Comment 1 Bas Smeelen 2012-12-10 08:36:19 UTC 
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:
Comment 2 Bas Smeelen 2012-12-10 17:02:46 UTC 
Warren Block suggested a much better text, so here is a changed patch.
Comment 3 Warren Block freebsd_committer freebsd_triage 2012-12-14 14:34:07 UTC 
Responsible Changed
From-To: freebsd-doc->wblock

Take.
Comment 4 dfilter service freebsd_committer freebsd_triage 2013-01-03 21:58:41 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"
Comment 5 dfilter service freebsd_committer freebsd_triage 2013-01-10 23:06:39 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"
Comment 6 dfilter service freebsd_committer freebsd_triage 2013-01-10 23:39:41 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"
Comment 7 Warren Block freebsd_committer freebsd_triage 2013-01-12 17:00:59 UTC 
State Changed
From-To: open->closed

Changes committed and MFCed to FreeBSD 9-STABLE and FreeBSD 8-STABLE.