Linking to library.gnome.org
Recently the brave gtk-doc guys introduced a tool called gtkdoc-rebase, which updates external links in your API docs to point on the GNOME Library. The gtk-doc.make script has been updated to run gtkdoc-rebase on make dist. Unfortunatly all this pretty stuff doesn't work out of the box on Gutsy, as two premise have to be fulfilled to make this voodoo work:
- The
index.sgmlfiles in the gtk-doc folder must be uncompressed. The gtk-doc and Ubuntu guys currently argue regarding that topic. - Your uncompressed
index.sgmlfiles must contain an<ONLINE>tag pointing on the online docs.
Updating all the gtk-docs I've got would have been a boring task. So I wrote a little script which updates the uncompressed index files, when documentation exists in the GNOME Library:
Use it carefully, as it sends HEAD requests to library.gnome.org for every gtk-doc package not having that <ONLINE> tag yet.
Did I mention already, that this script processes uncompressed index files only? So call sudo gunzip /usr/share/gtk-doc/html/*/index.sgml.gz before using it.
Just a note that the index.sgml files are not compressed during most of the package build, these are being automatically compressed by dh_compress in the final stage of building: hence, it would be technically possible to run an URL rebasing tool during the build process if that's useful.
On the discussion on compressed files: my conclusion is that gtk-doc upstream doesn't want Debian/Ubuntu/etc. to compress index.sgml files as this breaks their expectations, so I guess we're supposed to explicitely exclude these files on the long term in our packaging rules.
Quite possibly you already know this and are deliberately not using it, but Python has a GzipFile module that will let you open the gz files as easily as uncompressed files: http://docs.python.org/lib/module-gzi... .
Stuart: Yes, don't care about handling .gz files, as gtk-doc needs them uncompressed anyway.
Loïc: Good to know, but the discussion isn't about the index.sgml of the package currently built. It is about the index.sgml files of the other libraries, used used by the package currently build: So when having for instance libfoo, which provides custom widgets, proper packaging of libfoo-doc needs the index.sgml of glib, gobject and gtk+.
Well, but I absolutly do not want to take position regarding compression of the index files. I've just choosen the most convenient route to reach my goal. Guess when the Debian/Ubuntu/etc. community prefers compressed index files, its just a matter of contribution/maintaining a patch.