Hi Vincent, I was actually thinking of converting only the product docs, not the website. For just HTML output, I find Forrest quite nice, but the linking for the various versions creates a lot of overhead for a release. And that's basically what triggered that thought.
Basically, I'd suggest to do this: - Basic website with Forrest with links to versioned product docs and Javadoc. - Product docs converted to DocBook, offering HTML and PDF versions similar to the SVN Book. Including FAQ. - Move developer docs entirely to the Wiki where it is more likely to be maintained. Developer docs in two places is a bad idea. One problem remains for which I don't have a good answer: the compliance page which is a bit hard to maintain. On 06.07.2010 21:30:46 Vincent Hennebert wrote: > Hi, > > Jeremias Maerki wrote: > > On 05.07.2010 17:13:32 Simon Pepping wrote: > <snip/> > >> In compliance, I kept only 0.95, 1.0 and trunk. This caused extensive > >> changes to comments. > > > > I guess keeping track of various versions on the website is one of the > > biggest issues why doing FOP releases is so hard. I keep wondering if we > > should not transform the actual product information to DocBook. But that, > > too, takes a lot of (initial) work. > > Interesting. Do you mean completely replacing Forrest by a DocBook-based > framework? Because otherwise that would only add up to the complexity > IMO. > > From my experience I see the following pros and cons of using DocBook: > Pros: > • stable, well-known, well supported format; > • very well documented: http://www.docbook.org/tdg/en/html/docbook.html > • geared towards technical documentation which exactly matches our > needs; > • HTML output easily customizable by CSS; > • PDF output easily customizable by XSLT; > • well supported, excellently documented official stylesheets: > http://www.sagehill.net/docbookxsl/ > • I like it ;-) > > Cons: > • horribly verbose; > • some work would be needed to turn the HTML output into a proper > website; A website extension is available but I think it tends to lag > behind; > • some currently automatically generated pages (like status.xml) would > have to be re-created. > > From a personal point of view, I would be rather excited to work on > a DocBook-based website rather than a Forrest-based one. Mainly because > I’m more familiar with DocBook than Forrest that still looks a bit like > a black box to me. For example, I have already customized the PDF output > produced from a DocBook document, whereas I wouldn’t know where to start > with Forrest. The customization of the HTML output also looks easier to > me. > > > > > > > Jeremias Maerki > > > That was my 2 cents, > Vincent Jeremias Maerki
