Re: [Boost-docs] quickbook/boostbook relationship

Subject: Re: [Boost-docs] quickbook/boostbook relationship
From: Robert Ramey (ramey_at_[hidden])
Date: 2012-03-18 19:30:03

Daniel James wrote:
> On 9 March 2012 23:05, Robert Ramey <ramey_at_[hidden]> wrote:
>>
>> I don't see how one would generate all this with the quickbook
>> syntax. In other
>> words it looks like quickbook is "quick" because it skips a lot of
>> the boostbook
>> elements structure but maintains the formating - which is really
>> quite a different
>> thing than boostbook.
>
> Quickbook doesn't have any support for writing boostbook reference
> documentation, most people write it using doxygen, write it directly
> in boostbook, or write it in quickbook. Quickbook does have support
> for linking to boostbook reference document (funcref, classref etc.)
> so it integrates well with it and isn't just a docbook generation
> tool.
>
> AFAIK there's no one has ever expressed any desire for writing
> boostbook reference documentation in quickbook, I don't think it'd be
> a particularly good match. It might be possible to do something using
> escaped boostbook and templates.

Thanks for your response.  I've become quite interested in ways to make
effective documentation simpler to generate and more useful.

Soooo, just to make sure I understand all this more or less correctly.

a) In the beginning there was DocBook
b) Doug Gregor made BoostBook as DocBook with an extra layer
of sauce for detailed specification of functions, classes, member
functions, etc.
c) A couple of libraries have used BoostBook directly. Any, DateTime
but those don't seem to use all the detail that BoostBook has.
d) Joel Guzman made quickdoc as a quick way to generate HTML
from a simpler mini-language
e) Eric Neibler used this to make quickbook which generates BoostBook.
The generated BoostBook doesn't included all the BoostBook "detail"
because the quickbook mini-language doesn't have a syntax to specify
it and also because no one seemed suffiiciently interested to do this
because 1) It's a pain the butt, and 2) no other tools rely on or exploit 
it.
f) Doxygen has been used to generate XML which is then processed
using xsltproc to BoostBook which is then linked into the quickbook
generated documents.

I think that's how things are and how they got to be this way.

Which is OK.  Since the de-facto canonical form of boost documents is HTML
it really doesn't matter how one get's here.

So I think I understand the whole process.  There are a number of things
I don't like about it, but that would be going off topic

Thanks for answering my question.

Robert Ramey