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

Sectional zpool manpage #9564

Merged
merged 8 commits into from Nov 13, 2019
Merged

Conversation

overhacked
Copy link
Contributor

@overhacked overhacked commented Nov 8, 2019

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 .Sx internal references to .Xr cross refs

lots of .Sx references from when text was all in zpool.8
needed to be changed to .Xr zpool-$SUBCOMMAND 8 cross references.

Divided subcommand list in zpool(8) into sections

Divided into related functionality. This required writing new descriptions
for some commands.

How Has This Been Tested?

All altered manpages have been checked with mandoc -Tlint and return no warnings or errors.

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)
  • Documentation (a change to man pages or other documentation)

Checklist:

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>
@behlendorf behlendorf added Status: Code Review Needed Ready for review and testing Type: Documentation Indicates a requested change to the documentation labels Nov 9, 2019
@codecov
Copy link

codecov bot commented Nov 9, 2019

Codecov Report

Merging #9564 into master will decrease coverage by 0.3%.
The diff coverage is n/a.

Impacted file tree graph

@@            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
Flag Coverage Δ
#kernel 79.71% <ø> (-0.08%) ⬇️
#user 66.83% <ø> (-0.69%) ⬇️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 734de7c...916a8b0. Read the comment docs.

Copy link
Contributor

@Ornias1993 Ornias1993 left a 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.

man/man8/zpool-add.8 Show resolved Hide resolved
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
@overhacked
Copy link
Contributor Author

Now that I've added SEE ALSO sections to the new subcommand manpages, I think that this PR could be ready for approval. If we can get a few more readers to make sure I haven't made any boneheaded errors, that'd be great. I'll mention that in the Slack channel.

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.

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.

man/man8/zpoolprops.8 Outdated Show resolved Hide resolved
Autotrim tacked onto the end of a list. Now it is in
alphabetical order.
@overhacked
Copy link
Contributor Author

@ahrens, could you sign off here also?

@behlendorf behlendorf added Status: Accepted Ready to integrate (reviewed, tested) and removed Status: Code Review Needed Ready for review and testing labels Nov 12, 2019
man/man8/zpool.8 Outdated Show resolved Hide resolved
man/man8/zpool.8 Outdated Show resolved Hide resolved
man/man8/zpool.8 Outdated Show resolved Hide resolved
man/man8/zpool.8 Outdated Show resolved Hide resolved
man/man8/zpool.8 Outdated Show resolved Hide resolved
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
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
No open projects
OpenZFS 2.0
  
New OpenZFS 2.0 Features (0.8->2.0)
Development

Successfully merging this pull request may close these issues.

None yet

4 participants