Re: gtkdoc-fixref and install directories

[Owen Taylor <otaylor redhat com>]

Owen Taylor <otaylor@redhat.com> writes:

> What I'm thinking of doing is to change the gtkdoc-fixref system
> so that glib would install the HTML files in:
> 
>  $(datadir)/share/glib/html/*.html
> 
> And an index file into:
> 
>  $(datadir)/share/gtk-doc/indices/glib.index
> 
> And so forth. Then gtkdoc-fixref would simlpy scan all
> the files in $(datadir)/share/gtk-doc/indices and create
> relative links based on these files. gtkdoc-fixref would
> also honor a GTKDOC_PATH variable which could be
> set to include multiple index file directories for
> people who have packages installed in multiple places.

Thinking about it some more, there are various fundamental 
questions that this doesn't help with:

 - We need to ship HMTL docs in "fixed" form with the GTK+
   tarballs. However, the fixed form 

 - The fixed form needs to have relative links. But 
   if somebdoy uses GTKDOC_PATH, a relative link like:

    ../../../../../opt/gnome/share/glib/html

   is a bad idea since there is a good chance of symlinks
   getting in the way.

 - If somebody is building GTK+-2.0 with reference docs
   for both GLib-1.2 and GLib-2.0 on the system, even
   if they are in /usr/share/glib/html and 
   /usr/share/glib2/html, gtkdoc-fixref isn't going be 
   able to tell which g_string_new() description to get.

I guess the answer is basically that HTML is a lousy way
of distributing help text. My best idea is to do
as best as we can, accept that cross-module links will often
be broken for people doing odd things, and provide a
complete set of correctly built docs on the web site.


                                        Owen