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

[Cedric Sodhi]

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.

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.

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.

-------------------------------------------------
This free account was provided by VFEmail.net - report spam to ab...@vfemail.net

ONLY AT VFEmail! - Use our Metadata Mitigator to keep your email out of the NSA's hands!
$24.95 ONETIME Lifetime accounts with Privacy Features!
15GB disk! No bandwidth quotas!
Commercial and Bulk Mail Options!

[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

[Michael Orlitzky]

On Thu, 2023-01-19 at 13:25 +0200, Cedric Sodhi wrote:
>
> 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.
>

I think "protects noone" is overstating it. If your network is broken,
the man pages might be your only troubleshooting resource. It would
suck to find that (say) net-wireless/iwd introduced a new USE=man flag
a few weeks ago and now you can't get connected to some weird
conference wifi and are unable to google for help.

Something like USE=noman would be nicer for users, but IIRC we have a
policy against them (flags with a "no" prefix). Setting a global
USE="+man" default also creates some headaches in our "user interface."

OTOH I do agree it would be nice if we had a way to disable them if you
very explicitly ask for it. Sphinx (the example in bug 890589) is
obnoxious, and if you're going to strip the man pages with something
like FEATURES=noman on an embedded system -- or if you just don't care
about those particular man pages -- then it would be great if you could
not build them in the first place.

The best of both worlds would be if someone could convince upstream to
generate them during their "make dist" process.

[Cedric Sodhi]

On Thu, Jan 19, 2023 at 11:33:20AM -0500, Michael Orlitzky wrote:
> On Thu, 2023-01-19 at 13:25 +0200, Cedric Sodhi wrote:
> > 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.
>
> I think "protects noone" is overstating it. If your network is broken,
> the man pages might be your only troubleshooting resource. It would
> suck to find that (say) net-wireless/iwd introduced a new USE=man flag
> a few weeks ago and now you can't get connected to some weird
> conference wifi and are unable to google for help.

Fair enough, "protects noone" was not perfectly correct.

But is the improbable combination of

P( the user should have been protected ) =
P( user accidentally/mistakenly specifies USE=-man )
× P( the manpage's availability circularly depends on itself )
× P( the user has no other access to the manpage )
× P( the maintainer did not recognize the sitation and disabled "man" )
× P( the user ends up in that situation )
× P( the user is a reasonable user who deserves to be protected (!) )

really worth generalizing it as a "ALL packages MUST NEVER … ! "?

I think a far more agreeable approach which does justice to

The likelihood of the case that forcing manpages actually saves someone AND
The likelihood of the case that it causes problems (by dependencies for the user, or by additional work for the maintainer)

is to remind maintainers of it, but live-and-let-live, i.e. let maintainers do their job without imposing a policy.
I wouldn't know of anyone who would have had a problem with this in the past and I don't think anyone will exclaim "Gosh, if just we have had a policy...!" in the future.

[orbea]

Protecting users from themselves can be a misfeature. Its better to
educate and then let them freely choose than to play as their nanny.

[Rich Freeman]

On Fri, Jan 20, 2023 at 9:13 AM orbea <or...@riseup.net> wrote:
>
> Protecting users from themselves can be a misfeature. Its better to
> educate and then let them freely choose than to play as their nanny.
>

TL;DR - it makes sense to unconditionally install prebuilt manpages,
but not to require pulling in dependencies to build them. The latter
should be up to maintainer discretion.

I suspect the original policy was more about the fact that install
masks are already available to cover use cases like avoiding manpages.
I think the dependency issue is the much bigger one. If the
dependencies to generate manpages are trivial or can be expected to be
otherwise installed I can see the argument for just installing them
anyway. However, when they're large it doesn't make much sense.

If you're going to go on an expedition to the middle of the wilderness
where you can't use your phone to google a manpage, then I'd think
that manpages are probably just one of MANY things you'll be wanting
to pack. I get that once upon a time people only owned a single
computer and were concerned about having that one computer down.
Access to specialized tools could still be something you have to plan
for today. However, the text of most manpages is easily searched
online today so missing them is at worst an inconvenience unless you
literally have no access to a browser on another device.

--
Rich