Hi Michael, [CC'ing maintainer of devhelp.] Michael Biebl wrote (on debian-mentors): > the hal-doc package contains the API documentation for hal. In the last > upstream release, upstream decided to use devhelp [1] for the API > documentation. The location of the documentation files changed (to > /usr/share/gtk-doc/html/hal/) which lead to this bug report [2]. > [1] devhelp is a API documentation browser for Gnome > [2] http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=398803 > While taking a look at this issue I wondered how to deal with this > correctly. It seems that this case is not handled consistently by the > different packages that have devhelp documentation. [Option #1] > Some packages just install the files to > /usr/share/gtk-doc/html/$package. This of course has the disadvantage > that people that don't use devhelp have a hard time finding the files. This is a bug in the package. Debian Policy sections 12.3 and 12.4 are pretty clear that documentation other than man and info pages is supposed to be accessible under /usr/share/doc/<packagename>, at least with symlinks. (But this is a "should" rather than a "must" so it only warrants a severity-normal bug.) Also, not having docs in the expected place seriously confuses users, as in the bug you referenced. Please report a bug against any other packages you found doing this. [Option #2] > So, some package maintainers decided to move the documentation files to > /usr/share/doc/$package/html and create a link back to > /usr/share/gtk-doc/html/$package. The problem here is, that you mustn't > forget to explicitly exclude the html files from being compressed, > otherwise devhelp will not find them correctly. I think dh_compress excludes html and css files by default, doesn't it? [Option #3] > The third option is, to > leave the files in /usr/share/gtk-doc/$package and create a link to > /usr/share/doc/$package/html. > If I count the packages currently installed on my machine that use > devhelper, 6 use option #1, 16 option #2 and only 1 uses option #3. At first, reading this paragraph of Policy 12.3, I thought option #3 may be the preferred one: "Packages must not require the existence of any files in /usr/share/doc/ in order to function [78]. Any files that are referenced by programs but are also useful as stand alone documentation should be installed under /usr/share/package/ with symbolic links from /usr/share/doc/package." However, this still says that the real docs should live in /usr/share/<package>, not /usr/share/gtk-doc/html/<package>, so this isn't a perfect solution. Also, devhelp is an independent program, not part of the package in question, so it is not the *package* that is requiring files in /usr/share/gtk-doc/html/<package> in any case. From an aesthetic standpoint, personally I would prefer option #2. One can argue that devhelp is no different in principle from any other viewer that might be used to read docs. > So, there doesn't seem to be a consensus here, that's why I'm seeking > for advice and discussion of the following questions: > > 1.) Should the documentation be accessible from within > /usr/share/doc/$package? Yes, policy requires it with a "should" directive. > 2.) If yes, should the files be moved to /usr/share/doc/$package/html > and a link be created to /usr/share/gtk-doc/html/$package or > 3.) should the files remain in /usr/share/gtk-doc/html/$package and a > link be created to /usr/share/doc/$package/html These seem more-or-less equivalent to me, but as said above I'd prefer #2 aesthetically. > 4.) Should the package declare a Recommends: devhelp IMO at most a Suggests is warranted, as the docs are perfectly readable without it using any HTML viewer. > 5.) If there is a consensus on this matter, should this be documented > somewhere (policy, dev-ref) and bugs be filed against the packages not > complying to this policy? Maybe see what the Debian maintainer of devhelp thinks? Also, what does he think about the possibility of patching devhelp for Debian to look for docs in /usr/share/doc/<package>/html as well as in the default /usr/share/gtk-doc/html/<package> location? If that were done there would be no need for symlinks. best regards, -- Kevin B. McCarty <kmccarty@princeton.edu> Physics Department WWW: http://www.princeton.edu/~kmccarty/ Princeton University GPG: public key ID 4F83C751 Princeton, NJ 08544
Attachment:
signature.asc
Description: OpenPGP digital signature