GNOME Bugzilla – Bug 465920
Use gtkdoc-rebase
Last modified: 2007-09-22 19:55:11 UTC
Several things: 1. Actually use it. This means something like gtkdoc-rebase --online --relative --html-dir=$(distdir)/html in the dist hook and gtkdoc-rebase --relative --destdir=$(DESTDIR) --html-dir=$(DESTDIR)$(TARGET_DIR) in the install hook. 2. Improve handling of relative paths in gtkdoc-rebase. It works quite well for installed documentation (either into its final location or a staging area) when it knows exactly where the links should point to, but not so well in the dist hook. The primary problem is what to do, implementing it then is probably the easy part. Maybe the best strategy when making dists is to convert links to on-line, and if the on-line location is unknown, convert them to relative? 3. Remove --online from gtkdoc-fixxref (i.e. revert the change), it is a wrong place to do this. It can be run only immediately after the HTML generation when <GTKDOCLINK>s are still there, which makes it non-integrable.
Created attachment 93596 [details] [review] use gtkdoc-rebase
yep, is useful and works great. I added the online uri's to my local index.sgml files for glib/gobject/gtk+. GStreamer cvs has them already. Will also try to make patches for glib/gobject/gtk stable/trunk soon.
What is your view of 2. (and 3.)? I attempted to change rebase to do the right thing for making dists several times, I stopped when I realised I didn't know what the right thing is. I have some other useful changes in rebase (fixed typos and printing a summary of what it has done at the end) that I will decouple and attach.
Created attachment 93602 [details] [review] rebase improvements - fixes program name in --help - recognizes relative ../foo paths as references to package foo (making them transformable without --aggressive) - prints a summary of what base urls were transformed to what at the end
Yes 3.) makes sense, especially if we run -rebase by default. Regarding 2nd, using relative if online links are not know would work for e.g. library.gnome.org. Most 3rd party probably would like to see a message in the summary and drop the links. I plane to make a gnome-love task to tel people how the can use the new features in gtk-doc. So I assue it won't take ages before important libs have an online-tag.
There's one more complication: rebase should be IMO used even if --enable-gtk-doc was not given as this option only controls the rebuild rules, not installation (see bug 450343). But it must not cause make failure if gtk-doc isn't available at all. Perhaps adding `-' before the command is sufficient.
Maybe a silly idea ... Could/Should gtkdoc-rebase link to *.png,*.css in $gtkdocprefix/share/gtk-doc/data/ if gtkdoc is installed. It would save a whopping 5 k per docs. For the css it would provide the benefit that updating gtkdoc, applies the new look to already installed docs.
(In reply to comment #7) > For the css it would provide the benefit that updating > gtkdoc, applies the new look to already installed docs. Assuming everyone wants the stock icons and namely style. Which is something I'm not sure of (even after excluding myself from everyone).
I added '-' to the rebase invocations - good catch! I also committed the rebase update. 2007-08-21 Stefan Kost <ensonic@users.sf.net> * gtk-doc.make: * gtk-doc.notmpl.make: Make use of rebase if possible. Fixes #465920 * gtkdoc-rebase.in: Rebase improvements and fixes.