Bug#363139: gtk: Please move all gtk html documentation to /usr/share/doc/...

[Loïc Minier]

On Wed, Aug 09, 2006, Josselin Mouette wrote:
> Le mercredi 09 août 2006 à 17:49 +0200, Loïc Minier a écrit :
> >  1) We do want to see all documentations relevant to a package below
> >  /usr/share/doc/$package, but this can easily be achieved via symlinks
> >  to the actual location of the documentation.
> I think this is just a better because this is where all documentation is
> put for Debian packages.

 Well, in point 1), I propose a symlink, so all the documentation is
 still available from this place.

> >  4) What if the documentation is relevant to multiple packages?  It's
> >  easy to have multiple links to /usr/share/gtk-doc/html from the
> >  /usr/share/doc/$package dirs.
> And it's easy to have links to /usr/share/doc/$package
> from /usr/share/gtk-doc/html.

 Point 4) is about being relevant for multiple packages, for example
 libfoo-dev and libfoo-doc.  Why privilege one over the other when
 upstream already installs documentation in a central place which you
 could symlink to?

> >  5) This breaks expectations across distributions that you can find the
> >  gtk-doc of foobar below /usr/share/gtk-doc/html/foobar unless we manage
> >  symlinks there.
> Of course we should manage symlinks there, and this is what's done for
> packages which had their documentation moved.

 Let me rephrase point 5); wherever we ship the doc, we have to put list
 it in /usr/share/gtk-doc/html to not break expectations, so why move it
 at all?

 While thinking about this I thought about a new potential proble for
 the move:
 6) Some tools might not handle symlinks in /usr/share/gtk-doc very well
 (devhelp springs to mind), while we currently have no special tool that
 goes over /usr/share/doc/.

> >  Summing this up, I propose the following:
> >  - continue shipping doc to /usr/share/gtk-doc/html as the default place
> >    for all gtk-doc HTML documentations (imagine someone writes
> >    gtk-doc-genindex)
> >  - symlink from all relevant /usr/share/doc/$package dirs to these docs.
> I think we should do it the other way round, with a symlink
> in /usr/share/gtk-doc/html. Of course, the real solution is to integrate
> this in dh_installdocs.

 My mail gave (IMO) objective arguments to keep the files below
 /usr/share/gtk-doc and have symlinks in /usr/share/doc; while thinking
 about this, I've found zero reason to do it vice-versa.

-- 
Loïc Minier <lool at dooz.org>