Re: [boost] Boost documentation

From: Joel de Guzman (joel_at_[hidden])
Date: 2007-06-24 08:24:42

Cédric Venet wrote:
>> De : Guillaume Melquiond
>>
>> Le dimanche 24 juin 2007 à 11:04 +0200, Cédric Venet a écrit :
>>> The fact is if one day, quick book is broken and not supported
>> anymore, you
>>> just have to use the last correct version to convert your quickbook
>> doc into
>>> docbook and work on the doc book.
>> As far as I understand it, a short term goal of the quickbook
>> developers
>> is actually to get rid of the conversion to boostbook/docbook. So it
>> won't be as easy as you make it sound to get back to a docbook version.
> 
> Yes, I remember something like this.

No, "get rid" is too strong a term. The real goal is to provide
alternative back ends (e.g. direct HTML, LaTEX, DocUtils,  etc.,
in addition to DocBook). This can be achieved through a set of
back end template libraries. And, no, I don't think it is a short
term goal. The short term goal is to simplify quickbook a lot
more than it is now (a targeted 90% reduction in c++ code size)
by moving to template libraries. We'll end up with a standard
template library with 90% of the functionality of quickbook
plus a set of intrinsics in c++ code. *** We're actually
striving to make quickbook simpler, not more complex ***

Why? some people, do not like the elaborate tool chain that
Doc/BoostBook requires. Some parts of the tool chain, e.g. FOP,
is severely broken, XSLT is so slow and difficult to understand
and maintain, etc. DocBook is not perfect, you know. It too has
its own sets of problems.

>> Please correct me if docbook is still intended to be a mandatory
>> intermediate stage between quickbook and html/pdf documentations.
> 
> I can't speak for quickbook developers, but it could be useful to have a
> backend in boostbook or docbook, even if it is not anymore used as an
> intermediate stage. This involve some development cost, but à priori not too
> much. It could be useful if someone want to use a custom xslt for his doc
> (in case of use outside boost, since they try to make a common L&F for
> boost) or for the sake of having a standardized xml backend.
> 
> After it depend on the scope of use they want to give to quickbook.

A boost/docbook backend will still be supported, for sure. Backward
compatibility is a paramount concern. Most (all?) quickbook documents,
except the most simple ones rely on DocBook. As soon as you start
"escaping" to DocBook, you become dependent of it. AFAICT, there is
no way to break free of that dependency without sacrificing backward
compatibility.

Regards,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net