Give example of deleting partitions and partitioning scheme
ClosedPublic
Actions

Authored by danfe on Sep 12 2017, 10:14 AM.

Details

Reviewers

ae
bjk

Group Reviewers

manpages

Commits

rS330291: Clarify and clean up some language, and add an explicit example.
rS323764: Provide an articulate example of how to properly delete partitions and

Summary

Our users (including myself) often get confused and frustrated when trying to delete partition table and getting Device busy error because they forgot (or do not ever know that they have) to delete all its partitions first. Manual page mentions this briefly, but does not stress it out enough. Personally I always forget this ~~annoying~~ feature and have to google the answer every time I want to delete partition table on some drive.

Provide working example and explanation of Device busy error and how to properly deal with it.

Diff Detail

Repository

rS FreeBSD src repository - subversion

Lint

Lint Skipped

Unit

Tests Skipped

Build Status

Buildable 11618

Event Timeline

danfe created this revision.Sep 12 2017, 10:14 AM

Herald added a subscriber: imp. · View Herald TranscriptSep 12 2017, 10:14 AM

ae accepted this revision.Sep 12 2017, 10:21 AM

This revision is now accepted and ready to land.Sep 12 2017, 10:21 AM

Still waiting for a review/clearance from manpages...

manpages here.
Just a few minor tweaks for silly parts of the English language (inline).

You could update the date in .Dd to match the commit date when committing if you want.

There is also a general trend to avoid using "you" and addressing the reader directly, though I am not going to insist that you rewrite the whole thing to comply with that.

/usr/src/sbin/geom/class/part/gpart.8
1330 ↗	(On Diff #32954)	Add an 'a' for "If you get a"
1332 ↗	(On Diff #32954)	"with the"
1345 ↗	(On Diff #32954)	"invoke the"
1347 ↗	(On Diff #32954)	"with the"

This revision now requires changes to proceed.Sep 16 2017, 7:04 PM

I wholly agree with you that addressing the reader this way better be avoided, but I failed to come up with you-less wording (I've tried to dance off e.g. the "If one gets..." but it sounded/looked even worse).

Eventually I've decided it was OK here in the EXAMPLES section, and also because you is already (ab)used earlier in the manual page (a NOTE before SYSCTL VARIABLES section). If someone comes with a better wording we can always improve it in the future revisions. For the time being, I feel this change is good enough and useful even in its current form (after fixed articles).

In D12336#257288, @danfe wrote:

I wholly agree with you that addressing the reader this way better be avoided, but I failed to come up with you-less wording (I've tried to dance off e.g. the "If one gets..." but it sounded/looked even worse).

Eventually I've decided it was OK here in the EXAMPLES section, and also because you is already (ab)used earlier in the manual page (a NOTE before SYSCTL VARIABLES section). If someone comes with a better wording we can always improve it in the future revisions. For the time being, I feel this change is good enough and useful even in its current form (after fixed articles).

I agree that it is useful even in its current form, thanks for putting it together.

This revision is now accepted and ready to land.Sep 19 2017, 12:02 AM

It would be good to note also about the error when you can not modify partition table until it will be recovered.
This is frequent problem when GPT is marked as CORRUPT.

Noted @ae; I'll think about how to put this piece of information into the manpage and come up with another diff. Meanwhile let's close this one first.

Closed by commit rS323764: Provide an articulate example of how to properly delete partitions and (authored by danfe). · Explain WhySep 19 2017, 3:08 PM

This revision was automatically updated to reflect the committed changes.

yuripv_gmx.com added a subscriber: yuripv_gmx.com.Sep 19 2017, 3:17 PM

yuripv_gmx.com added inline comments.

head/sbin/geom/class/part/gpart.8
1350 ↗	(On Diff #33224)	This block closer seems to be superfluous: mandoc: gpart.8:1350:2: ERROR: skipping end of block that is not open: Ed

Yuri, can you provide a patch and run it through the manpages? I'm myself not a mandoc expert of any kind...

wblock added a subscriber: wblock.Dec 8 2017, 5:52 PM

wblock added inline comments.

head/sbin/geom/class/part/gpart.8
1328 ↗	(On Diff #33224)	This should be title-capitalized. .Ss Deleting Partitions and Partitioning Scheme
1329 ↗	(On Diff #33224)	If a
1331 ↗	(On Diff #33224)	error is shown when trying to destroy a partition table, remember that
1332 ↗	(On Diff #33224)	all of the partitions must be deleted first with the
1335 ↗	(On Diff #33224)	In this example,
1337 ↗	(On Diff #33224)	has three partitions:
1345 ↗	(On Diff #33224)	Please don't use that halting "Alternatively," start to a sentence. Rather than deleting the partitions and then destroying the partitioning scheme, the .Fl F option can be given with .Cm destroy to automatically delete the partitions first.

Oh, and as far as the use of "you", we do have specific guidelines to avoid it: https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style.html

"Write in a formal style. Avoid addressing the reader as “you”. For example, say “copy the file to /tmp” rather than “you can copy the file to /tmp”."

@wblock, while your comments are certainly valid, they arrived a bit too late (special note on the "usage of you": yes, I know and agree this is a bad style, but I failed to come up with you-less wording, see the earlier comments).

As a manpages member and committer, I guess you can simply fix those shortcomings in one of the next usual sweep over the manpages.

Revision Contents
Changeset List

Path

Size

gpart.8

25 lines

Diff 33186

View Options

Give example of deleting partitions and partitioning schemeClosedPublicActions