Re: [boost] [ Boostbook - Quickbook ] Silly questions

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.