gtk-doc inter-document cross references

[Owen Taylor <otaylor redhat com>]

Hi Daniel,

In the future, we hope to move the generation of HTML we do for
gtk-doc to using DocBook XML and libxsl. Mostly, this should be pretty
straightfoward, but there is one component of this that I don't know
how it would work.

Whenever gtk-doc hits something that it identifies as a type or a
function name in the text it is processing, it generates a cross
reference in the output SGML based on the name of the tag - something
like:

 see <link linkend="pango-break"></link> for details.

In some cases, these links are within the same document, so resolution
of this is simple - there is just an anchor:

 <title><anchor id="gtk-widget-show">gtk_widget_show ()</title>

And the normal cross reference resolution works. But in other cases,
the anchor that is targetted is in a completely different document.

The way we handle these cross references currently is rather a
hack. What we do is:

 - We pass in a command line option to Jade to be quiet about
   references missing ids.

 - We change our stylesheet so that when link to a missing 
   id is found, it generates, in the output:
    <gtkdoclink href="pango-break></gtkdoclink>

 - We change our stylesheet so that it outputs along with the
   html output, a file index.sgml, containing lines like:
   
   <anchor id="gtk-widget-show" href="gtk/gtkwidget.html#gtk-widget-show">
   
 - We have a tool, run at installation time, that uses the
   index.sgml files for all previously installed references
   to fix up the <gtkdoclink> tags in the reference being
   installed.

However:

 - I don't have a sense of how we'd move this to generating
   the docs via XSL

 - I feel there must be a better way... there should be some way to
   have XML document A reference a link inside XML document B, convert
   the documents to HTML, possibly splitting them into multiple files,
   and have the references still work.

Any ideas on this issue? 

Thanks,
                                        Owen