From: John Maddock (john_at_[hidden])
Date: 2007-06-16 05:06:42
Manuel Fiorelli wrote:
> Hi,
> finally I succeed in generating a documentation from a quickbook file
> (.qbk); however, I have some doubts about the correct procedure to
> do that. I use Fedora 7 and its prepackaged version of Boost but,
> unfortunately, it seems that there is nothing about Boost.build or
> BoostBoook. Thus, I downloaded the source distribution from Boost.org
> and untar it in my home directory where I also copied (and
> customized) the user-config.jam. Then, I downloaded the dtd and the
> xsl as stated from "getting started section". After that, I went in
> $BOOST_ROOT/doc and I succeed in regenerating doc through bjam --v2.
>
> My questions are:
> 1) is it possible to build a documentation outside the $BOOST_ROOT?
> if yes, what kind of jamfile / Jamroot is needed ??
Yes.
See
http://svn.boost.org/trac/boost/browser/sandbox/doc_test/doc/project-root.jam
and http://svn.boost.org/trac/boost/browser/sandbox/doc_test/doc/Jamfile.v2
for examples but ignore the experimental Jamfile options starting with "#
The page style" for now :-)
With the project-root.jam shown you need only set the environment variable
BOOST_ROOT to point to your main Boost tree to get things to work. At least
that's the general idea!
> 2) what is the minimal set of tools needed to build a documentation?
> Is it strictly necessary to download the entire boost distribution?
You need Docbook DTD and XSL, xsltproc (should be there already on Linux),
plus most of the contents of boost-path/tools. You can save some time in
rebuilds if you build quickbook in release mode and then add a:
using quickbook : some-path/quickbook ;
to your user-config.jam, but it's not essential to do this.
Doxygen is optional, as is an FO processor (for PDF output).
> 3) I noted that stylesheet and images miss from generated
> documentation. I suspect that it is due to the fact that these files
> are supposed to be there (since they are part of boost distribution).
> Is this correct?
Until now folks have had to copy these into the html sub-directory after the
docs are generated, however with current cvs you can just add
<xsl:param>boost.root=relative-path-to-boost ;
to the Jamfile and the docs will automatically pick up the Boost versions of
these under boost/path/doc. See the current Boost.Config docs in cvs for an
example of this in action.
HTH, John.