Re: [gentoo-dev] QA PG 0305 (manpages must always be installed) discussion

[Yuan Liao (Leo3418)]

On Thu, Jan 19, 2023 at 01:25:19PM +0200, Cedric Sodhi wrote:
> I would like to continue https://bugs.gentoo.org/890589 here and also increase the audience. The original policy was voted upon by 6 seniors and approved with no documented opposition or discussion. I think it's possible that it went under the radar a bit. It says:
>
> > Packages must not disable installing manpages via USE flags (e.g. USE=man or USE=doc). If upstream does not ship prebuilt manpages and building them requires additional dependencies, the maintainer should build them and ship along with the package.
>
> https://projects.gentoo.org/qa/policy-guide/installed-files.html#pg0305
>
> While I acknowledge Gentoo's responsibility to steer things towards the better, I am also a vivid defender of freedom-of-choice (part of the reason why I use Gentoo) and am sceptical of "protect the user from their own decisions" kind-of approaches.

To me, this is an issue about where Gentoo should be on the spectrum
between a package's documentation completeness and flexibility.  Both
ends are justifiable, though I second that they may conflict with each
other.

I know two other distributions that are perfect examples on both ends of
the spectrum:
- Fedora strives for man page completeness.  If a package comes with man
  pages, they should definitely be installed.  If not, package
  maintainers are encouraged to bring them into existence by reaching
  out to the package upstream or even using 'help2man'.  [1]
- OpenWrt, a distribution mainly for Wi-Fi routers, does not ship man
  pages with its packages.  In fact, OpenWrt does not install man-db at
  all by default.

Fedora has been mainly targeting full-fledged desktop/laptop computers
and servers, where storage space is not constrained, and users might
actively consult documentation as they use and learn about their system
every day.  (Certainly, Fedora is expanding its scope to IoT, embedded
systems, and containers, but its Workstation and Server editions carry
the most heritage.)

OpenWrt, on the other hand, specifically targets embedded systems (i.e.
Wi-Fi routers) where every byte of storage space counts.  Also, OpenWrt
users are not expected to read manual pages on their Wi-Fi router; they
typically have another device that they can use to read documentation.

Which side should Gentoo lean toward?  I would say the Fedora side, but
I am not confident to rule out any possible use case of Gentoo on
smaller systems like embedded systems either.  Some users might be
running Gentoo on resource-constrained machines.

Gentoo also has one special thing rarely seen on other distributions: in
general, users are responsible for compiling distribution packages on
their own.  As a result, unique challenges for Gentoo exist for adopting
policies akin to Fedora's man page guidelines.  On binary distributions,
dependencies required to build man pages might not hit end users at all
-- they would translate to BDEPEND on Gentoo and thus are only needed on
the build system.  On Gentoo, this has a more significant impact on end
users, and those on a resource-constrained system are affected the most.

> In this case, the expectation to compile manpages does not come free of cost and protects noone. By the above formulation, the cost "should" not come in the form of additional (heavy! dev-python/sphinx and deps are 75M) dependencies, but instead in the form of additional work for the maintainer. One way to annoy less-enthusiastic (proxy-) maintainers, in my opinion.

This is exactly an example of the point in my previous paragraph.
However, I am not sure what "maintainer" exactly refers to here.
- If it means a maintainer of a package that has extra dependencies for
  building man pages per se, then I think the maintainer should still
  refrain from being lazy and skipping invocation of the man page build
  in the ebuilds they write.  The extra work to support building man
  pages benefits users who need them.
- If it means a maintainer of another package that depends on a package
  of this type (e.g. someone who maintains a package that depends on
  app-text/zathura), then I do acknowledge that it could be a burden for
  some maintainers -- they would have to install extra transitive
  dependencies to continue maintaining their package.

> On the other hand - and I pick up the discussion from the tracker here - there is no documented benefit. We actively deny the user a choice which they were supposed to have from Upstream and gain nothing practical from it.
>
> In response to Comment #12, we could keep the spirit of "ensure documentation [if it exists in the first place]" and say "should install manpages", which would at least leave the maintainer the chance for an easy way out, if it comes with dependencies. I'm not a fan of this approach either, because it still denies the user their rightful choice, but at least it wouldn't negatively impact either the maintainer or the user.

Comment #12 proposes FEATURES="noman", and I think one might suggest
INSTALL_MASK too.  But as per my understanding of make.conf(5) (oops,
one example of man pages' usefulness), these do not prevent dependencies
for building man pages from being pulled, meaning that they are probably
non-solutions to additional dependencies being required.

I hope my proposal is not too crazy: we could enable USE="doc man" in
the base profile so man pages come by default, and IUSE="{doc,man}" are
still permitted for packages so users still have a choice to disable
them if they want to reduce the system's footprint.

Leo3418

[1]:
https://docs.fedoraproject.org/en-US/packaging-guidelines/#_manpages