On Fri, 2008-10-31 at 08:16 +0100, Hans Dockter wrote: > Hi, > > I think we should go with docbook.
Our emails were sent at roughly the same time -- you went ahead and got decisive as I was proposing :-) Whilst I think that LaTeX is still the best choice, making the move to DocBook/XML is far from being a stupid thing to do. > There are a couple of important reasons for this. It allows us to > provides our users an out-of-the-box way for generating the > documentation (vs. a high threshold for installing LaTeX). It also > allows us to integrate the user's guide into our continuous > integration. Just these two things are enough to justify a switch. > Docbook is a mature technology. Adam has figured already out how to > produce the formats we want. And Adam makes a valid point that we are > not a publishing house. Besides that the docbook to latex > transformation gives us always a way back to a LaTeX generated PDF > (for those who care and have a LaTeX installed). Toolchain issues are a string plus for DocBook/XML in the context where Java and Groovy are involved. I disagree about this issue of publishing house. Anyone writing documentation and creating representations of that documentation is a publishing house, in this case just a very small one. > I don't mind writing documentation in XML. In fact I would appreciate > the good tool support that comes in its wake. Sure there could be > better formats for doing this than XML but for our purpose it is > totally OK. LaTeX has good tool support as well, it is just slightly different. > The LaTeX to html transformation is a weak spot for LaTeX but very > important to us (more important than to a publishing house ;)). Adam > went through the big pains to make the LaTeX html generation from > useless to OK. I had never tackled this issue because I was afraid to > dive into this very time consuming and undocumented area of LaTeX. > And even after this huge amount of energy Adam has invested, there > are still flaws and significant limitations, which is frustrating. This is more a tex4ht that LaTeX issue, but the tex4ht documentation does look pretty rubbish. > We could start with the switch after the 0.5 release. Given the decision to switch has been made, that seems like a good plan. Depending of course when the 0.5 release goes out. Adam already has the DocBook/XML more or less in place already. Going with the LaTeX for 0.5 is the safer option though. One issue that will arise is which tool to use for editing DocBook/XML, you will need to be decisive on banning some tools since they reformat the XML without changing it. So for example using Emacs/nXML and XXE can cause versioning ping pong on format alone. (This is a problem for LaTeX as well, but I suspect the problem is more likely to arise with DocBook/XML.) -- Russel. ==================================================== Dr Russel Winder Partner Concertant LLP t: +44 20 7585 2200, +44 20 7193 9203 41 Buckmaster Road, f: +44 8700 516 084 London SW11 1EN, UK. m: +44 7770 465 077
signature.asc
Description: This is a digitally signed message part
