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
Sectional zpool manpage #9564
Sectional zpool manpage #9564
Conversation
Moved subcommand topics into individual manpages. Reordered and grouped the list of subcommands by topic. Moved concepts overview to `zpoolconcepts.8` and long list of available pool properties to `zpoolprops.8`. Internal cross-references copied from `zpool.8` needed to be converted to `.Xr` external references to new subcommand manual pages. Added new manpages to Makefile.am Signed-off-by: Ross Williams <ross@ross-williams.net>
5a03ef8
to
0596490
Compare
Codecov Report
@@ Coverage Diff @@
## master #9564 +/- ##
==========================================
- Coverage 79.35% 79.05% -0.31%
==========================================
Files 418 418
Lines 123686 123686
==========================================
- Hits 98157 97778 -379
- Misses 25529 25908 +379
Continue to review full report at Codecov.
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Went through a big portion of it. See nothing to obviously wrong with this.
I think you can check off:
-
Code cleanup (non-breaking change which makes code smaller or more readable)
-
My code follows the ZFS on Linux code style requirements.
-
All new and existing tests passed.
Divided zpool subcommand manual pages need their own SEE ALSO sections. Also modified fsck.zfs.8 to point directly to zfs-scrub.8 and zed.8.in to include a direct reference to zfs-events.8
|
Now that I've added |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The updated man pages look good to me as I read through them. I didn't spot any major issues or formatting problems. And I completely agree that once we get these big structural changes merged it'll be easier to tackle the other suggested improvements.
Autotrim tacked onto the end of a list. Now it is in alphabetical order.
|
@ahrens, could you sign off here also? |
h/t @ahrens Description was too specific to command syntax. Overview clarifies reason for attaching or detaching a device.
h/t @ahrens Make description simpler; don't refer to subcommand arguments.
h/t @ahrens, his wording. Say what split actually does and why you'd want to do it.
Simplify zpool.8 wording of zpool-upgrade(8) description.
Detail what zpool-import(8) actually does. h/t @ahrens
Motivation and Context
As more subcommands have been added to
zpool, the manpage has gotten to long to be easy to scroll through, especially on a text console. This PR is the completion of work started at the 2019 ZFS Dev Summit Hackathon. This PR is a companion to #9559.Description
Most subcommands got their own manpages (e.g. create).
Some related commands grouped into a single manpage and
symlinks created (e.g. set & get). I did
this when topics were either too short to warrant their
own file or so interrelated that a user would want to
refer between commands in the same file.
Corrected
.Sxinternal references to.Xrcross refslots of
.Sxreferences from when text was all inzpool.8needed to be changed to
.Xr zpool-$SUBCOMMAND 8cross references.Divided subcommand list in
zpool(8)into sectionsDivided into related functionality. This required writing new descriptions
for some commands.
How Has This Been Tested?
All altered manpages have been checked with
mandoc -Tlintand return no warnings or errors.Types of changes
Checklist:
Signed-off-by.