Re: [boost] [Boost-docs] [quickbook] Thank you Daniel James

Subject: Re: [boost] [Boost-docs] [quickbook] Thank you Daniel James
From: Eric Niebler (eniebler_at_[hidden])
Date: 2014-06-04 17:18:12

On 06/04/2014 08:51 AM, Daniel James wrote:
>>> Forgive the stupid question, but why does quickbook generate boostbook
>>> >> xml, which then generates html, instead of quickbook generating html
>>> >> directly?
>>> >>
>> >
>> > Not a stupid question.. Just a historical one. The precursor to quickbook
>> > did generate HTML directly. It was "ported" to generate docbook to have it
>> > integrate into the then newish Boost documentation toolchain based on
>> > docbook in order to simplify doc writing with a simpler wiki like syntax.
> Yes, boostbook markup is hard-coded into a lot of places.
> 
> I had a crude html generator in the abandoned spirit 2 branch, I think
> it's the only feature I didn't backport. It could do a passable job of
> simple markup, but for complicated documents it wasn't much use.
> Especially for documents which use doxygen, as that is used to
> generate boostbook. I felt it was more useful to concentrate on
> improving the language.

I was the one who took Joel de Guzman's QuickDoc tool, which generated
HTML, re-purposed it to generate BoostBook XML, and rechristened it
QuickBook. It has been terrifically useful, and other have run with it.
As others have pointed out, the Docbook toolchain is powerful. Escaping
to BoostBook/Docbook XML is a great way to Get Things Done when
QuickBook doesn't offer a pithy syntax. And as Daniel points out,
Doxygen generates XML which can be integrated with the XML spit out by
QuickBook, allowing you to easily link from your user docs to your
reference and (with some difficulty), the reverse.

It's ugly and round-about, and it cries out for a better solution, but
it's the best we've got, and it gets the job done.

Eric