Bug#970275: lintian: Please allow /usr/share/gtk-doc/html without emitting package-contains-documentation-outside-usr-share-doc

[Simon McVittie <smcv@debian.org>]

Package: lintian
Version: 2.92.0
Severity: wishlist

Libraries that are documented using gtk-doc install documentation into
/usr/share/gtk-doc/html. This is technically part of the package's
functional interface, because higher-level libraries that depend on
a lower-level library can build-depend on the lower-level library's
documentation in order to adjust cross-references in the higher-level
library documentation to point to a local copy instead of an Internet
copy; so my interpretation of Policy §12.3 is that it would be wrong
to move this documentation into /usr/share/doc, because of this paragraph:

    Packages must not require the existence of any files in
    /usr/share/doc/ in order to function.[6] Any files that are used or
    read by programs but are also useful as stand alone documentation
    should be installed elsewhere, such as under /usr/share/package/,
    and then included via symbolic links in /usr/share/doc/package.

For example, GTK has Build-Depends-Indep on GLib documentation in order
to fix cross-references to base classes like GObject and GInterface.
GTK-based GUI libraries like WebKitGTK have Build-Depends-Indep on GTK
documentation to fix cross-references to GtkWindow, and so on.

The GNOME team mostly handles this by leaving the real files that make
up the documentation in /usr/share/gtk-doc/html/mylib, and having
symbolic links like
/usr/share/doc/libmylib-{dev,doc}/html -> /usr/share/gtk-doc/html/mylib
to make it easy to discover via the usual paths. I believe this is
compatible with both the letter and the spirit of Policy.

However, it currently causes Lintian to emit
package-contains-documentation-outside-usr-share-doc. Perhaps there could
be logic like this pseudocode?

    for each file outside /usr/share/doc that looks like documentation:
        if there is a symlink in /usr/share/doc to the file or one of
        its ancestor directories:
            # assume it is used or read by programs
            no tag
        else:
            package-contains-documentation-outside-usr-share-doc

Thanks,
    smcv