Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Minor improvements to zpoolconcepts.7 #14726

Merged
merged 2 commits into from
Apr 13, 2023
Merged

Conversation

dodexahedron
Copy link
Contributor

Mostly grammatical consistency/fixes for zpoolconcepts.7, and some minor clarification.

Motivation and Context

I noticed incorrect use of "effects" when looking at the man page and decided to include some other minor improvements to grammar, clarity, and consistency while I was fixing that.

Description

  • Fixed a typo (effects -> affects)
  • Re-worded raidz description to make it clearer that it is not quite the same as RAID5, though similar
  • Clarified that data is not necessarily written in a static stripe width
  • Minor grammar consistency improvement
  • Noted that "volumes" means zvols
  • Fixed a couple of split infinitives
  • "we" -> ZFS

How Has This Been Tested?

Documentation changes only. No code changes.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Performance enhancement (non-breaking change which improves efficiency)
  • Code cleanup (non-breaking change which makes code smaller or more readable)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Library ABI change (libzfs, libzfs_core, libnvpair, libuutil and libzfsbootenv)
  • Documentation (a change to man pages or other documentation)

Checklist:

  • My code follows the OpenZFS code style requirements.
  • I have updated the documentation accordingly.
  • I have read the contributing document.
  • I have added tests to cover my changes.
  • I have run the ZFS Test Suite with this change applied.
  • All commit messages are properly formatted and contain [Signed-off-by]

 * Fixed one typo (effects -> affects)
 * Re-worded raidz description to make it clearer that it is not quite the same as RAID5, though similar
 * Clarified that data is not necessarily written in a static stripe width
 * Minor grammar consistency improvement
 * Noted that "volumes" means zvols
 * Fixed a couple of split infinitives
 * Clarified that hot spares come from the same pool they were assigned to
 * "we" -> ZFS

Signed-off-by: Brandon Thetford <[email protected]>
@dodexahedron
Copy link
Contributor Author

dodexahedron commented Apr 7, 2023

Minor documentation update to the zpoolconcepts.7 man page.
The only "important" part of it is fixing the improper use of "effects," which should be "affects," in this case.
Other changes made were either to be more consistent (such as insertion of commas to more closely match the style of the rest of the document), or to fix some awkward grammatical constructs, such as odd verb conjugations, and minor clarification on a couple of points.

There was also an instance of "can not" that I changed to "cannot," as those two terms have subtly different meaning, and "cannot" was the intended meaning. "Can not" can be interpreted to mean that something is possible to not be done. "Cannot" unambiguously means that it is impossible to do that thing.

Fixed warnings thrown by mandoc, and removed unnecessary wordiness in one fixed line.

Signed-off-by: Brandon Thetford <[email protected]>
@ceedriic
Copy link
Contributor

ceedriic commented Apr 8, 2023

The only "important" part of it is fixing the improper use of "effects," which should be "affects," in this case.

Why improper and important? Not a native speaker, but looking at Oxford dictionary, it seems "effects", used as a verb, is perfectly fine here.

@dodexahedron
Copy link
Contributor Author

"Effects" actually makes little to no sense in that sentence, as used.

"Effects," as a verb, means "causes" or "creates." The intent of that sentence is to say that it alters the capacity and IOPS. "Affects" is the appropriate word for that usage.

Copy link
Contributor

@behlendorf behlendorf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for making a pass over this. Generally looks good to me aside from my one DRAID comment.

man/man7/zpoolconcepts.7 Show resolved Hide resolved
@behlendorf behlendorf added Type: Documentation Indicates a requested change to the documentation Status: Code Review Needed Ready for review and testing labels Apr 10, 2023
@behlendorf behlendorf added Status: Accepted Ready to integrate (reviewed, tested) and removed Status: Code Review Needed Ready for review and testing labels Apr 12, 2023
@behlendorf behlendorf merged commit ac18dc7 into openzfs:master Apr 13, 2023
andrewc12 pushed a commit to andrewc12/openzfs that referenced this pull request Apr 30, 2023
 * Fixed one typo (effects -> affects)
 * Re-worded raidz description to make it clearer that it is not
   quite the same as RAID5, though similar
 * Clarified that data is not necessarily written in a static
   stripe width
 * Minor grammar consistency improvement
 * Noted that "volumes" means zvols
 * Fixed a couple of split infinitives
 * Clarified that hot spares come from the same pool they were
   assigned to
* "we" -> ZFS
* Fixed warnings thrown by mandoc, and removed unnecessary
  wordiness in one fixed line.

Reviewed-by: Brian Behlendorf <[email protected]>
Signed-off-by: Brandon Thetford <[email protected]>
Closes openzfs#14726
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Status: Accepted Ready to integrate (reviewed, tested) Type: Documentation Indicates a requested change to the documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants