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

From: Stjepan Rajko (stipe_at_[hidden])
Date: 2007-06-15 17:34:17

Hi Manuel,

On 6/15/07, Manuel Fiorelli <manuel.fiorelli_at_[hidden]> 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 have recently also learned to use these tools to some degree.  My
answers might not be the best procedure, but maybe they will be
helpful...  Anyway, maybe we will both learn something if the experts
comment:

> 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.  I don't know what is absolutely needed but the following works
with Boost.Build that is in the CVS HEAD (I have scavenged these files
from other boost projects):

In the root directory of your project:

a project-root.jam file with contents (exact, i.e., you don't have to
substitute anything for BOOST_ROOT as long as you have that
environment variable set):

import os ;

path-constant BOOST_ROOT : [ os.environ BOOST_ROOT ] ;

This seems to take in the system environment variable BOOST_ROOT and
makes it available to bjam.

...In the same place, a boost-build.jam file with contents:

boost-build $(BOOST_ROOT)/tools/build/v2 ;

That seems to point to boost build 2.

What I have, then, is a Jamfile that says (this might only be
necessary if you are also building code that uses boost)

use-project boost
   : $(BOOST_ROOT)
   ;

project boost/my_library
   : build-dir bin.v2
   ;

... and a few directories underneath, the Jamfile for the actual documentation.

> 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?

Wherever your docs end up, you might need to place the css files and
stylesheets there yourself.  Most of the out-of-boost-distribution
projects I've looked at have the docs/html directory with the
stylesheets already there, and docs/html/images with the images.  When
the docs get generated in the html directory they work with the
stylesheets and images that have been placed there.

HTH,

Stjepan