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 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 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