We have 4-5 main docbooks, which have lots of olinks between them. And we have many sandbox docbooks, which don't have many olinks, but may refer to each other or the main set occasionally.
olinks work by using paths from one doc to another going up a directory tree, and over and down to the target. The path to take is deduced from a hand-coded static file containing an xml representation of how the "site" containing the docbook targets are laid out. (see http://www.sagehill.net/docbookxsl/OlinkDetails.html#UsingSitemap for details). Our binary assembly distributions generally include docbook html/pdf artifacts. When these are laid out as specified in the "site", the olinks work. For our 4 main books, this is not too hard to do. If I think about the other books that would be included in other distributions (that may be obtained at other times), to make this work, we would have to design some kind of "bookshelf" (e.g. directory structure), and tell users (or have an install script ...) to move the downloaded docs to the right place in the bookshelf - to enable correct linking. (Note: we already have a bit of an install script - adjustExamplePaths, I think it's called). An alternative would be to not have olinks except among books released together; we could replace the olinks with links to a "well known web url" where the docs could be found. This could be the uima.apache.org/docs/.... release-number .../ etc. site. Issues here include what to do about versions/release numbers (keep the docs for older versions around up to a point?). Or, perhaps there's other alternatives? -Marshall
