Page 1 of 1

ANT Filter Tokens and Validation

Posted: Wed Aug 20, 2014 6:48 pm
by eskwayrd
Hi,

Can I configure oXygen to understand ANT filter tokens in some way, so that DocBook <xi:include> tags can validate when their hrefs use a filter token to specify a path?

For background, I manage a number of DocBook books with oXygen and each uses common elements, like copyright statements, that are included in each book. I work with authors on different platforms, Linux, Windows, OSX, and it is possible for the location of the common elements to vary with respect to the folder structure of each book. For example, when authoring on Linux, the folder structure might be:

Code: Select all


/docbook/
common_xml/
guide_xml/
Whereas on Windows, the folder structure might be:

Code: Select all


C:\DocBook\
common_xml\

D:\DocBook\
guide_xml\
I automate the transformation of DocBook to PDF and HTML output using ANT, and I can filter the XML using tokens, so instead of:

<xi:include href="../common_xml/copyright.xml"/>

I can use:

<xi:include href="@common_xml_dir@/copyright.xml"/>

However, when tokens are used to specify include paths validation within oXygen fails because the ANT tokens are not similarly filtered. Validation is important because it catches problems before the ANT task is invoked by my CI system, and failures because of the tokens are misleading if the document is otherwise valid and builds successfully, and could mask other problems if my co-authors get used to the red validation status indicator.

Is there a way to make this work in oXygen? Is there another approach that might help address the variability in common XML locations and allow oXygen to validate a book?

Re: ANT Filter Tokens and Validation

Posted: Thu Aug 21, 2014 3:36 pm
by adrian
Hi,

I'm afraid you cannot configure Oxygen to recognize the ANT filter tokens in their current form within XML documents.

My question is why are you using ANT filter tokens in XInclude @hrefs, why not use relative paths instead?

Within Oxygen you can use XML catalogs to redirect systemIDs or URIs to a specific location.
Even the ANT filter tokens if written as an absolute URL, can be redirected with an XML catalog (which can be added to Options > Preferences, XML > XML Catalog).
e.g.

Code: Select all

<xi:include href="file:/@common_xml_dir@/copyright.xml"/>
can be redirected to look for the files (copyright.xml) in the current location (.) of the XML catalog:

Code: Select all

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<rewriteSystem systemIdStartString="file:/@common_xml_dir@/" rewritePrefix="."/>
<rewriteURI uriStartString="file:/@common_xml_dir@/" rewritePrefix="."/>
</catalog>
Regards,
Adrian

Re: ANT Filter Tokens and Validation

Posted: Thu Aug 21, 2014 8:30 pm
by eskwayrd
Adrian,

I cannot simply use relative paths because the folder containing common elements is in different locations on different platforms (conforming to legacy file layout decisions, prior to conversion from FrameMaker to DocBook).

The suggestion to use an XML catalog is a good one; I overlooked that facility. I can make platform-specific XML catalogs that my co-authors can use.

Thanks!

Re: ANT Filter Tokens and Validation

Posted: Tue Aug 26, 2014 9:47 pm
by eskwayrd
Hi Adrian,

I'm having difficulty adapting the example catalog definition you provided. If I use this:

Code: Select all


<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<rewriteSystem systemIdStartString="file:/@common_xml_dir@/" rewritePrefix="file:///path/to/common_xml_dir"/>
<rewriteURI uriStartString="file:/@common_xml_dir@/" rewritePrefix="file:///path/to/common_xml_dir"/>
</catalog>
and turn up the XML > XML Catalog > Verbosity, I see errors logged like:

Code: Select all


Description: Public: null System: file:/path/to/guide/xml/@common_xml_dir@/legalnotice.xml = null
Note that the error demonstrates that @common_xml_dir@ is nested within a guide-specific URI, and is not at the start of the URI even though my include is <xi:include href="@common_xml_dir@/legalnotice.xml"/>.

I can update the catalog with guide-specific mappings for @common_xml_dir@, but that doesn't seem notably better than managing the <xi:include> paths.

Do you have any suggestions?

BTW: I'm using Oxygen 15.2.

Re: ANT Filter Tokens and Validation

Posted: Wed Aug 27, 2014 11:35 am
by adrian
Hi,

My example was misleading since it only works for a @href with an absolute URI, like this:

Code: Select all

<xi:include href="file:/@common_xml_dir@/legalnotice.xml"/>
Note the leading file:/ from the @href which makes it absolute (also works with just the protocol, 'file:', 'http:', etc).

It won't work with what you're using right now (it's considered a relative URI):

Code: Select all

<xi:include href="@common_xml_dir@/legalnotice.xml"/>
because as a relative URI, it first gets expanded to an absolute URI (resolved relative to the current directory or an established base directory) before being resolved through the XML Catalog. So, the ANT filter token ends up in the middle of the resolved URI instead of the start (as seen in the logged message):

Code: Select all

file:/path/to/guide/xml/@common_xml_dir@/legalnotice.xml
As a result the catalog resolver does not match the start string.

Because the token ends up in the middle of the absolutized URI, I'm afraid there is no way to write the XML catalog to work with the relative URI @hrefs in their current relative URI form (href="@common_xml_dir@). It simply cannot match a string in the middle. You will have to also modify the @hrefs in the files to make them absolute (href="file:/@common_xml_dir@ or href="file:@common_xml_dir@). Then you will probably also have to change the ant filter token expansion to compensate for this (omit the 'file:' protocol from the token expansion).

Regards,
Adrian

Re: ANT Filter Tokens and Validation

Posted: Wed Aug 27, 2014 10:44 pm
by eskwayrd
Your explanation makes a lot of sense, and I'm pretty sure I can make this work now.

Thanks very much, Adrian!