Re: [gentoo-dev] [RFC] New QA policy: Packages must not disable installing manpages via USE flags

[Kent Fredric]

On Thu, 25 Jul 2019 00:10:49 -0400
desultory <desultory@g.o> wrote:

> The user-side effects pf the proposal in question, were it to become
> policy, would be that anyone seeking to not install what is presently
> optional documentation would either be:
> (1) wasting build time and space (and, depending on implementation,
> dependencies) on their build system (potentially  masking the files from
> being installed);
> (2) wasting the space in their installed image(s) (if they did not mask
> the files which would not currently be installed anyway); or
> (3) wasting their own time working around what the developers would be
> required by policy to implement by repackaging the software themselves
> to avoid the time and space drawbacks (though this would generally be
> expected to be a rather exceptional case, as it would be relatively
> extreme to avoid what would be a distfile and some file masking from the
> user side).

Those concerns as per current policy is unrelated to the
dependency-control-of-USE issue presented here.

Its already established not to use a USE flag to toggle building of man
pages if it doesn't require additional dependencies.

These are _man_ pages we're talking about, not general purpose
documentation.

End users who don't like man pages are encouraged to use the relevant
FEATURES to strip them from the installed image, or use INSTALL_MASK or
something. ( FEATURES=noman )

The GOAL here is to provide man pages in *all* circumstances, and, if
additional dependencies are required to build them, to ALWAYS install
them, or NEVER install them, and then, find a secondary way to obtain
man pages (prebuilt)

The Total Cost of man pages as pure files on the target system is tiny,
and has practically no risk with regards to complexity.

But the cost of *dependencies* has risk, and can inflate to complexity,
causing much more real problems for more users than a few kb of .1.bz2
files.

Hence, why we gate them with USE flags: Because it provides an out for
that complexity ( at the cost of giving a different kind of complexity,
and a reduction in utility if somebody has to opt-out to get around
that initial complexity )

And hence why the counter-proposal to USE flags to solve that
complexity a different way is "prebuild them yourself and ship
them" ( as that eliminates all the dependency complexity and USE flag
complexity user side, while also giving them the man pages -> Quality )

Just the current mechanisms for this counter-proposal shift that
inescapable complexity to a place where it becomes harder to manage in
a standardized way.

And I don't think shifting this complexity to maintainers is the right
step, even though I want the same deliverables.

That's why I'd rather a way to shift this complexity to a build
service, ... albeit, it introduces some complexity of its own with the
building and distribution of these man pages.

Complexity is a pain-in-the-ass, you can't get rid of it, only shift it
around till it stops hurting.

However, all that said, If we're going to shoot some kind of
documentation in the face for the pain its dependency-complexity
introduces, let it be "info".

- Far fewer people enjoy or can actually get useful information out of
  info pages
- Its build tooling frequently has dizzying problems in dependency
  complexity and fragility, frequently made worse by portage getting
  build ordering wrong after perl upgrades.[1]

(Hopefully we've fixed the worst of that, but this is plutonium, a gift
that keeps giving cancer)

1: https://bugs.gentoo.org/buglist.cgi?quicksearch=texinfo