In article <[EMAIL PROTECTED]>, Brian Heinrich wrote: > On Tue, 18 Jun 2002 13:55:38 +0100, it is alleged that Gervase Markham ><[EMAIL PROTECTED]> swaggered in to netscape.public.mozilla.documentation and > announced: > >>Bugzilla uses DocBook for our documentation, and we find it a pain in >>the arse a lot of the time. Setting up the tools on Unix is non-trivial, >>even for a modern distro. I've never seen working tools on Windows at >>all. The HTML output from the standard transform looks ugly. Like all >>XML, it's really picky about what tags you can nest in what. >> >>Only use DocBook out of the box if you are either a) happy to spend the >>rest of your life translating other people's documents into DocBook >>again and again, or b) want to vastly raise the barrier to contributing >>documentation. I think you assertion that getting things marked up isn't >>a problem is extremely optimistic. > > So what are the alternatives? For on-site documentation, I suspect DocBook > (<disclaimer>with which I am not familiar</disclaimer>) is a bit of over-kill. > IIRC, Docbook was originally suggested in re. Help, where XML seems to make > sense in generating final documents.
Out of curiousity, has anyone thought about producing a docbook.css? If these are viewed-in-Mozilla-only help files, it might make sense to do a minimum of conversion (break a single big doc. w/ TOC and sections into one-file-per-section) and then view it as untransformed XML with CSS. As far as ease-of-contribution, I very much like the idea of DocBook as a format, but Gerv is correct in that getting contributions of *valid* DocBook will be very very hard. Are there any HTML-Tidy-like scripts for DocBook? > On-site documentation would seem to be going the Zope --> CVS route (Dawn is > pretty insistent on wanting CVS blame, tho' I have only the foggiest of just > what that means). > CVS blame, AFAIK, lets you view who changed what parts of what files, and when. -- Chris Hoess
