Bug 35951

Summary: disklabel(8) manual confuses partitions and slices, etc.
Product: Documentation Reporter: Gary W. Swearingen <swear>
Component: Books & ArticlesAssignee: Tom Rhodes <trhodes>
Status: Closed FIXED    
Severity: Affects Only Me    
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   

Description Gary W. Swearingen 2002-03-16 03:50:00 UTC 
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).)
================

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.)
How-To-Repeat: n/a
================
Comment 1 Tom Rhodes freebsd_committer freebsd_triage 2002-04-11 20:31:22 UTC 
State Changed
From-To: open->analyzed

disklabel(8) does need a good bit of work, I am currently chipping away 
at it.  Thanks.
Comment 2 Tom Rhodes freebsd_committer freebsd_triage 2002-04-11 20:31:22 UTC 
Responsible Changed
From-To: freebsd-doc->trhodes

disklabel(8) does need a good bit of work, I am currently chipping away 
at it.  Thanks.
Comment 3 Gary W. Swearingen 2003-01-22 19:45:34 UTC 
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.
Comment 4 Tom Rhodes freebsd_committer freebsd_triage 2003-01-23 23:23:36 UTC 
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
Comment 5 mwm-dated-1043967204.e45b13 2003-01-25 22:53:23 UTC 
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.
Comment 6 Gary W. Swearingen 2003-01-26 06:28:01 UTC 
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.
Comment 7 Tom Rhodes freebsd_committer freebsd_triage 2003-04-15 16:44:54 UTC 
State Changed
From-To: analyzed->patched

ru has done a complete makeover of this manual page in CURRENT. 
I'll MFC the STABLE applicable diffs soon.
Comment 8 Matteo Riondato freebsd_committer freebsd_triage 2005-08-16 21:14:20 UTC 
State Changed
From-To: patched->closed

trhodes MFC'ed this long ago.