[oXygen-user] importing a custom docbook epub stylesheet

[Sorin Ristache]

Hello,


Robert Nagle wrote:
> <?xml version="1.0" encoding="UTF-8"?>
> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
>       xmlns:xs="http://www.w3.org/2001/XMLSchema"
>       exclude-result-prefixes="xs"
>       version="2.0">
>     <xsl:import
> href="http://docbook.sourceforge.net/release/xsl/1.75.1/epub/docbook.xsl"/>
> </xsl:stylesheet>


You should write your DocBook customization layer as an XSLT 1.0
stylesheet and validate it with an XSLT 1.0 processor because some
validation errors will be always reported for the DocBook stylesheets
with an XSLT 2.0 processor.


> I have some meta questions with regard to the general process of
> debugging here.
>
> 1. I assume that xslt v2 is better because it's a bigger number (and
> I've glanced over the differences in syntax, etc). Can you think of a
> reason why something would fail when version 2 is specified which
> would not be the case if version 1 is specified? Is best practice just
> to play it safe and go with version 1, or should I generally use 2
> unless otherwise specified?


You should go with the target version of the stylesheet (the 'version'
attribute) because sometimes there are important semantic differences
(and different evaluation results) between the XSLT 1.0 version and the
XSLT 2.0 version of the same expression applied to the same input XML
document.


> 2. I'm guessing that it's easier to debug a local copy of a xsl file
> than a remote one (in this case version 1.7.5.1 of the epub-xsl
> transform. which is different from the local version (which is 1.7.4
> that came with 10.2).  Is there a way that Oxygen knows to associate
> the URL in the xsl import command with a local file or files on my
> Windows machine? I don't know how to do this.


Both a local version and a remote one can be used in the XSLT debugger
because the debugger reads the content of the stylesheet from the
specified URL. You can map the URL of a remote stylesheet to a local
version with an XML catalog and in this case the debugger uses the local
mapped URL instead of the remote one specified in the stylesheet. The
mapping for DocBook stylesheets is already done in the built-in catalog
of Oxygen but if there is a new version available you can modify this
catalog or add a new one in Preferences -> XML -> XML Catalog. You can
read about the XML catalog support in the User Manual:

http://www.oxygenxml.com/doc/ug-oxygen/using-XML-Catalogs.html


> 3. (Now for my really naive question). What's the best way to debug
> XSLT messages. Should I start at the source xsl of the file(s)  being
> imported here. Or should I be looking up references in Saxon parser or
> using some Oxygen debugging view.  I realize that the answer is
> probably "it depends", but where does one start first?


Do you mean to debug the XSLT execution error messages as the ones
reported above? For the DocBook stylesheets if you use an XSLT 1.0
processor you should get errors only in your customization layer, not in
the original stylesheets and such errors are probably caused by using
incorrectly an XSLT feature (which means grab an XSLT tutorial!).

Do you mean to debug the result of an XSLT transformation that is not
the expected one but it is generated without XSLT validation/execution
errors? You should start from the unexpected area of the output by
clicking on it in the Text output view or the XHTML output view of the
XSLT Debugger perspective (the right side of the window in the debugger
perspective) that will highlight both the XML element and the XSLT
instruction that generated exactly that output area. See the output
views of the debugger:

http://www.oxygenxml.com/doc/ug-oxygen/determining-what-template-generated-particular-output.html


> Thanks.
>
> Robert


Regards,
Sorin