Re: gtk-doc xml stuff

[James Henstridge <james daa com au>]

(cc'ing to the list so it gets archived).

Matthias Clasen wrote:

> > I noticed that you have been working on converting gtk-doc to use XML. 
> > I started working on converting the gtk-doc.dsl file in gtk-doc to XSLT 
> > last night, and hadn't realised that you were working on it as well.
> >    
>
> James, 
>
> thanks for the info. I haven't touched gtk-doc.dsl so far. What I have done
> now is enabling gtkdoc-mkdb to produce docbook xml as intermediate format
> and
> make gtkdoc-mkhtml smart enough to smell whether it operates on sgml or xml
> and behave accordingly. But since jade can process the xml just fine and the
> medium-term goal is to install xml anyway, I didn't plan on touching
> gtk-doc.dsl.
Okay.  I was hoping to be able to dump jade and SGML completely, and go 
with xsltproc for everything.  After porting the stylesheet, I was 
thinking of changing the docs to use XIncludes rather than entities to 
pull in the generated portions of the document.

This way, the files representing the different sections can be valid XML 
documents themselves (so a section could have its own entities, for 
instance), and you don't need to keep the list of entity definitions and 
entity references in the main file in sync.

Also, XIncludes work recursively, so you could combine a number of 
reference docs into a larger book set.

> Of course, we still need an xref-fixing pass before the xml can be
> installed.  I 
> have posted my first attempt at an xsl stylesheet for that to gtk-doc-list
> if
> you're interested.
I got the handling for <link> elements done as well now.

> The approach I took is to reduce the index file to a list
> of installed documents to scan for target ids. The main blocker for further
> progress in this direction is that  I need to find a definitive answer to
> the
> question of what uri scheme yelp/devhelp support/will support for 
> cross-referencing between xml documents. 
>  
What about for output on a website?  For that, we would still need 
something like the current scheme.  Below is the conversion of 
gtk-doc.xsl I did (well, the bits related to cross referencing):

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
               version='1.0'
               xmlns="http://www.w3.org/TR/xhtml1/transitional";
               exclude-result-prefixes="#default">

 <!-- import the chunked XSL stylesheet -->
 <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/>

 <xsl:output method="xml" indent="yes"/>

 <!-- change some parameters -->
 <xsl:param name="toc.section.depth">1</xsl:param>

 <xsl:param name="chapter.autolabel" select="0"/>
 <xsl:param name="use.id.as.filename" select="'1'"/>
 <xsl:param name="html.ext" select="'.html'"/>
 <xsl:param name="shade.verbatim" select="1"/>

 <!-- ========================================================= -->
 <!-- template to create the index.sgml anchor index -->

 <xsl:template match="book|article">
   <xsl:apply-imports/>

   <!-- generate the index.sgml href index -->
   <xsl:call-template name="generate.index"/>
 </xsl:template>    

 <xsl:template name="generate.index">
   <xsl:call-template name="write.text.chunk">
     <xsl:with-param name="filename" select="'index.sgml'"/>
     <xsl:with-param name="content">
       <!-- check all anchor and refentry elements -->
       <xsl:apply-templates select="//anchor|refentry"
                            mode="generate.index.mode"/>
     </xsl:with-param>
     <xsl:with-param name="encoding" select="'utf-8'"/>
   </xsl:call-template>
 </xsl:template>

 <xsl:template match="*" mode="generate.index.mode">
   <xsl:if test="not(@href)">
     <xsl:text>&lt;ANCHOR id=&quot;</xsl:text>
     <xsl:value-of select="@id"/>
     <xsl:text>&quot; href=&quot;</xsl:text>
     <xsl:call-template name="href.target"/>
     <xsl:text>&quot;&gt;
</xsl:text>
   </xsl:if>
 </xsl:template>

 <!-- ========================================================= -->
 <!-- template to output gtkdoclink elements for the unknown targets -->

 <xsl:template match="link">
   <xsl:choose>
     <xsl:when test="id(@linkend)">
       <xsl:apply-imports/>
     </xsl:when>
     <xsl:otherwise>
       <gtkdoclink href="{ linkend}">
         <xsl:apply-templates/>
       </gtkdoclink>
     </xsl:otherwise>
   </xsl:choose>
 </xsl:template>

</xsl:stylesheet>

I think it looks a bit more readable than the DSSSL version :)  As I 
said before, for the layout/visual portions of the stylesheet, I think 
it would be good to use some of the work Sander did on the Yelp 
stylesheets, so the reference docs look consistent with the rest of the 
gnome docs.

James.

--
Email: james daa com au              | Linux.conf.au 2003 Call for Papers out
WWW:   http://www.daa.com.au/~james/ |   http://conf.linux.org.au/cfp.html