Re:Gnome Developer Documentation: how to make 'some' money

[Matthias Clasen <maclas gmx de>]

>  So, we have three sub-problems here:
>   1) define the location-independant ID format/specification
>   2) use the location-independant ID in the developer documentation
> and/or make changes to gtk-doc to use it.
>   3) hack the conversion tools to support whatever needs to be 
>  supported
> to recognize the location-independant ID and convert it to
> location-dependant IDs.
> 
> Idealy, step 3) would be minimized. ie: only changes to the xslts 
> would be needed.
>

Exactly. In fact, I have made some attempts at getting gtk-doc to
produce properly cross-referenced docbook in the past. The basic idea is
to convert "dangling" <link>s to <ulink>s using a suitable url. Here is
my latest attempt. It consists of 

a) an index.xml file which lists documents from which IDs should be used
to satisfy dangling <link>s. Additionally, it specifies the prefix of
the url to emit. The attached example demonstrates that this prefix can
be used to e.g. link to man pages using the "man:" url scheme.

b) an xsl file which copies the docbook file and uses the index.xml file
to find out what urls to generate for dangling links.

This should mostly work, but I didn't finish it so far, since I couldn't
get scrollkeeper and yelp to do meaningful things with the ghelp urls so
far.

Matthias



<!DOCTYPE index [
<!ELEMENT document (#PCDATA)>
<!ATTLIST document url CDATA ""> 
<!ELEMENT target EMPTY>
<!ATTLIST target id ID #REQUIRED>
]>
<index>
  <document uri="ghelp:glib?">../gnome/glib/head/docs/reference/glib/glib-docs.sgml</document>
  <document uri="man:">index.xml</document>  
  <target id="abort"/>
  <target id="alloca"/>
  <target id="close"/>
  <target id="exec"/>
  <target id="execv"/>
  <target id="execvp"/>
  <target id="fopen"/>
  <target id="free"/>
  <target id="fseek"/>
</index>

<?xml version="1.0" ?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
version="1.0">

  <xsl:param name="index" select="'index.xml'"/>

  <xsl:output method="xml"
	      doctype-public="-//OASIS//DTD DocBook XML V4.1.2//EN"
	      doctype-system="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"/>

  <xsl:template name="copy" match="*">
    <xsl:copy>
      <xsl:apply-templates select="@*"/>
      <xsl:apply-templates/>
    </xsl:copy>
  </xsl:template>

  <xsl:template match="@*">
    <xsl:attribute name="{name()}">
      <xsl:value-of select="."/>
    </xsl:attribute>
  </xsl:template>

  <xsl:template match="//link">
    <xsl:variable name="linkend" select="@linkend"/>
    <xsl:variable name="linktext">
      <xsl:apply-templates/>
    </xsl:variable>
    <xsl:variable name="emitted">
      <xsl:choose>  
        <xsl:when test="id(@linkend)">
          <xsl:call-template name="copy"/>
        </xsl:when>
        <xsl:otherwise>
          <xsl:for-each select="document($index)/index/document">
            <xsl:variable name="uri" select="@uri"/>
	      <xsl:for-each select="document(text())">
                <xsl:if test="id($linkend)">
                  <xsl:element name="ulink">
                    <xsl:attribute name="url">
                      <xsl:value-of select="concat($uri, $linkend)"/>
                    </xsl:attribute>
                    <xsl:value-of select="$linktext"/>                       
                  </xsl:element>
                </xsl:if>
              </xsl:for-each>
            </xsl:for-each>
          </xsl:otherwise>
        </xsl:choose>
      </xsl:variable>
    <xsl:choose> 
      <xsl:when test="string($emitted)">
        <xsl:copy-of select="$emitted"/>
      </xsl:when>
      <xsl:otherwise>
        <xsl:value-of select="$linktext"/>                       
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>

</xsl:stylesheet>