[gtkmm] gtkmm & devhelp

[Roel <roel stack be>]

Hello,

I've written an xsl stylesheet that will convert the doxygen xml output to
devhelp format. It's very basic - tell me how you want it and I'll change
it. Steps to take: do ./configure in gtkmm source tree, go to
docs/reference and edit 'Doxyfile'. Change GENERATE_XML to 'yes'. Run
doxygen. Copy index.xml file to some directory, then run stylesheet (eg for
xsltproc: xsltproc -o gtkmm-2.2.7.devhelp doxygen2devhelp.xsl index.xml).
Copy resulting .devhelp file to gtkmm tree. Next step is tricky; devhelp is
a bit buggy, or I don't understand very well where it will search for
documentation; anyway, I just copied the whole documentation tree to
~/.devhelp/books/gtkmm-2.2.7/. Now run devhelp and voila, there you find
your trusty gtkmm documentation. Things to do:

- anchor links don't work (jump to page.html#somewhere). I don't know why
yet.
- Images don't work. I don't know how devhelp & gtkhtml work; should
coordinate with devhelp ppl.
- Index could be made better. Now there is only a list of classes and their
members, and the namespaces and their classes. Need to make more.
- Make something that works nicely for gnomemm and other doxygen
documenation (maybe it does already, haven't tried yet).

Anyway, I find it quite useful already. Like I said, I don't really know how
I should structure the index tree; if someone tells me what it should look
like, I'll implement it (standard disclaimer about having time and feeling
like it applies).

cheers,

roel

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

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

<xsl:param name="reference_prefix">reference/html/</xsl:param>

<xsl:template match="/">
  <book title="Gtkmm Library Reference Manual"
        name="gtkmm"
        link="index.html">
  <chapters>
    <sub name="Classes" link="{$reference_prefix}classes.html">
      <xsl:apply-templates select="doxygen/compound[ kind='class']">
        <xsl:sort select="."/>
      </xsl:apply-templates>
    </sub>
    <sub name="Namespaces" link="{$reference_prefix}namespaces.html">
      <xsl:apply-templates select="doxygen/compound[ kind='namespace']">
        <xsl:sort select="."/>
      </xsl:apply-templates>
    </sub>
  </chapters>

  <functions>
    <!-- @todo: maybe select only the real functions, ie those with kind=="function"? -->
    <xsl:apply-templates select="doxygen/compound/member" mode="as-function"/>
  </functions>
  </book>
</xsl:template>

<xsl:template match="compound">
  <xsl:param name="name"><xsl:value-of select="name"/></xsl:param>
  <xsl:param name="link"><xsl:value-of select="@refid"/>.html</xsl:param>
  <sub name="{$name}" link="{$reference_prefix}{$link}">
  <xsl:apply-templates select="member" mode="as-sub">
    <xsl:sort select="."/>
  </xsl:apply-templates>
  </sub>
</xsl:template>

<xsl:template match="member" mode="as-function">
  <!--
  <function name="atk_set_value" link="atk-atkvalue.html#ATK-SET-VALUE"/>
  -->
  <xsl:param name="name"><xsl:value-of select="name"/></xsl:param>
  <!-- Link is refid attribute of parent element + "#" + diff between refid of parent and own refid -->
  <xsl:param name="refid_parent"><xsl:value-of select="parent::node()/@refid"/></xsl:param>
  <xsl:param name="own_refid"><xsl:value-of select="@refid"/></xsl:param>
  <xsl:param name="offset"><xsl:value-of select="string-length($refid_parent) + 3"/></xsl:param>
  <xsl:param name="ref_diff"><xsl:value-of select="substring($own_refid, $offset, 5)"/></xsl:param>
  <xsl:param name="link"><xsl:value-of select="$refid_parent"/>.html#<xsl:value-of select="$ref_diff"/></xsl:param>
  <function name="{$name}" link="{$reference_prefix}{$link}"/>
</xsl:template>

<xsl:template match="member" mode="as-sub">
  <xsl:param name="name"><xsl:value-of select="name"/></xsl:param>
  <!-- Link is refid attribute of parent element + "#" + diff between refid of parent and own refid -->
  <xsl:param name="refid_parent"><xsl:value-of select="parent::node()/@refid"/></xsl:param>
  <xsl:param name="own_refid"><xsl:value-of select="@refid"/></xsl:param>
  <xsl:param name="offset"><xsl:value-of select="string-length($refid_parent) + 3"/></xsl:param>
  <xsl:param name="ref_diff"><xsl:value-of select="substring($own_refid, $offset, 5)"/></xsl:param>
  <xsl:param name="link"><xsl:value-of select="$refid_parent"/>.html#<xsl:value-of select="$ref_diff"/></xsl:param>
  <sub name="{$name}" link="{$reference_prefix}{$link}"/>
</xsl:template>

</xsl:stylesheet>

<!-- vim:ts=2 sw=2:
-->