From swear@blarg.net  Fri Mar 15 19:43:08 2002
Return-Path: <swear@blarg.net>
Received: from lists.blarg.net (lists.blarg.net [206.124.128.17])
	by hub.freebsd.org (Postfix) with ESMTP id 3BE5037B402
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 15 Mar 2002 19:43:05 -0800 (PST)
Received: from thig.blarg.net (thig.blarg.net [206.124.128.18])
	by lists.blarg.net (Postfix) with ESMTP id E99EABE57
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 15 Mar 2002 19:43:04 -0800 (PST)
Received: from localhost.localdomain ([206.124.139.115])
	by thig.blarg.net (8.9.3/8.9.3) with ESMTP id TAA03517
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 15 Mar 2002 19:43:04 -0800
Received: (from jojo@localhost)
	by localhost.localdomain (8.11.6/8.11.3) id g2G3jnw67090;
	Fri, 15 Mar 2002 19:45:49 -0800 (PST)
	(envelope-from swear@blarg.net)
Message-Id: <z13cz1ch02.cz1@localhost.localdomain>
Date: 15 Mar 2002 19:45:49 -0800
From: "Gary W. Swearingen" <swear@blarg.net>
Reply-To: swear@blarg.net
To: FreeBSD-gnats-submit@freebsd.org
Subject: disklabel(8) manual confuses partitions and slices, etc.
X-GNATS-Notify:

>Number:         35951
>Category:       docs
>Synopsis:       disklabel(8) manual confuses partitions and slices, etc.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Mar 15 19:50:00 PST 2002
>Closed-Date:    Tue Aug 16 20:14:56 GMT 2005
>Last-Modified:  Tue Aug 16 20:14:56 GMT 2005
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 4.5-STABLE i386
>Organization:
none
>Environment:
n/a
================
>Description:

The "Raw or in-core label" section of the disklabel(8) manual uses
"partition" to refer to a slice (in the first sentence). Some other
places use "partition" in the usual FreeBSD meaning.

The manual also confusingly uses the term "DOS partition" and the
idiosyncratic term "DOS slice".

The term "Microsoft partition table" would be better as "MBR partition
table".

A related problem, which maybe should have it's own PR, is that several
mentions of "disk" or "drive" should have "or slice" added.

It would probably also be better to consistently use "disk" instead of
often using "drive" or "disk drive" as it does. (It's not drivelabel(8).)
================
>How-To-Repeat:
n/a
================
>Fix:

Go through the manual and ensure that each use of "partition", "slice",
and their variants (eg, "DOS partitioning") is unambiguous and correct.

The terms used by the manual could be explained, but I think it is
better to assume that readers have learned in the Handbook what these
two terms mean in FreeBSD documentation and use them religiously.  Don't
use "DOS" as part of our terminology except in defining our terminology.

(Actually, I'd prefer that "slice" be replaced with "primary partition"
and "partition" with "secondary partition" throughout the documentation,
but I don't expect that will be done.)
>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->analyzed 
State-Changed-By: trhodes 
State-Changed-When: Thu Apr 11 12:31:22 PDT 2002 
State-Changed-Why:  
disklabel(8) does need a good bit of work, I am currently chipping away 
at it.  Thanks. 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Thu Apr 11 12:31:22 PDT 2002 
Responsible-Changed-Why:  
disklabel(8) does need a good bit of work, I am currently chipping away 
at it.  Thanks. 

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

From: swear@attbi.com (Gary W. Swearingen)
To: FreeBSD-gnats-submit@FreeBSD.org
Cc: freebsd-doc@FreeBSD.org, mwm@mired.org, trhodes@FreeBSD.org
Subject: Re: docs/35951; disklabel(8) patch; PLEASE REVIEW
Date: 22 Jan 2003 11:45:34 -0800

 I've made a 1300-line patch for disklabel(8) which I'm sure I will
 need some more work, especially if someone(s) will be kind enough as to
 review it and provide comments.
 
 You can find the thing with
 http://home.attbi.com/~swear/freebsd/disklabel.8.diff
 http://home.attbi.com/~swear/freebsd/disklabel.8.mdoc
 http://home.attbi.com/~swear/freebsd/disklabel.8.html
 
 After it gets reviewed/changed, I'd like to make a couple moves:
 
     -- The "Examples" section up to between "Description" and
     "Files" (instead of between "Saved File Format" and "See Also").
     (That doesn't give my preferred order, but this seems better, while
     generally following tradition.)
     -- "Initializing/Formatting..." subsection to "NOTES" section
     because it doesn't belong with the command descriptions as now.
      -- "Enabling and disabling ..." section to above the "Writing a
     disk label" section. (Gotta enable before writing.)
 
 I based many changes on testing and code review.  I know it could say
 more about some things, but I've added about all I care to.
 
 If this ever gets closed, docs/35948 can be closed too.

From: Tom Rhodes <trhodes@FreeBSD.org>
To: swear@attbi.com (Gary W. Swearingen)
Cc: FreeBSD-gnats-submit@FreeBSD.org, freebsd-doc@FreeBSD.org,
	mwm@mired.org
Subject: Re: docs/35951; disklabel(8) patch; PLEASE REVIEW
Date: Thu, 23 Jan 2003 18:23:36 -0500

 On 22 Jan 2003 11:45:34 -0800
 swear@attbi.com (Gary W. Swearingen) wrote:
 
 > I've made a 1300-line patch for disklabel(8) which I'm sure I will
 > need some more work, especially if someone(s) will be kind enough as
 > to review it and provide comments.
 > 
 > You can find the thing with
 > http://home.attbi.com/~swear/freebsd/disklabel.8.diff
 > http://home.attbi.com/~swear/freebsd/disklabel.8.mdoc
 > http://home.attbi.com/~swear/freebsd/disklabel.8.html
 > 
 > After it gets reviewed/changed, I'd like to make a couple moves:
 > 
 >     -- The "Examples" section up to between "Description" and
 >     "Files" (instead of between "Saved File Format" and "See Also").
 >     (That doesn't give my preferred order, but this seems better,
 >     while generally following tradition.)
 >     -- "Initializing/Formatting..." subsection to "NOTES" section
 >     because it doesn't belong with the command descriptions as now.
 >      -- "Enabling and disabling ..." section to above the "Writing a
 >     disk label" section. (Gotta enable before writing.)
 > 
 > I based many changes on testing and code review.  I know it could say
 > more about some things, but I've added about all I care to.
 > 
 > If this ever gets closed, docs/35948 can be closed too.
 > 
 
 I'm really likeing this, but will need a free hour or so to
 really review it.  Save me a spot ;)
 
 --
 Tom Rhodes

From: Mike Meyer <mwm-dated-1043967204.e45b13@mired.org>
To: swear@attbi.com (Gary W. Swearingen)
Cc: FreeBSD-gnats-submit@FreeBSD.org, freebsd-doc@FreeBSD.org,
	trhodes@FreeBSD.org
Subject: Re: docs/35951; disklabel(8) patch; PLEASE REVIEW
Date: Sat, 25 Jan 2003 16:53:23 -0600

 In <xd8yxdnf35.yxd@localhost.localdomain>, Gary W. Swearingen <swear@attbi.com> typed:
 > I've made a 1300-line patch for disklabel(8) which I'm sure I will
 > need some more work, especially if someone(s) will be kind enough as to
 > review it and provide comments.
 
 You say there may be one to four slices. disklabel works fine on
 extended slices, so there can be more than four of them. It's not
 clear that the disklabel docs should explain extended slices.
 
 Other than that, it looks good to me.
 
 	<mike
 -- 
 Mike Meyer <mwm@mired.org>		http://www.mired.org/consulting.html
 Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.

From: swear@attbi.com (Gary W. Swearingen)
To: Mike Meyer <mwm@mired.org>
Cc: FreeBSD-gnats-submit@FreeBSD.org, freebsd-doc@FreeBSD.org,
	trhodes@FreeBSD.org
Subject: Re: docs/35951; disklabel(8) patch; PLEASE REVIEW
Date: 25 Jan 2003 22:28:01 -0800

 Mike Meyer <mwm@mired.org> writes:
 
 > You say there may be one to four slices. disklabel works fine on
 > extended slices, so there can be more than four of them. It's not
 > clear that the disklabel docs should explain extended slices.
 
 Whoops.  I had forgotten about ad0s5, etc.  I think the manpage might as
 well mention them if the program (and the kernel) supports them.  I
 needn't explain about booting to them with an advanced boot loader, etc.
 
 It looks like it won't change much but mostly require an explanation of
 why there can be more than four slices.  I might try to avoid mentioning
 the primary/secondary slice difference and just refer to the primary
 slices as the first four.  This would avoid the need to use the
 contested term "extended".  (It's my strong opinion, shared by many
 document writers, that in IBM-PC jargon, an extended partition is a
 primary partition which contains additional "logical disks", which I
 would translate to "secondary slices" for s5, s6, etc., and "extended
 slice" to the "primary slice" which contains them.  If I need to
 introduce terms for these concepts, I'll probably have go looking for
 some IBM-PC or IDE/ATA documentation to see what they used.)
 
 Thanks.
State-Changed-From-To: analyzed->patched 
State-Changed-By: trhodes 
State-Changed-When: Tue Apr 15 08:44:54 PDT 2003 
State-Changed-Why:  
ru has done a complete makeover of this manual page in CURRENT. 
I'll MFC the STABLE applicable diffs soon. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=35951 
State-Changed-From-To: patched->closed 
State-Changed-By: matteo 
State-Changed-When: Tue Aug 16 20:14:20 GMT 2005 
State-Changed-Why:  
trhodes MFC'ed this long ago. 

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