#975941 add exception case to package-contains-documentation-outside-usr-share-doc if docs are linked to /usr/share/doc?

Package:
lintian
Source:
lintian
Submitter:
Nicholas D Steeves
Date:
2020-11-29 01:51:04 UTC
Severity:
normal
#975941#5
Date:
2020-11-27 05:08:32 UTC
From:
To:
Hi,

The case is software that provides, for example, html docs, and that
opens these docs using the standard F1 (file bar help) interface.
Such docs should of course also be present in /usr/share/doc.  As I
see it, the question is whether the files should actually exist in
their upstream location--which in Debian translates to
/usr/share/foo/bar and have these docs linked to /usr/share/doc, or
whether they should be moved to /usr/share/doc and be linked back to
where the software expects them.  Option three is maintaining a patch
for a Debian-specific location, but I don't think that's the right solution.

So, should Lintian not warn about
package-contains-documentation-outside-usr-share-doc if the package links the assets to /usr/share/doc, or should the Lintian information output recommend the inverse case (moving the docs to /usr/share/doc and linking them back to where the software expects them)?

I leave it to you :-)
Cheers,
Nicholas
#975941#10
Date:
2020-11-27 22:14:50 UTC
From:
To:
Nicholas D Steeves <nsteeves@gmail.com> writes:

If the files are used at runtime, Policy requires installing the files
outside of /usr/share/doc and linking them to /usr/share/doc.  See Policy
12.3, second-to-last paragraph.
#975941#15
Date:
2020-11-28 20:47:29 UTC
From:
To:
Hi Russ,

Russ Allbery <rra@debian.org> writes:

Given that W: package-contains-documentation-outside-usr-share-doc will
still warn in cases where Policy requires the documentation, which
suggests that lintian wants developers to do something different than
Policy, it seems like there are two or three avenues forward:

1. Demote package-contains-documentation-outside-usr-share-doc to
experimental--still not a great option, because of the tension with
Policy.

2. Check to see if docs have been linked to /usr/share/doc for
discoverability, and if they haven't then warn with something like
packages-doesnt-link-documentation-to-usr-share-doc.  Lintian output is
clean if the docs have been linked.  Alternatively maybe
package-contains-documentation-outside-usr-share-doc explanatory
information could be updated instead of adding
packages-doesnt-link-documentation-to-usr-share-doc?

3. Update explanatory information of
packages-doesnt-link-documentation-to-usr-share-doc to note that it will
find false positives and that lintian overrides should be employed.

In any case, I think Policy §12.3 should be cited in the explanatory
description[s].

Of course, if the expectation is that all software should be patched to
get its runtime documentation from /usr/share/doc, then Policy should be
amended.

Regards,
Nicholas
#975941#20
Date:
2020-11-29 01:48:20 UTC
From:
To:
Apologies, I should have been clear in my first message that I'm not an
active Lintian maintainer (and thus wouldn't be the one to make any
changes to Lintian).  Just providing some background from the Policy
perspective.

Nicholas D Steeves <nsteeves@gmail.com> writes:

It's unlikely that the project would go in this direction, since this is a
consequence of the long-term goal to ensure that /usr/share/doc can be
deleted in its entirety if desired by the local admin, and thus its
deletion can't break any software.  For example, I believe some embedded
systems hook into the package installation process to strip /usr/share/doc
files from the system because disk space may be very restricted.

Therefore, any files that installed software packages need at runtime have
to be installed outside of /usr/share/doc, with links to /usr/share/doc if
appropriate.