Give example of deleting partitions and partitioning scheme
ClosedPublic

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

Details

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
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.
danfe created this revision.Sep 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
danfe added a comment.Sep 16 2017, 2:03 PM

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

bjk requested changes to this revision.Sep 16 2017, 7:04 PM
bjk added a subscriber: bjk.

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
danfe updated this revision to Diff 33186.EditedSep 18 2017, 2:42 PM
danfe marked 4 inline comments as done.

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).

bjk accepted this revision.Sep 19 2017, 12:02 AM

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
ae added a comment.Sep 19 2017, 2:39 PM

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.

danfe added a comment.Sep 19 2017, 3:07 PM

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.

This revision was automatically updated to reflect the committed changes.
yuripv_gmx.com added inline comments.
head/sbin/geom/class/part/gpart.8
1350

This block closer seems to be superfluous:

mandoc: gpart.8:1350:2: ERROR: skipping end of block that is not open: Ed

danfe added a comment.Sep 19 2017, 3:27 PM

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

This should be title-capitalized.

.Ss Deleting Partitions and Partitioning Scheme
1329
If a
1331
error is shown when trying to destroy a partition table, remember that
1332
all of the partitions must be deleted first with the
1335
In this example,
1337
has three partitions:
1345

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.
wblock added a comment.Dec 8 2017, 5:54 PM

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”."

danfe added a comment.Dec 12 2017, 3:14 PM

@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.