c) I could choose which kind of documentation I wanted html or pdf or (maybe someday) windows help file
Building PDF docs is complicated by needing to have a specific PDF generator software which is commercial, IIRC. I heven't tried building PDF so someone else will have to answer as to how to do it.
Technically, you can use Apache FOP. In practice, you might need to use specific version, as all other versions are badly broken. What version exactly is sacred knowledge. I believe John is using XEP Personal for generating release docs on PDF.
Nod. XEP Personal edition is highly recommended - modulo the fact that it basically doesn't have any useful error handling :-( Apache FOP will build some of the docs OK, but often completely mangles the pagination in more complex cases, so I've stayed away from it. If you're building docs for a specific library that isn't too large, and you're prepared to manually check the docs to make sure they're OK, then FOP may work for you. Otherwise XEP personal edition is free and a drop in replacement for FOP. Just my 2c.... John.