search

openzfs / zfs

OpenZFS on Linux and FreeBSD
https://openzfs.github.io/openzfs-docs
Other
10.55k stars 1.74k forks source link

Add man pages for zfs and zpool including all of their respective separate sub-command man pages #11264

Open omnihackorg opened 3 years ago

omnihackorg commented 3 years ago

Hi, I'm sorry I'm late to the party. I disagree with PR #9559 and #9564 but understand that it is most likely too late to change any of that now.

Describe the feature would like to see added to OpenZFS

Create two new man pages, zfsall(8) and zpoolall(8) or similar, concatenating their respective separate sub-command man pages to closely resemble the previous zfs(8) and zpool(8) pages.

Reference them in a clear way in the SEE ALSO section of the main man pages (perhaps make that whole section more easy to read, now that it will make your eyes defocus, but that probably deserve an issue of its own).

How will this feature improve OpenZFS?

I just loved the old full man pages and how easy it was to find what you were looking for. I held them in high regard as something for man pages, of other projects with sub commands to their programs, to aspire to. This would be a way to retain that without undoing what was done.

I don't think I'm the only grumpy SysAdm who didn't notice that the plans were on display and you don't deserve what may spill out of some of us. Adding these manuals might mitigate future backlash over #9559 and #9564.

Additional context

The idea to suggest looking at how the zsh project has done this with zshall(1) is not mine so I cannot take credit for it. If you want to see what the zsh project does this might be a good place to start.

I do recognize the effort that has been put into splitting these into several separate man pages, as well as the related work involved, even though I'm an opponent of the changes. Writing and improving on documentation in general is too rare as is and I support any such effort.

Besides all the people who are or will be happy about the split man pages, an idea that I'd see as a positive outcome of the separate pages would be to use them for additional --help of each sub command (perhaps a lone -h shouldn't throw an error but just show usage information, but that too deserve an issue of its own).

omnihackorg commented 3 years ago

This should've been labeled Documentation but I can't find how to change that.