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:
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:param name="globalData" />
<xsl:attribute name="name">_fv_HELP::<xsl:value-of select="@text:name"/></xsl:attribute>
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.