Updates to mpr.4 man page

[slm]

Summary

• Add 3216 and 3224 support.
• Add SSU, chain_alloc_fail, and spinup_wait_time information.
• Clear up some sentences.
• Correct some typos.

[ken]

Looks good.

[wblock]

share/man/man4/mpr.4

41 ↗

(On Diff #15608)

Please bump this.

48 ↗

(On Diff #15608)

This sentence mentions the kernel three times now.

"if not already in the kernel that you are using" can be assumed from context.

"the following" is almost always used incorrectly, usually "these" is better.

Avoid "you" and "your" (https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style.html#writing-style-tips)

So, I suggest:

To compile this driver into the kernel, place these lines in the kernel configuration file:

57 ↗

(On Diff #15608)

Simpler:

The driver can be loaded as a module at boot time by placing this line in

("Alternatively" and "if not already loaded" are not needed, if the module is already part of the kernel there is only a non-fatal warning.)

137 ↗

(On Diff #15608)

Please start new sentences on new lines.

139 ↗

(On Diff #15608)

"may" is for permission, "can" is for possibility. "via" still means "a route" to me, but I know that not everyone agrees.

Also, "can be seen" seems a little weird. The command is what shows them, but the value is actually stored in the variable, not shown.

The current number of free chain frames is stored in the

144 ↗

(On Diff #15608)

As above (but avoiding repeating "seen"):

The lowest number of free chain frames seen since boot is stored in the

150 ↗

(On Diff #15608)

As above:

is stored in the

153 ↗

(On Diff #15608)

Please start new sentences on new lines.
Also, s/if/whether/

161 ↗

(On Diff #15608)

s/is shown in/is stored in/

192 ↗

(On Diff #15608)

No comma needed here. It would not hurt to break that into two sentences, though:

SCSI command to SATA direct-access devices during shutdown.
This allows the

193 ↗

(On Diff #15608)

I would say "before powering down."

201 ↗

(On Diff #15608)

As above:
s/the following/these/

206 ↗

(On Diff #15608)

Avoid semicolons, the rutabaga of the punctuation world.

Send SSU to SSDs, but not to HDDs.
This is the default value.

213 ↗

(On Diff #15608)

As above:
s/the following/this/

221 ↗

(On Diff #15608)

s/are valid as/are valid/

223 ↗

(On Diff #15608)

This sentence is repetitive, using "failed" for several things. Also "may" versus "can". How about:

SATA disks that take several seconds to spin up and fail the SATA Identify command might not be discovered by the driver.

225 ↗

(On Diff #15608)

"The following" is usually best avoided. Also, "spinup" versus "spin up".

This problem can sometimes be overcome by increasing the value of the spinup wait time in
.Xr loader.conf 5
with the
.Bd -literal -offset indent
hw.mpr.spinup_wait_time
​.Ed
​.Pp
tunable.
The value is the number of seconds to wait for SATA devices to spin up when
the device fails the initial SATA identify command.

236 ↗

(On Diff #15608)

Try to avoid if/then sentences with a pause (comma). Better to have declarative sentences.
Also, no "the following".

Spinup wait times can be set for specific adapters in
.Xr loader.conf 5
with the
​.Bd -literal -offset indent
​dev.mpr.X.spinup_wait_time
​.Ed
​.Pp
tunable.
X represents the adapter number, and the tunable value is the number of seconds
to wait for SATA devices to spin up when they fail the initial SATA Identify command.

[slm]

Wow. That's a lot of stuff. Who knew there could be so much wrong in such a little document :) I appreciate the feedback. I'll make the changes as suggested and put up a patch within a couple of days.

[slm]

Updated with Warren's initial comments.

[wblock]

One small note, but otherwise looks great! Thank you for your patience!

mpr.4

185 ↗

(On Diff #15744)

Don't use an apostrophe for a plural, just "IDs".

[slm]

mpr.4

185 ↗

(On Diff #15744)

I'll remove before committing. Thanks Warren.