Re: [Boost-docs] QuickBook for non boost project

Subject: Re: [Boost-docs] QuickBook for non boost project
From: Daniel James (daniel_james_at_[hidden])
Date: 2010-01-15 00:06:00

2010/1/14 Bo Jensen <jensen.bo_at_[hidden]>:

> I am new to boost QuickBook and consider using it for documentation of
> a non boost project. It looks very nice indeed, but I have come across
> a couple of problems :

Out of curiosity, are you using as a nice way to write docbook, or for
boostbook's C++ support (or both?).

> 1) Image and css paths seems to be hard to replace. For html I ended
> up just fixing the paths with a notfile call that replaces all the
> paths with the correct one, which works fine and is okey with me.

notfile? Is that a boost build thing?

> But
> in pdf files problems arise, because it fails with trying to fetch my
> images from a url...how do I correct this ?

As you might have guessed I don't know what I'm talking about here,
but John Maddock fixed my documentation by adding this parameter:

    <format>pdf:<xsl:param>img.src.path=../

The value of img.src.path should be the location of the directory that
image paths are relative to.

The other thing you can do is use docbook to treat print and html
differently. This is what I use for the unordered library (again based
on something by John):

[template diagram[name]  '''<inlinemediaobject>
<imageobject role="html">
<imagedata align = "center"
fileref="../../libs/unordered/doc/diagrams/'''[name]'''.png"></imagedata>
</imageobject>
<imageobject role="print">
<imagedata align = "center"
fileref="../../libs/unordered/doc/diagrams/'''[name]'''.svg"></imagedata>
</imageobject>
</inlinemediaobject>''']

I did that to use the svg file for printing, but I guess you could
also use different paths for the html and print image objects.

It's a pretty good idea to look at how John's written and is building
his documentation, as he has put a lot of effort into getting things
right.

> 2) How can I control where the pdf output files get located ? is there
> some kind of install command call I can make ?

Here's an example that will install the pdf in the current directory,
change '<location>.' to specify the target that you want. Then use
'bjam unordered_pdf'.

    xml unordered : unordered.qbk ;
    boostbook standalone : unordered ;
    install unordered_pdf : standalone/<format>pdf : <location>. ;
    explicit unordered_pdf ;

The explicit rule is there so that it's only installed when the target
is explicitly named.

Daniel