[boost] [boostbook] First experiments

From: Guillaume Melquiond (guillaume.melquiond_at_[hidden])
Date: 2007-06-07 07:54:08

Hi,

I am trying to convert the interval library HTML documentation to the
BoostBook format. I will describe my experience with it, as it may help
improve BoostBook and its documentation.

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. The
documentation should stress that, if the user does not modify the
user-config.jam file, bjam (or at least the jam files) will crash with
hundred of lines of nonsensical warnings. Would it be possible to get
some clearer message? Actually, the only important line is "using
boostbook", as bjam does not seem to mind if the other lines are
missing.

Concerning "using boostbook", having to specify the directories is a bit
annoying. As a regular user of DocBook, my catalog files for DocBook are
already properly configured and BoostBook should not override them with
its own version.

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.

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.

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?

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.

The documentation states that the list of library categories is in the
file src/boost.xml. I can't find this list. 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?

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.

Best regards,

Guillaume