From swear@blarg.net Fri Mar 15 19:43:08 2002 Return-Path: Received: from lists.blarg.net (lists.blarg.net [206.124.128.17]) by hub.freebsd.org (Postfix) with ESMTP id 3BE5037B402 for ; 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 ; 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 ; 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: Date: 15 Mar 2002 19:45:49 -0800 From: "Gary W. Swearingen" 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 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 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 , Gary W. Swearingen 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. 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 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 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: