Re: Switching to DocBook [was: svn commit: r960618 [1/3] - in /xmlgraphics/fop/branches/fop-1_0]
I spent time on the documentation in three ways: 1. Updating the links from 0.95 to 1.0 and from 0.94 to 0.95. This can be avoided if we call the directories 'latest' and 'previous'. 2. Updating the compliance page. I did this with emacs regexes, but they are tricky. I think the setup of the page needs to be changed to make it scriptable. 3. Updating the documentation. Some documentation is well maintained between releases, other documentation is left to become outdated. This will always be a problem. In this release I am trying to make a slight paradigm shift: Forget about 0.20.x, it is too far in the past (but Pascal just wrote that there are still questions about it). Such changes will always occur and take time. I would call it pre-release work rather than part of the release build. I cannot see if Docbook documents would be easier to maintain. It would certainly get them out of the web site structure, which may encourage people to modify them without fear to get tangled in structural problems. An effort to script the release build, including modifying the documentation automatically as much as possible, will reveal how difficult and time consuming a release really is, apart from pre-release work like updating the README, news, and taking a good look at other documents. Simon On Tue, Jul 06, 2010 at 10:08:13PM +0200, Jeremias Maerki wrote: > 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. -- Simon Pepping home page: http://www.leverkruid.eu
Re: Switching to DocBook [was: svn commit: r960618 [1/3] - in /xmlgraphics/fop/branches/fop-1_0]
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: > > >> 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
Re: Switching to DocBook [was: svn commit: r960618 [1/3] - in /xmlgraphics/fop/branches/fop-1_0]
Hi, Jeremias Maerki wrote: > On 05.07.2010 17:13:32 Simon Pepping wrote: >> 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
