Re: [Boost-docs] [quickbook][boostbook] CSS & image files

Subject: Re: [Boost-docs] [quickbook][boostbook] CSS & image files
From: John Maddock (boost.regex_at_[hidden])
Date: 2010-06-30 10:55:17

>> At the moment we have copies of the css and image files for boostbook
>> in doc/html and doc/src which is a bit messy. I'd like to remove one
>> of these. I'd prefer to remove the files under html, so that directory
>> would only contain the generated documentation.
>
> I've just started to try to comply with this with projects in development 
> but I'm confused again.
>
> Are we talking about Boost_trunk/doc/src/  with boostbook.css  and /images 
> containing home.png, next.png ... smiley.png,
> alert.png used by Quickbook?

Yep, and yes we really should fold all these into one master copy or each.

> I note that boost.png is NOT here.
>
> And I'd also like my own 'Not yet Boost' logo, instead of boost.png.  So 
> where do I put it?
> libs/my_stuff/doc/src/images/?

Wherever you like under libs/my_stuff/doc, I forget what it is, but there is 
an xsl:param to set the location.

> I'm also uncertain about how to deal with my own  images, say 
> "my_image.svg".  (however ugly that might be! ;-)
>
> Should they go at libs/my_stuff/doc/src/images/?  But won't (all) this 
> mean that you can't just zip the html folder to
> package the complete docs for some library?

That's an issue yes.

> Do I need something like
>
> # install html : ../../../doc/html/boostbook.css ; # Boost style sheet.
> # install ../../../boost.png ; # Boost standard reviewed logo.
> # install  navigation and admons...
>
> to make sure that the final /html folder contains everything?

Or just add doc/src to your zip as well.

> Would it be better to refer all the image requirements to boost_root (but 
> when I've tried to use absolute references it
> didn't work - I suspect that I haven't read the instructions for Windows 
> users to specify URI carefully enough).
>
>  # Path for links to Boost:
>  #<xsl:param>boost.root=\$(local-boost-root) # Link to Boost logo 
> boost.png
>  # Links are relative by default, so preceed by \ to make absolute.
>  # But doesn't seem to work :-(

When I've needed an absolute path, I've always used the path-constant rule, 
for example in the Boost.Math docs we use:

path-constant images_location : html ;

> Most important I want to reference these as [$my_image.jpg] in 
> Quickbook, - just like that with no \src prefix.
>
> Is Quickbook [$ my_image.svg] syntax   'hardwired' to expecting images in 
> doc/html/  ?
>
> Or can I point it somewhere else using the jamfile?
>
> Or does this control it, perhaps with
>
> <xsl:param>img.src.path=..\src\images

That should get it yes.

HTH, John.