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

Subject: Re: [Boost-docs] [quickbook][boostbook] CSS & image files
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2010-07-10 17:30:46

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of John Maddock
> Sent: Saturday, July 10, 2010 11:00 AM
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] [quickbook][boostbook] CSS & image files
> 
> >> 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 ;
> >
> > OK I've tried this, and echoing it says
> >
> > images_location
> > I:\boost-sandbox\tools\quick_auto_dox_index\libs\quick_auto_dox_index\doc\html
> >
> > as expected.
> >
> 
> > So in my jamfile I have (to get the location of my images for both html
> > and pdf)
> >
> > <xsl:param>img.src.path=$(images_location)/
> >
> > In my Quickbook I have
> >
> > [$my_image.jpg]
> >
> > but I don't get the image displayed and the image info (split to avoid
> > word wrap) is
> >
> > i:%5Cboost-sandbox%5Ctools%5Cquick_auto_dox_index%5Clibs%5Cquick_auto_dox_index
> >
> > %5C doc%5Chtml/
> >
> > ../my_image.jpg
> >
> > There seems to be a (to me) unexpected (and unwanted) ../ before
> > my_image.png
> >
> > (and of course the confusing %C is caused by nasty Windows backslashing
> > :-(  )
> >
> > So it doesn't display the image even if my_image.png is at /doc/html
> > and/or /doc/ :-(
> >
> > Is this a valid file specification?  Windows explorer says "The file name
> > is not valid."
> >
> > So what am I doing wrong?  Or is the Quickbook call causing this?
> 
> OK, first things first... you can't use the same path for PDF and html
> generation: PDF's will want absolute paths so that regardless of where the
> PDF actually gets built (in some deep directory known only to Boost.Build)
> the FO processor will still be able to find the images. 

> HTML files will want a relative path with all forward /'s so they act as relative URL's.

OK I suspected this, and it's usual, though I'm not clear why an absolute path is not allowed

http://docbook.sourceforge.net/release/xsl/current/doc/html/img.src.path.html says:

"img.src.path   Description

Add a path prefix to the value of the fileref attribute of graphic, inlinegraphic, and imagedata elements. The resulting
compound path is used in the output as the value of the src attribute of img (HTML) or external-graphic (FO).

The path given by img.src.path could be relative to the directory where the HTML/FO files are created, or it could be an
absolute URI. The default value is empty. Be sure to include a trailing slash if needed.

This prefix is not applied to any filerefs that start with "/" or contain "//:".
"
And this works OK ...

path-constant nav-images : $(local-boost-root)/doc/src/images/ ; # png and svg images for home, next, note, tip...
nav-images I:\boost_trunk\doc\src\images             <<<<<<<<<<<<<  an absolute reference seems OK.
<xsl:param>nav.graphics.path=$(nav-images)/ # Navigation graphics.
file:///I:/boost_trunk/doc/html/images/next.png

But that's not the main problem.

> I'm not sure where the extra .. is coming from in your paths - probably from
> the xslt stylesheets - according to their docs you should set img.src.path
> to be relative to the location of the html files (by default ./html).

So I've got my blunderbuss out and tried everything I can think of to try to understand what is going on :-(

<xsl:param>img.src.path=images
file:///I:/boost-sandbox/tools/quick_auto_dox_index/libs/quick_auto_dox_index/doc/html/quick_auto_dox_index/images../my_
image.jpg

Unexpected ..  after/ images !  (and I thought it should be /doc/html/ ?)

<xsl:param>img.src.path=/images
file:///images../my_image.jpg

<xsl:param>img.src.path=./images/
file:///I:/boost-sandbox/tools/quick_auto_dox_index/libs/quick_auto_dox_index/doc/html/quick_auto_dox_index/my_image.jpg

<xsl:param>img.src.path=./images
file:///I:/boost-sandbox/tools/quick_auto_dox_index/libs/quick_auto_dox_index/doc/html/quick_auto_dox_index/my_image.jpg

Neither of these add /images - they add /quick_auto_dox_index instead ???

<xsl:param>img.src.path=../images
file:///I:/boost-sandbox/tools/quick_auto_dox_index/libs/quick_auto_dox_index/doc/html/images../my_image.jpg

Now we have /images - but with trailing ..

<xsl:param>img.src.path=../images/
file:///I:/boost-sandbox/tools/quick_auto_dox_index/libs/quick_auto_dox_index/doc/html/my_image.jpg

NO /images (But works if images are in /html - but not the expected sub-folder /html/images/)

<xsl:param>img.src.path=../../images/
file:///I:/boost-sandbox/tools/quick_auto_dox_index/libs/quick_auto_dox_index/doc/my_image.jpg

No /images (although works if my_image.jpg is in /doc - but not the expected sub-folder /html/images/).

<xsl:param>img.src.path=../
file:///I:/boost-sandbox/tools/quick_auto_dox_index/libs/quick_auto_dox_index/doc/my_image.jpg

Produces same as ../../images/

<xsl:param>img.src.path=../../images
file:///I:/boost-sandbox/tools/quick_auto_dox_index/libs/quick_auto_dox_index/doc/images../my_image.jpg

Unexpected /.. again (so not a valid filename) but the /images is there OK.

All this has left me more than usually confused :-(

Am I missing something obvious or should I give up trying to control this path this way?

Or look into the XSLT 'in the middle' to see what is going on?

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal, UK   LA8 8AB
[phone], mobile [phone]
pbristow_at_[hidden]