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

Subject: Re: [Boost-docs] [quickbook][boostbook] CSS & image files
From: Daniel James (dnljms_at_[hidden])
Date: 2010-06-30 10:45:01

On 30 June 2010 10:59, Paul A. Bristow <pbristow_at_[hidden]> wrote:
>
> I've just started to try to comply with this with projects in development but I'm confused again.

This is mainly for libraries in the boost repository, not for sandbox
libraries. The main change there is that if you copy the css or images
from the main boost repository you'll need to do it from 'doc/src/'
(which you should have been doing anyway, but it wasn't really
explained anywhere). None of the applies to images from your own
documentation, just to the shared images. I'm just 'src' directory
name because that's where they currently are, if I was starting from
scratch I'd use a better location.

> 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?  And also all the svg equivalents (mostly - some of the Quickbook ones are missing - shall
> I convert the .png with Inkscape and add them?).

Yes. Although at least some of the images under doc/html will probably
have to remain for now as some of the documentation uses them
explicitly. What's missing?

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

No, it's set by the 'boost.image.src' parameter. In the main boost
tree it defaults to $boost.root/boost.png (because of the
'<xsl:param>boost.defaults=Boost' parameter in Jamroot). Outside
you'll have to set it explicitly if you want to use it.

> I'm also uncertain about how to deal with my own  images, say "my_image.svg".  (however ugly that might be! ;-)

So am I. Because of the way docbook works the easiest thing to do is
to copy them into a subdirectory of html. To correctly use images in a
location independent way would probably require extra support in our
xsl. Maybe using something like the 'boost:' links (which don't work
for images) but which also supports urls from sandbox repositories.

Modularisation of boost also plays into this. The ideal would be to
implement a url scheme to link to a file in a module, and then
implement this so that it uses an appropriate link according to the
context. But we don't know how or if modularisation is going to
happen.

I think I made a mistake by implementing the 'boost:' links in the
boostbook to docbook conversion. Steven originally implemented
something like it for the boostbook to html stage, but I moved it to
the boostbook to docbook state so that it'd only have to be
implemented once for all generated documentation. But we only really
know how the links should be converted when we know how the final
documentation is going to be generated. And we probably do want a
different implementation for generating pdfs to generating html, so
Steven's original approach seems better to me.

A possible url scheme would be something like:

module:x.png (relative link, no real reason to use this)
module:/libs/foo/images/x.png (absolute link in the current module)
module://foo/libs/foo/images/x.png (absolute link to the named module)

That url scheme won't work if module names could have slashes in them
(which they currently do). So it could use a different separator. It'd
also perhaps be something that could be used outside of boostbook, eg.
for html or docutils based documentation.

But that's a bit of a tangent, for now you just have to muddle
through. You can either copy the images into your html directory, or
use a relative link from the html directory.

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

No, probably not. In my example in the sandbox I'm still copying the
images into the html directory. The boostbook defaults are set up so
that in the main boost repository it uses images and css from
doc/src/, but outside it still uses the from the html directory. The
jamfile is at:

https://svn.boost.org/svn/boost/sandbox/example/libs/example/doc/Jamfile.v2

To use your own boost logo, you need to add something like:

    <xsl:param>boost.image.src=../../../../not-yet-boost.png

> Is Quickbook [$ my_image.svg] syntax   'hardwired' to expecting images in doc/html/  ?

It's not even wired, it just passes the url through and that's what it
ends up as.

Daniel