Hi Russ, Russ Allbery <rra@debian.org> writes: > Nicholas D Steeves <nsteeves@gmail.com> writes: > >> 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)? > > 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. > Thank you for definitively NACKing that option. 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
Attachment:
signature.asc
Description: PGP signature