Unify manpage makefiles, move pages to better sexions, revisit some

[nabijaczleweli]

Motivation and Context

#12149

Description

On top of #12169 for now, that move, and some pages I revisited having the benefit of hind-sight, having rewritten every manpage now

One thing that is potentially controversial here is that I replaced the .Os -> .Os Linux with .Os OpenZFS – the prevailing style is to either leave this blank or set .Os to the organisational umbrella the page came out of (Debian/OpenSSL/&c.), which is OpenZFS in this case (and definitely not Linux).

How Has This Been Tested?

Looked at it? I trust that judicious use of git grep -i zpoolprops.8 and/or find man -type f -exec sed -i 's/Xr zpoolprops 8/Xr zpoolprops 7/' {} + with manual touch-ups where necessary got everything.

If you turn the OpenZFS back into Linux, the installed tree is identical before/after

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.

[nabijaczleweli]

What seems to be a common solution to the "BSD General Commands Manual" problem is to pre-render the pages with mandoc -Tman, which generates the right center heading (and corners) based on the sexion (and .Os), primarily because it uses a different mdoc macro package, but mandoc is optional, so

[nabijaczleweli]

Rebased

[rlaager]

I gave this a really quick skim. I don't see anything wrong textually at first glance.

I agree with the assessment about OpenZFS as the section. I also agree with the solution of changing it at build-time for Linux, as this is friendlier to BSD as noted.

I think I disagree with the "Move properties, parameters, events, and concepts to section 7" commit. I think it's fine for zfsprops and zfsconcepts to be in either 8 (System administration commands and daemons) or 5 (File formats and conventions), but I don't think 7 (Miscellaneous) is appropriate for those or the others that are in 5 now. I got the section names from: https://en.wikipedia.org/wiki/Man_page#Manual_sections

I'm happy to approve this if: that commit is dropped, that commit is moved to a new PR, someone convinces me section 7 is appropriate, or @behlendorf or @ahrens makes an executive decisions that section 7 will be used.

[nabijaczleweli]

The .7 migration is taken from #12149, but you'll be hard-pressed to find any explicit reasoning there. I don't feel too strongly about moving (all of) these to .7, but these have been bugging me for a while too, so I'd like to arrive at some good consensus of where to put them.

These pages moved to .7:

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

According to FreeBSD, the sexions are as such:

1. FreeBSD General Commands Manual
2. FreeBSD System Calls Manual
3. FreeBSD Library Functions Manual
4. FreeBSD Kernel Interfaces Manual
5. FreeBSD File Formats Manual
6. FreeBSD Games Manual
7. FreeBSD Miscellaneous Information Manual
8. FreeBSD System Manager's Manual
9. FreeBSD Kernel Developer's Manual

And man-db:

1. Executable programs or shell commands
2. System calls (functions provided by the kernel)
3. Library calls (functions within program libraries)
4. Special files (usually found in /dev)
5. File formats and conventions eg /etc/passwd
6. Games
7. Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
8. System administration commands (usually only for root)
9. Kernel routines [Non standard]

Straight off the bat: none of these pages are programs or commands (indeed, zfs*.8 and zpool*.8 are leftovers from the unified zfs.8 and zpool.8 pages, aren't they?), so it's not 1. Likewise for 2, 3, and 6.
9 is, indeed, non-standard. It existed for a short while in Linux man-pages and described like 20 internal kernel interfaces in an incredibly obtuse way, or just noted the name and type with a "fill me out later pls". man-pages 1.2 (1993) describes it as "Section 9 = internal kernel routines (for kernel hackers)" and has 13 files in man9/. Unused for the past 20 years at least.
FreeBSD uses it for a similar purpose, though much more verbosely (and usefully, I assume, even if intro(9) says "prototypes: yes please" lol) – 2388 files, most describing some sort of internal kernel interface, which these are not.

This leaves 4, 5, 7, and 8.

According to FreeBSD's intro(4):

This section contains information related to devices, device drivers and miscellaneous hardware.

then follow The device abstraction, Accessing Devices, and Drivers without device nodes subsexions.

FreeBSD stores what seem to be surprisingly useful descriptions of most kernel drivers and their ioctl interfaces.

According to Linux man-pages' intro(4):

Section 4 of the manual describes special files (devices).

FILES
/dev/* — device files

It also has 40 files in it (9 of which aliases, 2 to ioctls in .2): laconic descriptions of /dev/{zero,full,null,ttyS,tty} (ttyS(4), in particular, says

       They are typically created by:

           mknod -m 660 /dev/ttyS0 c 4 64 # base address 0x3f8
           mknod -m 660 /dev/ttyS1 c 4 65 # base address 0x2f8
           mknod -m 660 /dev/ttyS2 c 4 66 # base address 0x3e8
           mknod -m 660 /dev/ttyS3 c 4 67 # base address 0x2e8
           chown root:tty /dev/ttyS[0-3]

lol), drivers removed in 2.6.35 (wavelan(4)), potentially-useful descriptions of some other drivers from 4.9 (smartpqi(4), but just give it time), and some ioctl interfaces (sd(4), st(4), "The information returned in the parameter is the disk geometry of the drive as understood by DOS!").

There's an argument to be made for {spl,zfs}-module-parameters.4. It's a valid interpretation of what sexion 4 means. Would it be my go-to before? Not really, but then I don't use FreeBSD enough to have a high opinion of sexion 4. There's something to be said about zfs-events.4.

According to FreeBSD's intro(5):

This section contains information about file formats.

FILES
/etc location of most system configuration files

According to Linux man-pages' intro(5):

Section 5 of the manual describes various file formats, as well as the corresponding C structures, if any.

In addition, this section contains a number of pages that document various filesystems.

Indeed! These are in agreement.

.5 consists entirely of file formats. Exclusively.
I expected fs(5) to be a description of The Filesystem, but it's a really arduous listing of the UFS superblocks and what they mean.
There's cd9660(5) and msdosfs(5) as a "here's a filesystem, turn on this config option, mount like this, fstab like this" (indeed, the actual content of these pages is in mount_msdosfs(8)). It's really not remotely what any pages in question are, either.
Linux man-pages ships ext4(5), which describes some (well, a lot of) mount options, as well. You'd be hard-pressed to put any pages in this category, either.

According to FreeBSD's intro(8):

This section contains information related to system operation and maintenance.

It describes commands used to create new file systems (newfs(8)), verify the integrity of the file systems (fsck(8)), control disk usage (edquota(8)), maintain system backups (dump(8)), and recover files when disks die an untimely death (restore(8)). Network related services like inetd(8) and ftpd(8) are also described.

It also says

A number of pages in this section describe general system management topics.

But

For example, the boot(8) manual page describes the system bootstrapping procedures, and the diskless(8) manual page describes how to boot a system over a network. The crash(8) manual page should be consulted to understand how to interpret system crash dumps.

These are rare, and scrolling through the listing I've found one other non-command page (YP(8)/NIS(8), "yp – description of the YP/NIS system", with improved defaults and administrtor's notes. it also references SunOS 4.x (and that's the thing that dates it least), wasn't touched since 2011, and I can't really stop asking myself why it's in .8).

According to Linux man-pages' intro(8):

Section 8 of the manual describes commands which either can be or are used only by the superuser, like system-administration commands, daemons, and hardware-related commands.

As with the commands described in Section 1, the commands described in this section [...]

Obviously much stricter, and I haven't noted a single page (well, beside the ones in question :Р) on my system that isn't a daemon or an administrative command.

It goes without saying that these pages have no place in .8.

According to FreeBSD's intro(7):

This section contains miscellaneous documentation.

ffs(7) commonly used filesystem in FreeBSD
stats(7) statistics utilities available in FreeBSD
tuning(7) general advice on tuning FreeBSD

According to Linux man-pages' intro(7):

intro – introduction to overview and miscellany section

Section 7 of the manual provides overviews on various topics, and describes conventions and protocols, character set standards, the standard filesystem layout, and miscellaneous other things.

"The rest." Well, zfsconcepts.7 and zpoolconcepts.7 make explicit sense here, considering they're, well, overviews.

Considering all of this, I propose the following filing, in descending order of preference:

• zpool-features.[754]
• spl-module-parameters.[47]
• zfs-module-parameters.[47]
• zfs-events.[47]
• zfsconcepts.7
• zfsprops.[75]
• zpoolconcepts.7
• zpoolprops.[75]

Thoughts?

[rlaager]

zfs*.8 and zpool*.8 are leftovers from the unified zfs.8 and zpool.8 pages, aren't they?

The convention on Linux is that man pages for stuff in {/usr}/bin goes in section 1 and man pages for commands in {/usr}/sbin go in section 8. So zfs-* and zpool-* should be in section 8 at the moment. Though one can make an argument that zfs allow means they should be in /usr/bin and section 1, but that's probably out-of-scope for this PR.

I can see the case for section 4 for module parameters, especially on FreeBSD.

I think you've made a fairly compelling case for section 7. I'll approve this and we'll see what other people think.

[behlendorf]

Section 4 seems like the right place to put the module options and event descriptions to me. Even though virtually all of the Linux modules don't bother to document their kernel parameters I did find one which does. The md(4) driver man page contains both a "KERNEL PARAMETERS" and "FILES" (proc files) sections which documents all of its interfaces. This strikes me as a pretty nice way to handle this, and it provides at least some precedent.

While we're at it we could also rename zfs-module-parameters.8 -> zfs.4 and zpl-module-parameters.8 -> spl.4 to be consistent with the other section 4 man pages. The zfs.4 rename would also give us a location to eventually document the public /dev/zfs ioctl() interface if we were so inclined.

I think putting everything else listed in this PR in section 7 would make good sense.

[debdrup]

Considering all of this, I propose the following filing, in descending order of preference:

* zpool-features.[754]

* spl-module-parameters.[47]

* zfs-module-parameters.[47]

* zfs-events.[47]

* zfsconcepts.7

* zfsprops.[75]

* zpoolconcepts.7

* zpoolprops.[75]

Thoughts?

While section 4 for does have an exception for pseudo devices like /dev/mem, it seems to me that that's still addressing a distinct bit of physical hardware.
In this respect, the SPL and ZFS module parameter manual pages do seem to cover a distinct bit of hardware, and in addition also describes values that are to be handled by the loader, which is also true for something like em(4), so I think that makes sense.

The zfs-events manual page, having spent a bit more time with it, seems to describe a way to interface with the zfs in the kernel, so would it make more sense to put it in section 9? Otherwise, I really don't think it belongs in section 4 and the only other place for it seems to be section 7.

Both FreeBSD and Linux seems pretty explicit that only vdev_id.conf belongs in section 5.

While we're at it we could also rename zfs-module-parameters.8 -> zfs.4 and zpl-module-parameters.8 -> spl.4 to be consistent with the other section 4 man pages. The zfs.4 rename would also give us a location to eventually document the public /dev/zfs ioctl() interface if we were so inclined.

This makes a lot of sense to me, and as it happens it, there aren't any conflicts for zfs.4 and spl.4 in either FreeBSD or FreeBSD Ports (I checked using ports-mgmt/pkg-provides).
It also makes it a lot easier to remember. :)

[nabijaczleweli]

Section 4 is for kernel-userspace interfaces – for the most part this means files under /dev, especially on berkeley derivatives, and that for the most part means physical devices because a modern kernel is 90% drivers by weight, but it describes kernel modules (and their parameters, the vast majority of .4 in FreeBSD has a LOADER TUNABLES sexion) and interfaces in general, so it's not that scandalous.
Stripping -module-parameters is a stroke of genius.

How's this look?

before	after
zpool-features.5	zpool-features.7
spl-module-parameters.5	spl.4
zfs-module-parameters.5	zfs.4
zfs-events.5	zfs-events.4
zfsconcepts.8	zfsconcepts.7
zfsprops.8	zfsprops.7
zpoolconcepts.8	zpoolconcepts.7
zpoolprops.8	zpoolprops.7

[ghost]

zfs-events seems to fit better in section 7. It documents the event information one obtains by the zpool events command.

[behlendorf]

Regarding zfs-events I think a reasonable case could be made for either section 4 or 7. However, perhaps a better idea is to merge the content of the zfs-events.5 man page in to the zpool-events.8 man page. We originally created a dedicated zfs-events page for this since the zpool.8 man page hadn't been split and we didn't want to make it even larger. But since that's no longer a problem it would be nice to have all this information in one place and easy for users to find. Plus it gets rid of the zfs-events / zpool-events confusion. We could tackle the merge in another PR and just move it for now in this one.

Everything else looks good to me.

[nabijaczleweli]

Sure, makes sense; updated as follows:

before	after
zpool-features.5	zpool-features.7
spl-module-parameters.5	spl.4
zfs-module-parameters.5	zfs.4
zfs-events.5	(inside zpool-events.8)
zfsconcepts.8	zfsconcepts.7
zfsprops.8	zfsprops.7
zpoolconcepts.8	zpoolconcepts.7
zpoolprops.8	zpoolprops.7

[behlendorf]

Thanks for updating this. I skimmed through all the updated pages locally and they looked good. I also verified the updated to me, I also verified the new install-data-hook is working correctly on Linux. So my only feedback is the suggested tweak to zpool-events.8.

[behlendorf]

Closing. Merged as:

4b7ed6a zgenhostid.8 revisit
1b37cc1 Consistentify miscellaneous style on remaining manpages
2badb34 Move properties, parameters, events, and concepts around manual secti>
b0f3e8a man: use one Makefile, use OpenZFS for .Os