Switching from our own generated man page to an upstream-supplied one sounds good on paper, but this new man page stinks! Things I've noticed so far: --acls isn't documented --xattr isn't documented --keep-directory-symlink isn't documented These are all things important for gentoo day to day use of tar. It's almost like they're trying to get 'man' to look bad so we all start using info =) IMHO it would be best to switch back to the old man page, but you guys know best. Thanks!
we're not switching back ... it too rotted and was a pain to maintain
No worries, I'm not even sure if there is anything to be done here, besides prodding upstream to update their copy. And on my end, learning to use tar --help instead of man tar. I won't be offended if you just want to close this as UPSTREAM.
Maybe it makes sense to add small patch to ebuild which will add _static_ NOTICE about this on top of man page? Such a notice doesn't need any maintenance, we can leave it there forever (or until someone will open bug to let us know man page now in sync with --help and notice can be removed). I've just lost a lot of time because of disappearing xattrs on hardened system after copying filesystem using tar - and I've checked man page first, looking for an extra option needed to include xattrs… found nothing and was sure xattrs will be included by default if it's not configurable.
The man page now seems to be much more up to date and in line with the info page