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

Re: Best practice for packages using devhelp for their API documentation

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

Reply to: