Re: [Boost-docs] Generating HTML files from BoostBook XML files

Subject: Re: [Boost-docs] Generating HTML files from BoostBook XML files
From: Daniel James (daniel_james_at_[hidden])
Date: 2008-09-15 18:43:28

2008/9/15 Boris <boriss_at_[hidden]>:
>
> As index.html refers to ./boostbook.css I understand that all HTML files
> need to be copied to boost/doc/html (at least I found boostbook.css there)?
> Is this something which is done by bjam automatically? If it is I guess I
> need to run bjam not in my doc directory but in BOOST_ROOT (and pass some
> arguments for bjam to understand only to build the documentation in
> boost/libs/foo/doc)?

No, and it's a little complex as different libraries do different
things. The documentation in doc/html is generated by running bjam in
the doc directory. This will first build the asio documentation, and
then the combined documentation for a number of libraries and tools
(this takes a long time).

The individual libraries' 'standalone' documentation can also be built
by running bjma in their documentation folder. Some of them are set up
to automatically copy the required files that they need - but some
will have broken links as we don't have a mechanism for linking to
files regardless of the location that they're built in. The main
reason for building standalone documentation is to test the library's
documentation without building the whole thing.

There are several libraries which always build their documentation
separately from the main documentation. These are built by running
bjam in their doc directory. They'll either already have the images in
place, or copy them explicitly in their Jamfile, they'll also set some
parameters in their jamfiles to specify the location of the css files
and some image files. I think John Maddock has done this very
successfully, so the TR1 library might be a good example.
'boost.root', 'boost.libraries' and 'html.stylesheet' are all
important parameters - all relative directories are relative to the
base of the generated documentation - the 'html' directory.

> I assume that if I run bjam from BOOST_ROOT I won't get any warnings anymore
> either that referenced libraries are not found (like "warning: Cannot find
> library 'Asio'" as I've used <libraryname
> alt="Asio">Boost.Asio</libraryname> somewhere)?

I think those library cross links will only work in the combined
documentation, if you're working on a submission to boost, the best
thing to do would be to link to the site, and then change the links if
your library is accepted.

> In my BoostBook documents I also refer to a PNG file (with <imagedata
> fileref="design.png"/>). While the img tag is generated in the HTML file the
> PNG file is not copied to the subdirectory html. Is there any support in
> bjam for referenced files like images or they need to be copied manually?

You can either link to the image file (relative to the html directory
- not the directory the generated file is placed in) or use an install
rule in your Jamfile to copy the file. If you have a look at the
bottom of 'doc/Jamfile.v2' you can see how it installs css and image
files. Note the dependency listed in the 'doc' rule (i.e.
'<dependency>css'), the install rule and the explicit rules - which
tells boost build to only install the files when they are asked for
(i.e. by the dependency).

Daniel