pkg_alternatives vs manual pages

[Jonathan Perkin <jperkin%joyent.com@localhost>]

Today I learned that having a manual page in an ALTERNATIVES file is
not supported, and turns out to be actively harmful, yet a bunch of
packages have them:

  $ git grep -l /man -- '*/ALTERN*'
  databases/py-peewee/ALTERNATIVES
  devel/py-bugzilla/ALTERNATIVES
  devel/py-ipython/ALTERNATIVES
  devel/py-logilab-common/ALTERNATIVES
  devel/py-pylint/ALTERNATIVES
  fonts/py-fonttools/ALTERNATIVES
  graphics/py-blockdiag/ALTERNATIVES
  graphics/py-qrcode/ALTERNATIVES
  graphics/py-seqdiag/ALTERNATIVES
  misc/py-tqdm/ALTERNATIVES
  www/py-swiftclient/ALTERNATIVES

The problem is pkg_alternatives explicitly doesn't support anything
other than "bin|libexec|sbin", and will error out if that does not
match.  Unfortunately this means that "pkg_alternatives rebuild" will
remove all the wrappers from the system and then leave it in that
state, as one of my users found out.

There appears to be some kind of automated manual page handling, but
it only supports situations where there is an exact match between a
command handled in the ALTERNATIVES file and its manual page, which
doesn't help the package that triggered this issue where that is not
the case:

  $ cat databases/py-peewee/ALTERNATIVES 
  bin/pwiz @PREFIX@/bin/pwiz-@PYVERSSUFFIX@
  @PKGMANDIR@/man1/peewee.1 @PREFIX@/@PKGMANDIR@/man1/peewee-@PYVERSSUFFIX@.1

Roland, could we get a pkglint error for this, so at least we aren't
shipping actively dangerous ALTERNATIVES files?

Is anyone interested in adding support for ad-hoc manual pages to
pkg_alternatives, or is this just something that is outside of the
intended design?

Thanks,

-- 
Jonathan Perkin  -  Joyent, Inc.  -  www.joyent.com