Re: gtk-doc inter-document cross references

[Daniel Veillard <veillard redhat com>]

On Thu, Jun 14, 2001 at 12:12:04PM -0400, Owen Taylor wrote:
> 
> 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

   Steps 1/ 2 and 3/ can still be handled at an XSLT stylesheet.
     1/ xsltproc won't do validity checking so won't complain by default
     2/ that can be tested easilly in the template related to the reference
        <xsl:if test="id(@href)"> ....
	and the default case outputing different XML/HTML
     3/ using the <xsl:document> extension it is possible to generate
        multiple output

>  - 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.

     Interdocument links are possible, but they need to name the document,
there is no native equivalent to keep a multi tree ID table. I think the
core of the problem is that except at installation time you are never able to
know the relative path to the missing document (because the function name
don't give you the module/file components).

> Any ideas on this issue? 

     Sure I have ideas about this. What is needed are out of band links.
Basically being able to store a list of links outside the source or target
document. That's basically the index.sgml purpose. XLink has support
for those kind of links
        http://www.w3.org/TR/xlink/#xlg
but this is not natively supported by the browsers so this will need to be
processed by the stylesheet to generate the references anyway.

     I think keeping an index is a very sound thing to do, whatever the
technique used for making the binding at a later time this will be required
to keep the links manageable. If this index is kept in an XML format 
and its path can be computed by the final XSLT stylesheet which generate
the rendered HTML, then it is possible to load it using the document()
function (very much like Norm coded the localisation support of the DocBook
generated HTML). And then it's just adding a thin layer of customization on
top of the existing stylesheets to expand those links when the HTML is
generated. But in any way we still need to keep the index (but it should
not be too hard).

  Sounds a better solution ?

  If keeping the index is the point you object to, the alternative would
be when installing a new set of XML to an user installation to preprocess 
it when it gets installed. This would require loading all the existing
documents walk them to collect the IDs and fix the refs in the installed
document (i.e. the same process as you described but without keeping an
index around).

  No miracles, but this looks manageable in a relatively similar way,
either resolving the references at install time or when generating the
HTML.

Daniel

-- 
Daniel Veillard      | Red Hat Network http://redhat.com/products/network/
veillard redhat com  | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/