so

Extending for interoperability?

Volume 5, Issue 17; 28 Jul 2021

Considering support for ZIP files on the catalog path in the XML Resolver.

Extensions, be they vendor extensions or system extensions or user extensions, are often problematic from the perspective of interoperability. Just because your system understands the extension doesn’t mean my system does, and vice versa.

It feels slightly odd to be in the position where I’m considering adding an extension to improve interoperability.

Completely standard behavior for a catalog resolver is to read a list of catalogs and lookup external identifiers and URIs in those catalogs, returning local versions where possible.

It’s incredibly handy that the 3.x version of (the Java version of) the XML Resolver, the resolver will automatically locate catalogs that appear on your classpath.I suppose this is an extension too, strictly speaking, but since an implementation is free to locate catalog files through any means it chooses, this isn’t the same kind of extension as the one I’m coming to. Stick the DocBook schemas JAR file and the stylesheets JAR file on your classpath and resolution of DocBook schemas and stylesheets “just works”. This is extra easy in modern build environments where you don’t even have to manage the classpath, you just list the DocBook artifacts as dependencies and you’re done.

Turning our attention to the C# side of the house, C# doesn’t have anything like the classpath (AFAICT). Applications are compiled into executables and all of the “assemblies” required are packaged into the executable. I think the behavior in this context that’s equivalent to searching for catalogs on the classpath is finding catalogs in referenced assemblies. That’s fine, the resolver can do that.

But that doesn’t help you, the user, after the fact, if you want the application to be able to resolve, for example, DocBook URIs. You can download the relevant schemas and stylesheets, unpack them on your local file system, update the catalog path to point to those two catalogs, and that’ll work. But it means you have to manage all those files “by hand.”

If there isn’t some extension in the resolver, it’s just going to be a whole lot harder to use it on .NET and that seems less than ideal.

I am seriously considering (to the point of having experimentally implemented) allowing ZIP files to appear directly in the catalog path. For example:

catalogs=./catalog.xml;/usr/local/docbook.zip

That’s definitely an extension, but it would have the nice feature that it could be implemented in both the Java and C# resolvers: stick the archive files on the catalog path and it would “just work.” (In fact, since JAR files are really just ZIP files anyway, you could even stick the JAR files on the catalog path and the C# resolver wouldn’t have any trouble with them.)

The C# resolver is hampered by a broken API design, so if you want interoperability, the catalog files themselves will have to be crafted carefully, but that’s true regardless of whether or not they appear in ZIP files on the catalog path.

Is allowing (optionally, but enabled by default) ZIP files to appear directly on the catalog path a terrible idea?