Re: API docs locations

[Owen Taylor <otaylor redhat com>]

Havoc Pennington <hp redhat com> writes:

> "R.I.P. Deaddog" <maddog linuxhall org> writes:
> > 
> > However, under the perspective of packagers,
> > /usr/share/doc/packagename-version/html can be a very bad choice, since
> > %doc will install various docs there. I'm not sure about Redhat and Debian,
> > but for Mandrake docs, %doc directory will be 'rm -rf'ed before placing
> > any docs there, thus losing all API docs.
> > 
> 
> Red Hat probably does this too, but it seems pretty dumb if we can't
> put real docs in /usr/share/doc. We could ideally do some RPM fixage
> or come up with a hack for this. I'll ask the RPM experts.
> 
> Just occurred to me that including the version in the directory name
> might make cross references hard to set up. (e.g. from GTK docs to
> GLib docs)

The current gtk-doc code actually depends on a common installation
root directory for cross references to work. Now, this cross-reference
system needs to be improved/redone as we move to docbook-xml, but in
general the need to have a way of finding out all installed docs is
going to persists.

The reason for the:
 
  /usr/share/gtk-doc/html 

location is that it is neutral. I don't think it really makes sense
for libxml or glib to be installing under /usr/share/doc/gnome.  We
could go to

 /usr/share/doc/api

or something, but that seems a bit like namespace poaching.

Regards,
                                        Owen