some thoughts on our docbooks, and linking among them

[Marshall Schor <ms...@schor.com>]

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