olinking in webhelp

["Bob Stayton" <bobs@sagehill.net>]

I'm investigating the DocBook SourceForge bug report #3469357 that requests 
that webhelp support olinking. I set up two books with olinks and processed 
them with webhelp from docbook-xsl-1.77.1.  The olinks did not work, but I 
was able to determine why.

The basic problem is that the xhtml stylesheet that webhelp is based on 
makes it difficult to set up olinking. The webhelp stylesheet imports the 
xhtml/chunk.xsl stylesheet, which in turn imports the xhtml/docbook.xsl 
stylesheet.  The latter has this xsl:output element:

<xsl:output method="xml" encoding="UTF-8" indent="no" 
doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN" 
doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"/>

The hardcoded doctype attributes in this element cause all output files from 
the xhtml stylesheet to have a <!DOCTYPE> declaration. That includes when a 
target.db file is generated for olinks.  Most olinkdb.xml database files use 
system entity references to pull in the target.db files, but system entities 
do not work when there is a DOCTYPE in the file.  With Saxon, it is not 
possible to override the original xsl:output, and so it is not possible to 
turn off the DOCTYPE.

The only workaround I've ever found for using olinks with xhtml is to 
replace the system entity references in olinkdb.xml with XIncludes. An 
XInclude will tolerate a DOCTYPE declaration in target.db.  After a bit of 
wrangling, I managed to get the webhelp/build.xml file to configure XInclude 
processing when the webhelp stylesheet is applied, so that when the 
olinkdb.xml file is opened to process olinks, it can resolve the XIncludes 
in that file.

That introduced a further complication, though.  The xhtml DOCTYPE has a 
remote SYSTEM URL, which means the XInclude processor will try to open it. 
Since it is to the www.w3.org website, it is not fast when responding.  To 
avoid the network fetch, you can set up an XML catalog file to redirect to a 
local copy of the DTD, so the webhelp/build.xml file would need to add 
catalog processing to the xslt process.

Here is the kicker, though.  I found that I could avoid all of these 
complications by changing xsl/webhelp.xsl to import xhtml5/chunk.xsl instead 
of xhtml/chunk.xsl.  The xhtml5 version does not have a hardcoded DOCTYPE, 
so the target.db file does not get a <!DOCTYPE> declaration, so system 
entities can be used.    With that change, olinks worked out of the box when 
the files are properly configured.

Now I'm not sure how to proceed.  It appears that the xhtml5 output works in 
the two browsers I tested, but I have not done extensive testing.  The 
xhtml5 stylesheet provides support for videoobject and audioobject, which 
could be nice for help systems.

An alternative to switching over to xhtml5 would be to modify webhelp's base 
stylesheet to work like the xhtml5 base stylesheet. That stylesheet sets up 
a replacement for xhtml/docbook.xsl that imports all the other xhtml modules 
but does *not* have the problematic <xsl:output> element.  You can look at 
xhtml5/xhtml-docbook.xsl to see what I mean.  That means webhelp would stick 
with xhtml instead of xhtml5.

I would suggest that if we don't switch webhelp to xhtml5, that we add a 
webhelp5.xsl anyway, for those who want to generate webhelp based on HTML5 
so they can get video and audio working.

Comments?

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net