Skip to content

Multiple man-pages: Move to appropriate section#12149

Closed
debdrup wants to merge 8 commits intoopenzfs:masterfrom
debdrup:master
Closed

Multiple man-pages: Move to appropriate section#12149
debdrup wants to merge 8 commits intoopenzfs:masterfrom
debdrup:master

Conversation

@debdrup
Copy link
Copy Markdown
Contributor

@debdrup debdrup commented May 28, 2021

Motivation and Context

These manual pages belong in section 7 of the manual pages as that
section, according to intro(7) on both FreeBSD and Linux, is meant to
contain miscellaneous information pages whereas section 5 describes file
formats (a good example being vdev_id.conf in zfs/man/man5/).

While here, an errant space has also been removed.

Signed-off-by: Daniel Ebdrup Jensen [email protected]

How Has This Been Tested?

Mandoc has been run, but the change doesn't change a whole lot of roff formatting.

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:

@debdrup
Multiple man-pages: Move to appropriate section
5f037e2 
These manual pages belong in section 7 of the manual pages as that
section, according to intro(7) on both FreeBSD and Linux, is meant to
contain miscellaneous information pages whereas section 5 describes file
formats (a good example being vdev_id.conf in zfs/man/man5/).

While here, an errant space has also been removed.

Signed-off-by:	Daniel Ebdrup Jensen	<[email protected]>
jrtc27
jrtc27 reviewed May 28, 2021
View reviewed changes
ghost
ghost reviewed May 28, 2021
View reviewed changes
ghost
ghost reviewed May 28, 2021
View reviewed changes
@ghost
Copy link
Copy Markdown

ghost commented May 28, 2021

I spotted a few missed cross references to the moved pages just in the diff context, so let's make sure to grep and get all of them.

@ghost ghost added Type: Documentation Indicates a requested change to the documentation Status: Code Review Needed Ready for review and testing labels May 28, 2021
@debdrup
Copy link
Copy Markdown
Contributor Author

debdrup commented May 28, 2021 •
edited
Loading

I spotted a few missed cross references to the moved pages just in the diff context, so let's make sure to grep and get all of them.

You're right, I missed quite a few.
Apparently my own grep wasn't thorough enough.
I'll fix 'em. :)

While here, I also noticed that I forgot some other things.

@ghost
Copy link
Copy Markdown

ghost commented May 28, 2021

Thanks. There are still 3 files renamed without changes, so they still have the old section number in them:

  • spl-module-parameters
  • zfs-module-parameters
  • zfs-events

@debdrup
Copy link
Copy Markdown
Contributor Author

debdrup commented May 28, 2021

Thanks. There are still 3 files renamed without changes, so they still have the old section number in them:

* spl-module-parameters

* zfs-module-parameters

* zfs-events

Ah, good catch!

I have to admit that I wasn't aware of the .ST macro.
It doesn't seem reasonable to assume it has anything to do with .St as described here, nor is it mentioned in mdoc(7), nor roff(7), so I'm a bit confused about where it originates.

@ghost
Copy link
Copy Markdown

ghost commented May 28, 2021

FYI there are a few other batches of manpage changes open right now such as #12125 and #12129 which may conflict a bit, but should also make the manpages much cleaner WRT mandoc style.

@nabijaczleweli
Copy link
Copy Markdown
Contributor

nabijaczleweli commented May 29, 2021 •
edited
Loading

Yeah, can we hold off on this until after #12125 and #12129 please? I touch all but two manpages (and rewrite some in parts or in full) in those and it was already a tremendous effort (and I don't say that lightly), and just rebasing that onto the new ztest.1 was non-obvious.

If you like, if you compile the list of renames from here I can run them myself after these land (which will be likely simpler to get right since most manpages properly .Xr now) and submit that?

@debdrup
Copy link
Copy Markdown
Contributor Author

debdrup commented May 29, 2021 •
edited
Loading

Yeah, can we hold off on this until after #12125 and #12129 please? I touch all but two manpages (and rewrite some in parts or in full) in those and it was already a tremendous effort (and I don't say that lightly), and just rebasing that onto the new ztest.1 was non-obvious.

Yeah, I can imagine, as that's quite a bit of work.

If you like, if you compile the list of renames from here I can run them myself after these land (which will be likely simpler to get right since most manpages properly .Xr now) and submit that?

Sure, I don't mind as long as it gets done, that's what I care about. :)

The files are:

  • zpool-features.5
  • spl-module-parameters.5
  • zfs-module-parameters.5
  • zfs-events.5
  • zfsconcepts.8
  • zfsprops.8
  • zpoolconcepts.8
  • zpoolprops.8

This can also be seen by looking the subtractions in man5/Makefile.am and man8/Makefile.am here.

Can I get a Co-authored-by: Daniel Ebdrup Jensen <debdrup at FreeBSD.org>?

@nabijaczleweli
Copy link
Copy Markdown
Contributor

nabijaczleweli commented May 29, 2021

Sure thing

nabijaczleweli added a commit to nabijaczleweli/zfs that referenced this pull request Jun 4, 2021
@nabijaczleweli @debdrup
Move properties, parameters, events, and concepts to section 7
a8954bc 
Signed-off-by: Ahelenia Ziemiańska <[email protected]>
Co-authored-by: Daniel Ebdrup Jensen <[email protected]>
Closes openzfs#12149
@nabijaczleweli nabijaczleweli mentioned this pull request Jun 4, 2021
Closed
13 tasks
nabijaczleweli added a commit to nabijaczleweli/zfs that referenced this pull request Jun 4, 2021
@nabijaczleweli @debdrup
Move properties, parameters, events, and concepts to section 7
2dd557a 
Signed-off-by: Ahelenia Ziemiańska <[email protected]>
Co-authored-by: Daniel Ebdrup Jensen <[email protected]>
Closes openzfs#12149
nabijaczleweli added a commit to nabijaczleweli/zfs that referenced this pull request Jun 4, 2021
@nabijaczleweli @debdrup
Move properties, parameters, events, and concepts to section 7
50197f9 
Signed-off-by: Ahelenia Ziemiańska <[email protected]>
Co-authored-by: Daniel Ebdrup Jensen <[email protected]>
Closes openzfs#12149
nabijaczleweli added a commit to nabijaczleweli/zfs that referenced this pull request Jun 7, 2021
@nabijaczleweli @debdrup
Move properties, parameters, events, and concepts to section 7
0de7f4c 
Signed-off-by: Ahelenia Ziemiańska <[email protected]>
Co-authored-by: Daniel Ebdrup Jensen <[email protected]>
Closes openzfs#12149
@behlendorf
Copy link
Copy Markdown
Contributor

behlendorf commented Jun 8, 2021

@debdrup it'd be great to get your thoughts on the right location for some of these man pages. @nabijaczleweli posted a nice detailed #12196 (comment) which goes over rationals for various locations.

nabijaczleweli added a commit to nabijaczleweli/zfs that referenced this pull request Jun 9, 2021
@nabijaczleweli @debdrup
Move properties, parameters, events, and concepts around manual sections
b44fe40 
The pages moved as follows:
  zpool-features.{5 => 7}
  spl{-module-parameters.5 => .4}
  zfs{-module-parameters.5 => .4}
  zfs-events.5 => into zpool-events.8
  zfsconcepts.{8 => 7}
  zfsprops.{8 => 7}
  zpoolconcepts.{8 => 7}
  zpoolprops.{8 => 7}

Signed-off-by: Ahelenia Ziemiańska <[email protected]>
Co-authored-by: Daniel Ebdrup Jensen <[email protected]>
Closes openzfs#12149
nabijaczleweli added a commit to nabijaczleweli/zfs that referenced this pull request Jun 9, 2021
@nabijaczleweli @debdrup
Move properties, parameters, events, and concepts around manual sections
5b0688c 
The pages moved as follows:
  zpool-features.{5 => 7}
  spl{-module-parameters.5 => .4}
  zfs{-module-parameters.5 => .4}
  zfs-events.5 => into zpool-events.8
  zfsconcepts.{8 => 7}
  zfsprops.{8 => 7}
  zpoolconcepts.{8 => 7}
  zpoolprops.{8 => 7}

Signed-off-by: Ahelenia Ziemiańska <[email protected]>
Co-authored-by: Daniel Ebdrup Jensen <[email protected]>
Closes openzfs#12149
nabijaczleweli added a commit to nabijaczleweli/zfs that referenced this pull request Jun 9, 2021
@nabijaczleweli @debdrup
Move properties, parameters, events, and concepts around manual sections
cbd67b1 
The pages moved as follows:
  zpool-features.{5 => 7}
  spl{-module-parameters.5 => .4}
  zfs{-module-parameters.5 => .4}
  zfs-events.5 => into zpool-events.8
  zfsconcepts.{8 => 7}
  zfsprops.{8 => 7}
  zpoolconcepts.{8 => 7}
  zpoolprops.{8 => 7}

Signed-off-by: Ahelenia Ziemiańska <[email protected]>
Co-authored-by: Daniel Ebdrup Jensen <[email protected]>
Closes openzfs#12149
@behlendorf behlendorf closed this in 2badb34 Jun 9, 2021
behlendorf pushed a commit to behlendorf/zfs that referenced this pull request Jun 10, 2021
@nabijaczleweli @debdrup @behlendorf
Move properties, parameters, events, and concepts around manual sections
2e93407 
The pages moved as follows:
  zpool-features.{5 => 7}
  spl{-module-parameters.5 => .4}
  zfs{-module-parameters.5 => .4}
  zfs-events.5 => into zpool-events.8
  zfsconcepts.{8 => 7}
  zfsprops.{8 => 7}
  zpoolconcepts.{8 => 7}
  zpoolprops.{8 => 7}

Reviewed-by: Richard Laager <[email protected]>
Reviewed-by: Brian Behlendorf <[email protected]>
Signed-off-by: Ahelenia Ziemiańska <[email protected]>
Co-authored-by: Daniel Ebdrup Jensen <[email protected]>
Closes openzfs#12149
Closes openzfs#12212
behlendorf pushed a commit to behlendorf/zfs that referenced this pull request Jun 10, 2021
@nabijaczleweli @debdrup @behlendorf
Move properties, parameters, events, and concepts around manual sections
a444efb 
The pages moved as follows:
  zpool-features.{5 => 7}
  spl{-module-parameters.5 => .4}
  zfs{-module-parameters.5 => .4}
  zfs-events.5 => into zpool-events.8
  zfsconcepts.{8 => 7}
  zfsprops.{8 => 7}
  zpoolconcepts.{8 => 7}
  zpoolprops.{8 => 7}

Reviewed-by: Richard Laager <[email protected]>
Reviewed-by: Brian Behlendorf <[email protected]>
Signed-off-by: Ahelenia Ziemiańska <[email protected]>
Co-authored-by: Daniel Ebdrup Jensen <[email protected]>
Closes openzfs#12149
Closes openzfs#12212
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

2 more reviewers

@jrtc27 jrtc27 jrtc27 left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

@tonynguien tonynguien

Labels

Status: Code Review Needed Ready for review and testing Type: Documentation Indicates a requested change to the documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@debdrup @nabijaczleweli @behlendorf @jrtc27 @tonynguien