GNOME Bugzilla – Bug 454916
gtk-doc should permit generation of URI-based cross-references
Last modified: 2007-09-22 19:53:46 UTC
Gtk-doc should permit the packager to specify URI's for cross-references, instead of always assuming local installation of external documentation. For example, a gtk-doc cross-reference to the Glib type gint is now relative: href="../glib/glib-Basic-Types.html#gint" instead of the (often more useful) web-based reference: href="http://developer.gnome.org/doc/API/API/2.0/glib/glib-Basic-Types.html#gint"
correction: href="http://developer.gnome.org/doc/API/2.0/glib/glib-Basic-Types.html#gint"
Right now I don't have a good idea how to support it. One would need to pass the uri to the index.sgml as e.g. --extra-index to FIXXREF_OPTIONS. While that is technically doable, I don't like the idea of hard-coding web-uri's in a number of packages. It would be better if that uri could be taken from the local index.sgml and there would be a switch to build webdocs (where fixxref would try to use weburis whenever it can). I had a brief look at the docbook specs and my proposal would be to add <releaseinfo> <ulink url="http://library.gnome.org/API/glib/index.html">glib</ulink>. </releaseinfo> to glib-docs.sgml (people should need to update their existing master files - maybe we could warn if this is missing). Next gtk-doc.xsl could generate an entry for index.sgml, like e.g.: <ONLINE href="http://library.gnome.org/API/glib/index.html">. One issue we have to clarify is how to specify when to do what: * 'make install' tries to resolve against localy installed docs * 'make publish' could use the weburis and maybe even provide a hook to upload the files As recommended on gtkdoc-mlist, this can be used meanwhile: http://gwyddion.svn.sourceforge.net/viewvc/gwyddion/trunk/gwyddion/devel-docs/ncrosslinks.py?view=markup
Some thoughts: 1. <releaseinfo> looks good, but I would add a role attribute to the <ulink> to prevent screw up in the case someone adds some actual release info. In fact, gstreamer seems to be already using <releaseinfo>. Also the text inside should be something meaningful as it will appear in the output if processed with older gtk-doc. Unfortunately the allowed children of <releaseinfo> are quite limited. Maybe the text should meaningful enough to keep it always: <releaseinfo> for GStreamer Library 1.2.3.4.5. The latest version of this documentation can be found on-line at <ulink role="online-location" url="http://library.gnome.org/API/gstreamer/index.html">http://library.gnome.org/API/gstreamer/</ulink>. </releaseinfo> 2. index.html in http://library.gnome.org/API/glib/index.html is superfluous. For anyone following the link http://library.gnome.org/API/glib/ is equivalent and anything processing the directory URI will not have to remove index.html first. The only possible use of it could be to determine the extensions, e.g. if it points to index.xhtml, linked files will be given extension .xhtml. This is obscure. On the other hand my on-line API documents have .php extension... 3. `make install' vs. `make publish': consider possible interaction with bug 434134. General rebasing of links in already built HTML would be nice. 4. <ONLINE> in index.sgml: Can we assume gtkdoc-fixxref is the only program reading index.sgml -- or at least that the other things will not consider the file broken? 5. Migration. It will take years. However any temporary mechanism, such as new gtkdoc-fixxref options, would be very hard to get rid of, so we should probably avoid them. People can convert the links manually meanwhile, for instance with my script (I can add support for more libs if anyone is interested).
1.) yes a role for the ulink makes sense. I though of role on the releaseinfo tag first. The default one is created in gtkdoc-mkdb::OutputBook. That part is easy to change. 2.) agreed. 3.) yes. but I have no good plan for this yet. For that we need some alternative rules in gtkdoc.mak that fixxrefs if not gtkdoc is installed. 4.) index.sgml is not even sgml. I've checked gtkdoc-fixxref and it would ignore unknown 'tags' so adding a new one is safe. 5.) I don't think it will take year. The most important libs can be changed quickly. having library.gnome.org will help. I wonder if gtkdoc-fixxref should still create relative links for documents with the same base uri. Will probably save some bytes.
Created attachment 91747 [details] [review] gtk-doc.xsl ONLINE patch Here's the gtk-doc.xsl part, it creates <ONLINE> element in index.sgml from <ulink role="online-location" ...> in <releaseinfo>. Maybe it's a bit clumsy as I'm not a XSL expert and also wanted to keep the match="*' template intact.
Created attachment 91756 [details] [review] gtkdoc-fixxref.in ONLINE patch This patch adds --online option to gtkdoc-fixxref, which makes it to prefer on-line locations for absolute (see the FIXME inside) links.
Now if I fix GLib docmentation to create <ONLINE>, rebuild it, add --online to my FIXXREF_OPTIONS and rebuild my documentation, I get references to developer.gnome.org in my documentation instead of local. So it essentially works. That was the easy part. The remaining, hard, part is the integration. I have no idea what other people expect or how they are going to use this (I use a heavily customized build process, including custom XSLT, for on-line publication). If gtk-doc.make gains another target (`publish'), what ii should do? Rebuild html/ with on-line locations? Rebuild it into another directory? Or should it be an install-like target?
I could imagine using 'make publish' which builds docs to a separate directory tmpdir and afterwards call my hook to upload. I am not sure if there are people that would like to use the online links for local docs, because they don't have those installed (does not sound like a good idea to me).
I would like see a uri mapping file or an similar entry in Makefile.am: file: <package>-crossrefs.txt ----------------------------- glib <uri|local> gobject <uri|local> pango <uri|local> gtk+ <uri|local> (etc.) --end--- in the absense of an entry in the uri map file, gtk-doc would warn and remind the packager to add the entry, while perhaps assuming local. I think it's desirable to have a single place, e.g. this map file, to manage this issue. You set it up once and forget it. Just my thoughts. Phil
I don'T like to have such a file, as its unclear who maintains it. What if upstream changes the URL where the publish the docs. With Yeti and my proposal the change would automatically reach the sources (after updating them).
(In reply to comment #9) > I would like see a uri mapping file or an similar entry in Makefile.am: > > file: <package>-crossrefs.txt > ----------------------------- > glib <uri|local> > gobject <uri|local> > pango <uri|local> > gtk+ <uri|local> > (etc.) > --end--- > > in the absense of an entry in the uri map file, gtk-doc would warn and > remind the packager to add the entry, while perhaps assuming local. > > I think it's desirable to have a single place, e.g. this map file, to manage > this issue. You set it up once and forget it. A use case, please. I can see these clear use cases: (a) Upstream developer (i.e. who releases the source code). You have no idea where the thing will end up being installed, therefore any local references are wrong (unless they are intrapackage). You want neutral links, that's either no links (poor) or on-line URLs. Now, the integration problem is that this should somehow happen automatically on `make dist', and it should *not* involve running xsltproc on the whole beast. This is what my ncrosslinks.py script achieves but it's a kluge with hardcoded on-line locations. (b) On-line reference publisher. You want all references on-line (intrapackage can probably stay relative). (c) Distro package manintainer. You know the final locations of the off-line documentation and you want all references local because they are faster, work off-line and do not eat users' bandwidth. And you can make sure all the linked API references are installed at package build time to get good links. Again, you would rather avoid running xslt when building the package. (d) Random builder from source code. You are happy with on-line references or want to rebase them to local files, but in any case, what use would be the crossrefs file to you? It's quite possible people want other things, that's why I said I don't know what they want to do, but I'd like to hear what the goal is, not `I'd like to see some stuff in Makefile.am or somewhere'. To repeat a bit what Stefan said: It's unclear who would set up such a file and who would use it then and for what purpose. Also, hardcoding the URI of GLib on-line documentation in every package that uses GLib is exactly what we are trying to avoid here.
Created attachment 91847 [details] [review] gtkdoc-fixxref.in ONLINE patch Current svn trunk changes has broken patch 91756. Here's an updated version.
Created attachment 91852 [details] [review] gtkdoc-fixxref.in ONLINE patch Still broken. This one should actually work.
Let me back up and try to understand what you're doing. You want upstream developers of gtkdoc-based documentation to decorate their docbook <releaseinfo> with an additional piece of information -- the "official" online-location of their documentation. That location will (somehow) later be used, e.g. with gtkdoc-fixxrefs, to flesh out cross-references. Let's stop right there. Isn't the assumption that this <releaseinfo> location is "of interest" to other developers simply wrong? For the sake of argument, consider the case of developers on a private LAN. One of the boxes on the LAN, box A, is for private web-hosting to LAN members, including the hosting of gtkdoc-based documentation. In this case, the need is for all LAN members see a copy of all "well-known" gtkdoc-based documentation: glib, gtk+, pango, etc., hosted on box A. The <releaseinfo> "online-location" role, as supplied by the upstream maintainer, is irrelevant in that case, i.e. to people who wish to rehost documentation privately. These people would also want to resolve cross-references to that private host. I agree that having an official online location, as specified by the upstream maintainer, is useful. I don't think that you can end the story there, however. Documentation _installers_ should have final say as to where documentation resides and where external cross-references resolve. I think "local" or <releaseinfo>-based is not enough. Phil
In the case you describe the local packager *also* controls the packages referred to and equips them with the corresponding <releaseinfo>. Where's the problem?
Anyway, if you want some complex install and post-install time manipulation with the locations, I suggest to grab proposed gtkdoc-rebase in bug 434134 and implement the requested functionality there. gtkdoc-fixxref is tied to the XML -> HTML building step and does now work afterwards.
What you propose is workable, but requires editing the gtk-doc source files on a per-installation basis. I suppose I would rather see that releaseinfo entry placed in a gtkdoc-owned map file, e.g. /usr/share/gtk-doc/data/xref.map, and then that map file is referred to as other packages are installed. That way you don't have to open up a package tarball and hack away at releaseinfo tags. You simply install the package untouched, then edit the new entry placed in /usr/share/gtk-doc/data/xref.map, iff you wish to retarget the online location, and gtkdoc-fixxref would refer to that map file. Phil
<releaseinfo> is in the DocBook source. <ONLINE> is in installed index.sgml. If you rebuild the docs, change the DocBook source. If you don't, change index.sgml. I fail to see how patching index.sgml differs from editing some xref.map file.
ok, sounds good.
2007-08-02 Stefan Kost <ensonic@users.sf.net> Patch by: Yeti <yeti@physics.muni.cz> * gtk-doc.xsl: Generate ONLINE tag in index.sgml. * gtkdoc-fixxref.in: Allow to base links against online versions of xreffed docs. Fixes #454916. * gtkdoc-mkdb.in: Add releaseinfo to doctemplates. * tests/bugs/docs/tester-docs.sgml: * tests/gobject/docs/tester-docs.sgml: Update templates.