Kevin B. McCarty wrote: > 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. agreed > [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? Right, but it didn't exclude the sgml and *.devhelp files which are also shipped as part of the API documentation and are used by devhelp. As devhelp can cope with *.devhelp and *.sgml being gzipped though, this issue is solved. > [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. It's comparable to dhelp, only specialised for API documentation. If the documentation in /usr/share/doc/$package/html is not accessible, /usr/share/gtk-doc/html/$package will be a dangling symlink and devhelp will simply show nothing. It won't crash or something alike. >> 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, > Thanks for you feedback! I went for option #2 for now and also changed the Recommends to Suggests. Cheers, Michael -- Why is it that all of the instruments seeking intelligent life in the universe are pointed away from Earth?
Attachment:
signature.asc
Description: OpenPGP digital signature