If you are looking for the epic motorcycle journey blog that I've written, please see the Miles By Motorcycle site I put together. 
  • OpenOffice XHTML XSLT export filter
    09/18/2007 1:59PM
    As part of large project I'm working on, I need to create some kind of context sensitive online help system for a web application. I've used LyX in the past and exported that to DocBook which I then ran through an HTML filter but it's clumsy and there's no good maintainable way to link sections of the webapp to the generated html pages. For a given bit of help information you don't know which page it will end up on.

    I decided instead of using a hodgepodge of technologies, I would try to use OpenOffice.

    OpenOffice has an XSLT engine useful for transforming ODT files to other formats including XHTML. They have a sample XHTML export filter which works fairly well but, at the present moment, only seems to generate a single monolithic page. I'll deal with that later.

    The concept I had was, somehow, to include specially formatted <a name=""> tags in the generated HTML to mark points that I want to link to from my application. I figure I could use some standard naming scheme like "special_prefix|section|feature". I could then write a quick  indexer that could crawl through the generated HTML files looking for the special_prefix and create an index identifying which features are documented in which HTML files. Then it's a simple matter of writing a little index lookup utility; pass it the section and the feature you want the documentation for and have it displayed. Of course since the OpenOffice XHTML export only supports a single monolithic file, this isn't strictly necessary, but eventually I want to get the filter to generate multiple pages and the last thing I want to have to do is crawl through the app and update links every time I change the documentation.

    OpenOffice doesn't seem to support much in the way of metadata, so as a proof of concept I used the bookmark feature. I created a sample document and dropped bookmarks at various places.

    The stock XHTML export filter ignores bookmarks so I had to modify the share/xslt/export/xhtml/body.xsl filter definition to include a section to turn ODT bookmark tags which look like:

    <text:bookmark text:name="ecommerce|customer_list"/>

    to <a name=""> tags like:

    <a name="_fv_HELP|ecommerce|customer_list" />

    in the generated HTML. the _fv_HELP is just a arbitrarily chosen string that I can be relatively sure will not be present in any other <a name=""> tags so I can use that to search on to find the tags I'm interested in.

    After much trial and error, I added:

        <xsl:template match="text:bookmark">
            <xsl:param name="globalData" />

            <xsl:element name="a">
                <xsl:attribute name="name">_fv_HELP::<xsl:value-of select="@text:name"/></xsl:attribute>
            </xsl:element>

        </xsl:template>

    to body.xsl right above the first link definitions and it seems to work. The <a name=""> tags are exported to the right places in the generated HTML.