Re: [Boost-docs] quickbook/boostbook relationship

Subject: Re: [Boost-docs] quickbook/boostbook relationship
From: Julian Gonggrijp (j.gonggrijp_at_[hidden])
Date: 2012-03-10 11:12:27

Robert Ramey wrote:

> I thought I understood this:
> 
> // docbook includes all the transformations to generate "general purpose" 
> documents
> // xslt transforms docbook elements to html or whatever.
> docbook xml ->xslt -> html or (fo ->pdf)  or ?..

That's probably correct. I'm not any more knowledgeable about all of 
this than you, but hopefully I can still help a little with some 
educated guesses from an outsider's perspective. :-)

> // boostbook adds a bunch of new elements specialized for C++ library 
> documentation
> // xslt transforms this to docbook elements.  The output of this 
> transformation can be used above.
> boostbook xml -> xslt-> docbook xml

BoostBook is described as an "extension" to DocBook, which makes me 
think that it's a variant of DocBook rather than some kind of 
preprocessor for it. So I'd expect that BoostBook xml is translated 
directly to html (through the BoostBook xslt sheet).

> // quickbook defines a new "more convenient syntax" for C++ library 
> documents
> // quickbook transforms this syntax to boostbook syntax to be used above.
> quickbook source -> quickbook -> boostbook xml.

Yes, but note that according to the QuickBook documentation it 
started out as a sample application for Boost.Spirit that produced 
html directly. It was adapted to be translated to BoostBook xml only 
later.

> OK this always made sense to me.
> 
> I look in the documentation for boost book xml and I find a lot of elements
> such as function, method, etc with a fairly elaborate structure   This also 
> makes
> sense since the object is to capture the "meaning" or "structure" of the 
> documentation
> (and by implication the library being documented).
> 
> BUT when I look a the quickbook syntax I don't find a correspondence between
> quickbook syntax and boost book xml definition.

So, I think this is because QuickBook was not originally designed as 
a "shorthand" for BoostBook.

>  For example in boostbook 
> one
> finds:
> 
> <function name="any_cast">
>  <type>void</type>
>  <parameter>
>        <paramtype>int i
>   </parameter>
> </function>
> 
> this is just the simplest example.  boostbook covers the whole C++ 
> declaration
> syntax.
> 
> I don't see how one would generate all this with the quickbook syntax.

I don't know either, but QuickBook seems to be dealing well with code 
nonetheless (importing, displaying, linking). Since it's smart enough 
to colour your syntax, I guess it may perhaps also translate your 
"plain" code into semantically structured xml.

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

Yes, QuickBook and BoostBook do seem to be totally different things.

> I would appreciated it if anyone who understands all this could shed some
> light on it for me.

Well I don't, but I hope it helped a little anyway.

-Julian