GNOME Bugzilla – Bug 434134
fixxrefs like sed for installing pregenerated docs
Last modified: 2007-09-22 19:51:31 UTC
we need something that does simillar job like fixxrefs even if there is no gtk-doc available (to use the right xrefs links or remove them if lib is not there).
CC doesn't hurt.
Why can't it just depend on gtk-doc? This only affects people building from source, doesn't it? I think that people building from source should just make sure they have gtk-doc.
I'm been told that rebuilding docs for Gtk+ literally takes hours. People not touching source shouldn't need to rebuild docs. If you think they do, what's the point of shipping docs in tarballs then?
Oh, I see what you mean - we aren't installing the pregenerated docs properly. I wouldn't want to create another package just with gtkdoc-fixxref in it. Maybe we can change the gtk-doc Makefile stuff so that even when gtk-doc is disabled gtkdoc-fixref is used to install the docs if they are there.
Exactly.
It's a bit more complicated. We want the tarball to have links to online docs for all known modules, and to fix refs to installed docs if they exist only in the installed destination. So gtk-doc Makefile needs to know both the online location and the installed location (if any).
That sounds to me like too much trouble for source tarballs - how many people use source tarballs as opposed to packages? It would only help people using source tarballs who don't have all the other docs installed already, and who need cross-references.
At the end of the day I don't really care as long as distro-installed docs do the right thing, preferably without having to rebuild docs when building distro packages.
Created attachment 91854 [details] [review] implementation This patch adds gtkdoc-rebase command, to be used on documentation installed into its final location. It can do the following: - fix local cross-references to on-line (provided the corresponding packages define the on-line location as suggested in bug 454916, use --online) - fix on-line location to local - create either absolute or relative (use --relative) local cross-references - with a high probability fix random locations from upstream author's system to correct local or on-line locations (use --aggressive) - take into account the installation into a staging area during distro package build (use --dest-dir) and create relative references even in this case It is intended to be installed as a part of gtk-doc, but it operates on already installed HTML, therefore the dreaded xsltproc invocation is avoided. Please test and complain about the bugs...
2007-08-02 Stefan Kost <ensonic@users.sf.net> patch by: David Nečas <yeti@physics.muni.cz> * Makefile.am: * configure.in: * gtkdoc-rebase.in: Allow rebasing cross-references in generated docs. Fixes #434134.
So, how exactly does it work? What should the user library do to get the fix?
I belive you dist the gtkdoc-rebase and then run this after installing gtkdoc-rebase --html-dir=/usr/share/gtk-doc/html/pango --aggressive Lets see what Yeti suggests.
1. To enable linking to their on-line references, libraries put something like <releaseinfo> The latest version of this document can be found on-line at <ulink role="online-location" url="http://gwyddion.net/documentation/libgwyapp/index.php">http://gwyddion.net/documentation/libgwyapp/</ulink>. </releaseinfo> into the book (foo-docs.sgml). The key part is the <ulink> with role "online-location" in <releaseinfo>. This URL is the put into the installed index.sgml of the library as <ONLINE> tag. The problem with this bit is that someone has to do it for each relevant library. 2a. When making dists, developers use --online option of fixxref to refer to on-line instead of local version of other documentation (if it comes with <ONLINE>). 2b. When making dists, developers use gtkdoc-rebase --online on the documentation copied to dist-directory. Local file URIs are converted to on-line (again, requires <ONLINE> from the referred libraries). The second is easier and can be relatively simply integrated to the `dist' target. Neither 2a nor 2b is actually present in gtk-doc.make at this point. 3. Distro packagers that do not want to waste resources rebuilding the documentation but want local cross-references, use gtkdoc-rebase again (without --online) after `make install' to convert on-line paths to correct local paths for their system. If they install into a staging area, they use --dest-dir to specify the to-be-ignored prefix. 4. Local packagers can also point <ONLINE> and/or "online-location" to other places when building packages (somewhere on LAN for instance). ========================================================================= Please, please, give it some testing. Also, I'm not sure if 2a is a viable option at all. Maybe it would be better to leave the functionality in rebase and the revert fixxref on-line patch?
Well, I was mostly expecting an answer along the lines "nothing, it all Just Works automagically" :)
1 unfortunately does not happen automagically. 2. will happen automatically once we implement it -- if you use the supplied gtk-doc.make, people using customized makefiles have to update them to get this functionality. You probably need not to care about 3. and 4.