OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: olinking in webhelp

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.


Bob Stayton
Sagehill Enterprises

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]