[Boost-docs] quickbook/boostbook relationship

Subject: [Boost-docs] quickbook/boostbook relationship
From: Robert Ramey (ramey_at_[hidden])
Date: 2012-03-09 23:05:57

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

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

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

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

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

Robert Ramey