Anyway

I’ve been slowly work­ing on a tutorial for using entity res­ol­u­tion cata­logs that I prom­ised the OASIS Entity Res­ol­u­tion Tech­nical Com­mit­tee (ERTC) I’d do (I chair the TC). As befits a proper tutorial, I figured I should test out the bits as I’m writ­ing them in more than one imple­ment­a­tion, just so I can warn people of the poten­tial pit­falls. This has proven to be a frus­trat­ing exper­i­ence for me, and I can see why so many people say tech­no­logy is just too hard.

The cata­log spe­cific­a­tion itself is fine; not widely imple­men­ted enough in my opin­ion (for example, MSXML doesn’t sup­port it) but we’re hop­ing to change that in the TC. Even those tools that do sup­port cata­logs often do so piece­meal; for example I’ve tested the cata­log sup­port in jEdit and it works as expec­ted — but not in the XSLT plu­gin. Sup­port­ing files that the editor finds aren’t found when you come to trans­form the doc­u­ment you’re edit­ing. The XSLT trans­form uses Xalan so I can prob­ably fig­ure out how to make it work with a cata­log — but I shouldn’t need to.

And talk­ing of Xalan — this whole sys­tem is just too hard. In the tutorial I wanted to use the XML stylesheet PI as an example of the uri ele­ment to keep the con­cepts simple. And Xalan, being part of the Apache XML pro­ject, is reas­on­ably widely used. So here are the steps I went through to try to have my stylesheet be some­where other than in the same dir­ect­ory as the doc­u­ment says it is.…

1. Down­load Xalan and install
2. Down­load Norm Walsh’s entity resolver for Java (so far, so good)
3. test with the cata­log I’ve been using up till now. No luck
4. dis­cover that the JDK that you just installed on the new PC didn’t add itself to the PATH and so the PC is mer­rily using whatever java execut­able it found in the Win­dows sys­tem dir­ect­ory. Sigh. Add the Java bin dir­ect­ory by hand to the PATH envir­on­ment variable.
5. the cata­log still isn’t being found. Hunt around on google for poten­tial answers
6. Dis­cover that the JDK 1.4.2 comes with its own ver­sion of Xalan, which is too old, and doesn’t allow you to reset the resolver with com­mand line options, and you have to tell Java that the Xalan dir­ect­ory is “endorsed” (whose bright idea was this? Just over­writ­ing the jar files with the new set should be suf­fi­cient, but no, you have to tell java as well that you really meant for the new Xalan to be used).
7. This doesn’t work either, but the error mes­sages are dif­fer­ent now, so some­thing changed… dis­cover that you also have to put the resolver jar into the same “endorsed” directory
8. the cata­log still doesn’t work, and run­ning the “verb­ose” option on the resolver gives you more details… now you’ve run into what I con­sider a bug in SAX (for details, see Leigh Dodd’s art­icle) which means you have to rewrite the entity cata­log to put in abso­lute URIs where you had rel­at­ive URIs before since SAX only passes abso­lute URIs (this does some­what lower the ues­ful­ness of cata­logs since you can’t move your dir­ect­or­ies around as eas­ily any more). Change all the cata­logs (but not the ones for the other applic­a­tions which don’t require this).
9. Now the basic cata­log works, so let’s try it with the stylesheet. Com­mand line at this stage is java -Djava.endorsed.dirs="c:\java\xalan-j_2_6_0\bin" org.apache.xalan.xslt.Process -in example.xml -xsl example.xsl -out example.html
-URIRESOLVER org.apache.xml.resolver.tools.CatalogResolver -ENTITYRESOLVER org.apache.xml.resolver.tools.CatalogResolve
   Dis­cover that Xalan doesn’t apply the entity resolver to the com­mand line. And using the XML stylesheet PI doesn’t seem to work either.
10. Give up on Xalan and resolve to try libxml

Stay tuned for adven­tures from the libxml world. And when I have suf­fi­cient energy I’ll go back and see if I can nail down why I can’t get Xalan to work with the stylesheet PI (it’s meant to, apparently).

Ser­i­ously, it’s no won­der people say tech­no­logy is just too hard. I have the advant­age of being reas­on­ably tech­nical, and know­ing people like Norm Walsh who told me about the SAX prob­lems. How are people without those con­nec­tions meant to be able to put all this together?