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

Subject: Re: [Boost-docs] QuickBook for non boost project
From: Bo Jensen (jensen.bo_at_[hidden])
Date: 2010-01-15 01:01:26

On Fri, Jan 15, 2010 at 1:06 AM, Daniel James <daniel_james_at_[hidden]> wrote:
> 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?).

I just intend using QuickBook straight out for my documentation for a
small software company.

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

It just call a scripts at every build, which fixes paths in all html files.

>
>> 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=../

Thanks this was actually useful to me and fixes the image path issue.

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

Thanks I will have a look later, when time permits.

>
> The explicit rule is there so that it's only installed when the target
> is explicitly named.
>
> Daniel
> _______________________________________________
> Boost-docs mailing list
> Boost-docs_at_[hidden]
> http://lists.boost.org/mailman/listinfo.cgi/boost-docs
>