[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

 


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