Re: gtkdoc-fixref and install directories

[Damon Chaplin <damon helixcode com>]

Owen Taylor wrote:
> 
> 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.

Yes, and since the whole help system is supposedly moving to DocBook
for Gnome 2.0, I wouldn't worry about it too much.

As long as it will work in RPMs/debs, and we can ship bundles of the
HTML docs, I think that is OK for now.

Damon