[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Best practice for packages using devhelp for their API documentation



Hi all,

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].

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.
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.
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. 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.
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?
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
4.) Should the package declare a Recommends: devhelp
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?

Cheers,
Michael


[1] devhelp is a API documentation browser for Gnome
[2] http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=398803
-- 
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


Reply to: