I'd be happy to do some research on this subject. I'll look into this and see what i can dig up.
Before I spend time on this, it might make more sense to look into Docbook, as Glen mentioned. In addition, it would be good to spend some time checking out what other Apache projects are using for ideas. I would suspect that the most-used documentation system(s) would bear the most fruit for us. If for no other reason, than the sheer numbers of people banging on them.
I assume we already have a system (I think it's Javadocs). I think it would also be good to determine if any of our colleagues have made the switch from our system to another. Finally, assuming we've already got a system, what are the reasons we're moving away from our current system? Complexity? Dead-end product? Etc.
It's not a question of moving away, necessarily. What I'm looking for is a supplementary facility. Look at
and click on one of the class name links on the left of the main page, e.g. PropNames. That opens an iframe with the source. On linux, in Mozilla, it also positions the iframe at the top of the page. Clicking the link again - it's a toggle - restores the previous position of the page. When I first set is up, this tidy behaviour was not available on Windows using either Mozilla or IE, but that may have changed by now.
The problem is that there was no clean way to automatically generate the htmlized source. It's that supplementary facility that I'm looking for.
Peter -- Peter B. West <http://www.powerup.com.au/~pbwest/resume.html>