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"
> // 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
> // 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
> // 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
> sense since the object is to capture the "meaning" or "structure" of the
> (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
> <function name="any_cast">
> <paramtype>int i
> this is just the simplest example. boostbook covers the whole C++
> 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.
> words it looks like quickbook is "quick" because it skips a lot of the
> elements structure but maintains the formating - which is really quite a
> 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