Convert ZFS chapter to active voice and remove weasel/unnecessary words

[bcr]

Summary

Convert many of the sentences in this chapter from passive to active voice. Example: "... a data error has been detected" (passive) vs. "detecting a data error" (active). In many cases, the sentences became shorter, but also easier to read and understand. In some instances, adding ZFS in places where the sentence would become too short.
Note to translators: In some cases, I merged a short sentence into the previous one to improve reading flow.

Remove weasel and unnecessary words that do not add any extra meaning to the sentence like: many, significantly, very, relatively, a number of, clearly, extremely, etc.

Test Plan

1. Apply the patch do a doc tree checkout
2. Build the handbook
3. Read the output

[bcr]

content/en/books/handbook/zfs/_index.adoc

2533 ↗

(On Diff #94611)

I changed it to /usr/bin and removed mentions of "the ports tree" in surrounding sentences.
I think we always assume that /bin/sh is used for shell scripts like this in the handbook. Otherwise, we'd have to mention something like "adapt to your shell syntax if necessary" to each example.
In this particular example, the loop is not really necessary for the gist of this example, but speeds things up.

[bcr]

Update including the lastest suggestions to the lower last part of the chapter.

[pauamma_gundo.com]

Mentioning it here to avoid repeating it a gazillion times: 1 sentence per line.

Not done yet for tonight but Chromium just crashed on me, and while it somehow restored the partial review when I restarted it, I don't count on that happening twice, no siree.

content/en/books/handbook/zfs/_index.adoc

2614 ↗

(On Diff #94688)

*ponders* To me, "the mountpoint where mounting the file system", looks like it's missing a large part of the sentence. I think "the mountpoint where to mount the file system" would be better.

Unrelatedly; is it "mountpoint" or "mount point"?

2628 ↗

(On Diff #94688)

This way, it sounds less like ordering the user around and more like offering options for their consideration.

2630 ↗

(On Diff #94688)

To me, "upper size of" reads as "size of the upper part of". I would either keep "maximum" or, if you prefer "upper", use something like "upper limit of the size of.

2632 ↗

(On Diff #94688)

2633 ↗

(On Diff #94688)

2634 ↗

(On Diff #94688)

2639 ↗

(On Diff #94688)

Maybe add an explanation of how to check? I had a look into dmesg.boot on my laptop, which reports 512 bytes but given the above, it may be wrong. Is the best answer "look up the drive's spec sheet on the Internet"?

2643 ↗

(On Diff #94688)

"will use" or "may use", I think.

2646 ↗

(On Diff #94688)

Since it's countable here, not mass. Taste.

2649 ↗

(On Diff #94688)

Taste, concision.

2651 ↗

(On Diff #94688)

Also, see above re "upper" vs "maximum".

2654 ↗

(On Diff #94688)

Taste, clarity, redundant spaces not after a full stop.

2655 ↗

(On Diff #94688)

Same as above

2657 ↗

(On Diff #94688)

See above upper vs. maximum. Also, spurious spaces.

2662 ↗

(On Diff #94688)

If you don't like "maximum" here, maybe "better" or "higher"?

2666 ↗

(On Diff #94688)

2688 ↗

(On Diff #94688)

Missing subject here.

2713 ↗

(On Diff #94688)

2716 ↗

(On Diff #94688)

Concision.

2717 ↗

(On Diff #94688)

I think this is what you meant. While there, I also used the term introduced above.

2726 ↗

(On Diff #94688)

First sentence redundant with above, but since this is a glossary, I would keep it anyway.

Unless it's the name+GUID pair that identifies the pool, I would s/and/or/ in the 2nd sentence and maybe add "either".

2729 ↗

(On Diff #94688)

Assuming a few vdevs allow spreading, not just a lot (however many that means).

What's the initial "a|" for? Index term?

2737 ↗

(On Diff #94688)

Hey, I wrote that! *toot toot*

[pauamma_gundo.com]

Aaaaaaaand done! (Split glossary to 1 sentence per line, please.)

content/en/books/handbook/zfs/_index.adoc

2740 ↗

(On Diff #94688)

Last sentence should be a paragraph of its own. Not sure whether it's better here or at the start of the vdev type section.

2745 ↗

(On Diff #94688)

Clarity

2748 ↗

(On Diff #94688)

2750 ↗

(On Diff #94688)

Grammar

2752 ↗

(On Diff #94688)

Is that recommendation still valid?

2755 ↗

(On Diff #94688)

Maybe nitpicking, but if not deployed automagically, are they still *hot* spares?

2756 ↗

(On Diff #94688)

Spurious spaces, grammar, a lot vs. several.

2757 ↗

(On Diff #94688)

Maybe nitpicking, but I think "only"worked better than "alone" here. The cache device doesn't have other duties, but it may (I think) share these duties with other cache devices.

2760 ↗

(On Diff #94688)

"assert" doesn't look quite right. Maybe "ensure" or "guarantee"?

2762 ↗

(On Diff #94688)

"There is always a transaction group in the open state" was better, I think. Your version confused me since I understood it as "a (given) transaction group remains in the open state forever".

2763 ↗

(On Diff #94688)

Taste.

2764 ↗

(On Diff #94688)

Or perhaps "a number of passes" if you mean it's unbounded or maybe large. Your call.

Also, check I didn't change the meaning of the description of successive passes.

2767 ↗

(On Diff #94688)

While here (maybe for a later scrub): "LRU" feels wrong here, since the ordering and the insertion of new objects both feel more like "MRU" to me.

2770 ↗

(On Diff #94688)

What's a DDT?

2773 ↗

(On Diff #94688)

See above for only vs. alone.

2779 ↗

(On Diff #94688)

Only one of each.

Also, "technically"?

2782 ↗

(On Diff #94688)

"most others"?

If you don't want "is mounted", perhaps "the kernel mounts a ZFS file system"?

2785 ↗

(On Diff #94688)

IIRC, there's no longer any such thing in FreeBSD as a block device.

Also, "a lot of the same features" as what? Datasets?

2788 ↗

(On Diff #94688)

Unsplit sentence here and on next line while splitting into 1-sentence lines?

2789 ↗

(On Diff #94688)

I don't understand what you mean by "Also mark snapshots with a <<zfs-zfs-snapshot,hold>>." Is that an order to the user or an option available to them?

Ditto for "Take snapshots on volumes, clone, or roll back to them, but not mount independently."

2792 ↗

(On Diff #94688)

"a snapshot" or "snapshots". (Also, isn't most or all of this also covered earlier? Maybe link there instead of repeating it and risking eventual inconsistency.)

2795 ↗

(On Diff #94688)

Duplicates earlier material better linked to?

2800 ↗

(On Diff #94688)

Isn't it strongly discouraged rather than merely "not recommended"?

2806 ↗

(On Diff #94688)

Arguably very nitpicky here, but crabs gotta crab.

2815 ↗

(On Diff #94688)

Why the initial caps in "File System" and "Volume"?

2818 ↗

(On Diff #94688)

Clarity, concision, spurious spaces.

2824 ↗

(On Diff #94688)

"a|"?

2828 ↗

(On Diff #94688)

Taste.

2832 ↗

(On Diff #94688)

Word choice.

2836 ↗

(On Diff #94688)

Contrast with "Quotas" above?

2845 ↗

(On Diff #94688)

What I think you mean.

2847 ↗

(On Diff #94688)

By "audio logs", do you mean sound files specifically, audi*t* logs, or generic (potentially) huge files in general?

2850 ↗

(On Diff #94688)

Grammar, word choice, spurious spaces.

2858 ↗

(On Diff #94688)

What does the first sentence mean?

2861 ↗

(On Diff #94688)

Word choice, clarity.

2864 ↗

(On Diff #94688)

Grammar, clarity, taste.

[bcr]

Yet another update addressing some of @pauamma_gundo.com's comments.

[bcr]

Update with some of my own replies.

content/en/books/handbook/zfs/_index.adoc

2740 ↗

(On Diff #94688)

I removed it from here and moved it into the vdev Types section above.

2752 ↗

(On Diff #94688)

Not sure, but I think we need to do a separate technical review of the chapter with all the new stuff that came in OpenZFS 2.0.

2757 ↗

(On Diff #94688)

That would contradict the sentence "Mirroring cache devices is impossible".

[pauamma_gundo.com]

I'll have another look at the whole thing, but it will likely be a few days before I can.

content/en/books/handbook/zfs/_index.adoc

2757 ↗

(On Diff #94688)

Now I'm confused about the whole paragraph. I assumed "Adding a cache vdev to a pool will add the storage of the cache to the <<zfs-term-l2arc,L2ARC>>" meant you can have several vdevs in the L2ARC, and that's why I suggested "only" (as in, "L2ARC doesn't store any other data") instead of "alone" (which to me means "this vdev and no other").

[bcr]

Reply with confirmation about the L2ARC vdevs question.

content/en/books/handbook/zfs/_index.adoc

2757 ↗

(On Diff #94688)

it is possible to have several L2ARC vdev cache devices (striped, not mirrored), see:
https://www.truenas.com/docs/references/l2arc/

I'll change it back to only then.

[bcr]

Change an instance of "alone" to "only" in the L2ARC description to not confuse people about adding multiple devices there.

[pauamma_gundo.com]

As far as I'm concerned, I think you can go ahead and commit at your discretion after this round of (very minor) suggestions. Getting to diminishing returns here.

content/en/books/handbook/zfs/_index.adoc

6 ↗

(On Diff #97682)

Is "designs" the best word here? I'm tempted to say "file systems" but that's only a part of what ZFS does and its integration of several layers is its major strength, so perhaps "storage subsystem software", for all that it's a mouthful?

52 ↗

(On Diff #97682)

Difference between "ditto" and "mirror"?

68 ↗

(On Diff #97682)

305 ↗

(On Diff #97682)

367 ↗

(On Diff #97682)

Or "a disk being"

868 ↗

(On Diff #97682)

1353 ↗

(On Diff #97682)

1600 ↗

(On Diff #97682)

1695 ↗

(On Diff #97682)

1737 ↗

(On Diff #97682)

2792 ↗

(On Diff #94688)

Still needs number agreement.

[bcr]

Alright, I incorporated these last feedback items. I'm going to commit this shortly.
Thanks to all reviewers, your feedback and suggestions helped a lot in improving the text!