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

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


This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC