From: Jeff Garland (jeff_at_[hidden])
Date: 2007-06-24 22:46:02
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
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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk