DOCBOOK-APPS: Using olinks

["Rankine, Alastair J (Alastair)" <arankine at avaya dot com>]

Reading Bob's excellent guide to using the XSL stylesheets gave me the incentive I needed to attempt using olinks in my documents. However I've ran across some problems - interested to see if it's just my setup or whether other people are having similar problems. The end result is that I got it working, but with several workarounds I'm not particularly happy with. Also note I haven't tried print output yet.

The major versions of software I'm using are Saxon 6.5.2, Sun catalog resolver classes 1.1, Docbook DTD 4.2CR3, XSL stylesheets 1.52.2.

If I included all off the relevant config files, Makefiles, drivers, catalogs, etc I'm sure this email would be (more) unreadable :) Hence I've included just extracts from my HTML driver file and olinkdb.xml file posted at the end of this email.


*** 1. Generating the xref targets files.

The standard stylesheets generate an XML declaration which seems to confuse saxon:

	<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>

When saxon comes to parse this via an external entity in the olinkdb.xml file, it gets confused:

Error on line 1 column 34 of file:/.../aaa-targets.db:
  Error reported by XML parser: unexpected characters in XML text declaration (expected "?>")
Recoverable error
org.xml.sax.SAXParseException: unexpected characters in XML text declaration (expected "?>")
Olink error: could not open target database file:/.../olinkdb.xml.

If I manually remove the "standalone" attribute from the xml declaration in aaa-targets.db file, it works just fine.



*** 2. Saxon doesn't seem to do URI rewriting when parsing the DOCTYPE of the olinkdb.xml file. URI rewriting seems to work fine elsewhere however (eg the xsl:import statement in the driver file).

Error on line 6 column 1 of file:/.../olinkdb.xml:
  Error reported by XML parser: Cannot read from http://docbook.sourceforge.net/
release/xsl/current/common/targetdatabase.dtd (Connection timed out: connect)
Recoverable error
org.xml.sax.SAXParseException: Cannot read from http://docbook.sourceforge.net/release/xsl/current/common/targetdatabase.dtd (Connection timed out: connect)
Olink error: could not open target database file:/.../olinkdb.xml.

Workaround seems to be to use a hardcoded pathname in the DOCTYPE declaration of olinkdb.xml (as below).

Maybe a Saxon bug?



*** 3. Ambiguous rule match error occurs when using olinks in a document:

Recoverable error
Ambiguous rule match for /article[1]
Matches both "dedication|preface|chapter|appendix|article" on line 236 of file:/c:/cygwin/usr/local/lib/sgml/stylesheets/docbook-xsl-1.52.2/html/xref.xsl
and "abstract|article|authorblurb|bibliodiv|bibliomset                      |biblioset|blockquote|calloutlist|caution|colophon                      |constraintdef|formalpara|glossdiv|important|indexdiv                      |itemizedlist|legalnotice|lot|msg|msgexplan|msgmain                      |msgrel|msgset|msgsub|note|orderedlist|partintro                      |productionset|qandadiv|refsynopsisdiv|segmentedlist                      |set|setindex|sidebar|tip|toc|variablelist|warning" on line 180 of file:/c:/cygwin/usr/local/lib/sgml/stylesheets/docbook-xsl-1.52.2/html/xref.xsl
Writing target.db for article
Writing assumptions.html for sect1(assumptions)

[... snip ...]


This doesn't seem to affect the output - the link works just fine.




--- the start of my olinkdb.xml file:

<?xml version="1.0"?>
<!DOCTYPE targetset SYSTEM "file:/C:/cygwin/usr/local/lib/sgml/stylesheets/docbook-xsl-1.52.2/common/targetdatabase.dtd" [
<!ENTITY aaa-targets SYSTEM "aaa-targets.db">
<!ENTITY bbb-targets SYSTEM "bbb-targets.db">
<!ENTITY ccc-targets SYSTEM "ccc-targets.db">
]>
<targetset>
  <sitemap>
    <dir name="syseng">
      <document targetdoc="abc">
        &abc-targets;
      </document>

	...snip...


--- my HTML driver file

<?xml version="1.0" encoding="ISO-8859-1"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
                version='1.0'>

  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/>
  
  <xsl:param name="section.autolabel" select="1"/>
  <xsl:param name="section.label.includes.component.label" select="1"/>
  <xsl:param name="toc.section.depth">3</xsl:param>

  <xsl:param name="use.id.as.filename" select="1"/>
  <xsl:param name="navig.graphics" select="1"/>
  <xsl:param name="navig.graphics.extension">.png</xsl:param>
  <xsl:param name="html.stylesheet.type">text/css</xsl:param>
  <xsl:param name="make.valid.html" select="1"/>
  <xsl:param name="html.cleanup" select="1"/>
  <xsl:param name="header.rule" select="0"/>
  <xsl:param name="footer.rule" select="0"/>
  <xsl:param name="chunker.output.doctype-public">-//W3C//DTD HTML 4.0 Transitional//EN</xsl:param>

  <!-- support use of external cross-references -->
  <xsl:param name="collect.xref.targets">yes</xsl:param>

<!-- snip some generated text customization -->

</xsl:stylesheet>


--
 Alastair Rankine        arankine@avaya.com
 Avaya Labs Services R&D    +1-303-538-4129