Eric Niebler wrote: I'm barely following this discussion b/c I'm in a time crunch, but as an avid Quickbook fan I think I should chime in...
I was the one who re-targeted Joel's QuickDoc/HTML to generate BoostBook/XML, added the Doxygen integration and re-christened it QuickBook. It was a quick hack so that I could write xpressive's docs. I
And thx for doing so, Quickbook has saved me much time over the last couple years especially writing standards proposals.
needed something that would let me write docs fast in a plain text editor, with cross-links to a reference section generated by Doxygen. I wasn't aware of any tool that fit that description. I'm still not. I see a lot of talk about XML editors. I don't want to edit XML, fancy editor or not. My personal preference is for plain text editors and simple mark-up.
Nor I. I've looked at various XML editors and always been bitterly disappointed -- they all stink as far as I'm concerned. I always wind up back at emacs. But even emacs with XML modes can't really overcome the problems with with XML. And trust me, I know, all the date-time docs are in BoostBook. It's really painful to edit them because the signal/noise ratio of XML is so low. And it's really hard to get nice looking C++ examples with richly colored text. What makes Quickbook so attractive is to me is that 1) it's signal to noise ratio is high (that is, little distraction from the actual content caused by the 'required structure'), 2) C++ code examples can be copied and pasted directly into text, 3) it supports easy hypertext linking, 4) since it's all simple text it means that regular version control and diff is very powerful for tracking changes, 5) it's editable in anything that can edit plain text, 6) I can get both html and pdf out the back.
I'm all for standardizing on DocBook. I'm also all for unifying the look-and-feel of the docs across all of boost. If we decide that all
Me too -- the irony being that it's mostly the DocBook toolchain that causes problems for people...
Boost docs must be in DocBook XML, that's peachy. But unless someone shows me a better way, I'll probably continue using QuickBook and Doxygen to generate the DocBook XML. I don't see why that's any cause for concern. After all, QuickBook is just a dumb translator. We can convert any QuickBook file into DocBook at any time -- no harm done.
I would be concerned if I saw a lot of people wasting time struggling with QuickBook. But the reality is quite the opposite -- I think it has been a real time-saver for people. So what is the problem?
Exactly...QuickBook is trivial to learn and use (partially because of it's simplicity and partially because the docs rock)...it's DocBook that took most of the struggle for me -- setting up the tools, writing a perl script to get rid of boost build and BoostBook xslt crud, etc. I agree that we can't can't/shouldn't force anyone to move to Quickbook and I even worry about BoostBook/DocBook. That said, so far our standard has been html. But html creates lots of problems in getting similar looking documentation (and pdf, of course) -- and I really think that's a big problem we (Boost) should solve. I think half of what makes PHP viable is good looking consistent docs - some Java docs really stink, but the common look and feel helps developers navigate large collections of libraries. Perl/Python...the list goes on -- all these languages/libraries have standard documentation systems to handle large sets of libraries. This lack of common feel in the docs I do think holds back C++ in comparison. For that reason alonge, as the premier place for C++ library development I think it's quite reasonable that Boost would push this envelope and set the standard. Anyway, I really think most developers that actually do the work of documenting something non-trivial in html or DocBook and then try Quickbook (Rest is likely similar) will be converts to Quickbook. And I think we should seriously consider upping the ante and requiring BoostBook/DocBook going forward so that we can get a unified look and feel. Jeff