Re: [boost] Boost documentation

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 
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