Re: [boost] [boostbook] First experiments

From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2007-06-07 10:42:25

Guillaume Melquiond wrote:

> As I am a user of DocBook, I already have a proper installation of
> DocBook. So I didn't want to run the automatic setup script.

Neither did I :-) Because I wanted to use all the latest versions of 
stuff. The unfortunate part is that for Windows I *have* to use the old 
patched xsltproc.

> Concerning "using boostbook", having to specify the directories is a bit
> annoying.

I just use:

using doxygen ;
import xsltproc-config ;
import boostbook-config ;
import quickbook-config ;

> The documentation should point that BoostBook is not compatible with the
> recent releases of DocBook (4.3, 4.4, and 4.5), as it redefines the code
> element and its id and last-revision attributes.

I still manage to use docbook 4.5. I just ignore the warnings about the 
overridden code element.

> Running BoostBook creates a bin/mycompiler-version/debug directory.
> Perhaps it is an intrinsic defect of bjam. But if it is not, it would be
> great if BoostBook could avoid using a directory that depends on the
> compiler currently used.

Yea. That one's on our TODO list.

> While a bin/.../debug directory has been created, it is not used to
> store the main Doxygen-generated .xml file. This file is directly stored
> amongst the documentation files. Moreover, an additional bin/.../debug
> directory is created there, in order to store all the other temporary
> Doxygen files. Is it possible to get all the generated files stored in
> the same place instead of polluting the original documentation
> repositories?

If I understand you correctly, that's what we currently do. So you are 
likely not using the CVS HEAD version of the code.

> As BoostBook does not seem to be usable without bjam, the documentation
> should at least contain a sample jam file and explain the parameters of
> the boostbook and doxygen rules. And if it is usable without bjam, the
> documentation should explain how.

Yea, good point.

> The documentation states that the list of library categories is in the
> file src/boost.xml. I can't find this list.

Hm, I see a boost-root/doc/src/boost.xml.

> There are only the examples
> given by the existing libraries. Does the documentation means that I
> should find a related library and copy its library category?

It seems like that's what it want :-\

> To conclude this mail, let me say that it took me six hours from the
> moment I decided to start a BoostBook documentation to the point I had
> finally generated an empty documentation including Doxygen references.
> In my opinion, the delay for getting started is a bit too long.

Lucky you... First time I tried this on Windows it took me a week ;-)

-- 
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo