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
