Re: DOCBOOK-APPS: Using olinks

[Bob Stayton <bobs at caldera dot com>]

On Tue, Jul 16, 2002 at 10:42:17AM -0600, Rankine, Alastair J (Alastair) wrote:

> 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.
 
I was intending to post something about using
the new olink mechanism that has just been implemented
in the 1.52 stylesheets, but was waiting for a resolution
to a small problem that came up, which you ran into (your item #1).
I'll try to address your questions.

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

In the 1.52 chunking code, Norm added support for
outputting the 'standalone' attribute in the XML
declaration for XML output.  Unfortunately, the XML
standard doesn't permit that attribute in the
XML declaration in system entities
(only version and encoding).  The workaround for the
current 1.52.2 stylesheet is to set the parameter
'chunker.output.omit-xml-declaration' to 'yes' to omit
the XSL declaration entirely.  I've fixed
this in CVS (the common/targets.xsl file), and it shouldn't
be a problem after the next stylesheet release.


> *** 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?
 
When you say "rewrite", do you mean <rewriteURI>
in an XML catalog?
If so, try using <rewriteSystem> rather than <rewriteURI>.
DOCTYPE's are considered system identifiers, not URIs,
although they sure look the same to me!
 

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

This appears to be a bug in the stylesheet templates.
There shouldn't be two templates in xref-to mode that match article.
I'll fix it.  


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


-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
Caldera International, Inc.                 fax:   (831) 429-1887
                                            email: bobs@caldera.com