Getting eXist to work with Resin
eXist is an XML database that I'm interested in looking at. There's a web servlet front-end to it, so I thought I'd look into doing some things with that. My web hosting service uses Resin for servlets. I appreciate that. Resin has a lot of things going for it. If I do wind up using eXist, I may want to put it on my website, so I installed Resin on my linux box at home to mimic my website.
You can download a war file of eXist, which makes it easy to set it up as a web application for Resin. There's a problem, though. The web.xml file for eXist makes some assumptions that you are using Jetty, the web application container that eXist includes with the stand-alone verison of eXist. So, you need to make a couple of changes to get the war file to work with Resin.
Edit WEB-INF/web.xml, and search for "Jasper". I found two sections:
and
I commented those out, and eXist appears to work okay.
Dad’s Problems
I learned something by watching my Dad today. Not how to fix the garage door opener that's jammed shut, now how to straighten the fence that is leaning into my neighbor's yard, and not how to fix the heater so my wife's toes don't freeze this winter. He helped me with all of these problems, but he didn't fix any of them. What I learned is that I, like my father, am more interested in problems than solutions.
This realization dawned on me as I looked at the bottom of my Dad's shoes while he was trying to figure out why the bathroom sink leaked. I didn't read it in the rubber soles of his Sear's brand shoes (even though I'd been staring at them for the last two hours, there wasn't any insight there). But I was starting to figure it out when he called up to me "What's that for?".
There was excitement in his voice. He called me down under the sink to help him identify whatever it was that had caught his fancy. "You see that?". He was shining the flash light beam on a little half-inch copper pipe, poking up through the floor. "Uh huh," I said, hoping my voice didn't carry any of the uncertainty I felt.
I was sure I should have known what that pipe was for, but I didn't. My Dad always seems to know when I'm trying to hide my ignorance, and he likes to call me on it. He said, "Do you know what that's for?". He was on to me. I didn't really have any choice. I stammered about a bit, and then asked him, "You mean this pipe? The little copper one?". He drawled out, very slowly, almost like a caricature of the Minnesotan he is, "Yah". "Umm, hmm, let me look at it a bit better. Can I have the flash light?"
Stalling sometimes works at times like these. He gets too impatient and lets something slip. I scooted under the sink as he inched out of the way. We both couldn't fit under in there at once. Taking the flashlight, I shined it over the pipe. Seeing nothing unusual, I put my hands on the pipe, tested the cap, looked behind the pipe, and finally shut the flashlight off. He hadn't said a word. I was stuck.
"Nope, what's it for?" I finally asked. He sat back and wiped his hands on a rag and said, "No idea, let's go downstairs and see if we can find it there."
He wasn't as interested in helping me stop the leak that started there under the bathroom sink, slinked through the sub-floor, and dripped through the supporting beam onto my kitchen floor. He was interested in why the half-inch copper pipe poked up through the floor from who-knows-where. I scrambled out from under the sink and realized, as I grabbed the toolbox, and hurried off after him, so I was I.
Indexing in XSL
Indexes are a vital part of documentation, whether it's online help or printed documentation.
I could point you to a lot of studies on this, but I'll just give you an example from my experiences. When I was working at Oracle, our users always claimed they liked search the best, but by studying how they used the product, we learned that what they were calling search was actually the index (the index has a search box in it, so they'd type a search in there and get the closest index result). Nearly all of our experienced and intermediate users used the index as their main interface to the online help. They hardly ever used the table of contents, and only went to the full text search when the index really failed them. This behavior is probably changing as full text search gets better and as search tools push indexed lists (like Yahoo!) aside on the web.
So, it's quite surprising that there is no indexing support in XSLT. RenderX has some nice extensions to make things easier, but those extensions are related to formatting the index, not creating it.
Here are the problems I'm running into.
- Uniqueness
- Each index entry should only be output once. If it's a child indexterm, it should only be output once for each parent term. That's hard to do.
- Grouping
- Index terms are grouped. For example, all the index terms that start with "A" are usually grouped in the same area.
- Sorting
- You can't control sort order in
xsl:for-eachloops except by telling it you want a text or numeric sort. What if my text order is different than the one chosen by the XSLT processor? Asian languages often have multiple ways of sorting. Which one do I use? Can I do any of them without having to edit the FO by hand?
In case it's not clear, I'm pretty frustrated by this. Indexing should be easy to support in an almost functional language like XSLT. It's not, though.
Installing DITA OT 1.2beta onDebian Linux
I'm just setting up the DITA Open Toolkit (DITA OT) on my Debian box, and I thought I'd take notes. This isn't really a how-to, but maybe it will help someone.
- Go to the DITA Open Toolkit webpage.
- In the left pane, click on Download
- Two choices - dita-ot releases under the CPL or the dita-ot released under the Apache ASL . Use whichever you prefer, the content of both packages is the same. I chose the Apache license.
- Look at the Linux Install Guide
- Extract the archive somewhere. In its current incarnation DITA is hard to share, so take that into account.
- Debian and Java have challenges. Make sure you install Java, at least 1.4 (there have been some problems with JDK 1.5, more on that later)
- Install (using apt) ant, ant-doc, and ant-optional.
- Install xalan, libxalan2-java and libxalan2-java-doc
- If you want to make PDFs, install fop.
- Go into the DITA directory and type "ant all" and you should be set to go.
Optional things:
If you are doing this for personal use, get RenderX's xep instead of fop. You can't really compare the two - xep is the better solution. Their free edition includes a little footer telling everyone about xep, but that's okay by me. They are giving me something free. I don't mind giving them some advertising for it. People pay $50 for a $5 t-shirt advertising Tommy or DKNY and they feel like they got a good deal.
Install eclipse. Managing ant projects can be a real pain. Take advantage of eclipse for doing that.
If you can afford it, buy oXygen. It's worth the $50 they charge, and their license is really good. Things may have changed, but the last time I tried the free XML editors on Linux, they left a lot to be desired, especially debugging support for XSL transformations. Really, I wanted to use emacs. I've used emacs for years, but I was wasting a lot of time and switched back to oXygen.
Use source control. Install CVS or something similar. It's too hard to manage XML projects without source control.