Re: [Boost-docs] Problem building documentation from quickbbook to html using xslt under Windows

Subject: Re: [Boost-docs] Problem building documentation from quickbbook to html using xslt under Windows
From: Edward Diener (eldiener_at_[hidden])
Date: 2015-11-18 00:32:05

On 11/17/2015 6:36 PM, Daniel James wrote:
> On 17 November 2015 at 22:39, Edward Diener <eldiener_at_[hidden]> wrote:
>>
>> In the process of building my source from quickbook to boostbook to docbook
>> to HTML an XML file is generated which has the path to my VMD library's
>> reference file as one of the sections of my documentation. The line in
>> vmd.docbook is:
>>
>> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
>> href="E%3a/Programming/VersionControl/modular-boost/libs/vmd/doc/vmd_reference.xml"/>
>>
>> The xsltproc is called with the full path to vmd.docbook to transform this
>> XML file:
>>
>> xslt-xsltproc.windows
>> C:\Programming\VersionControl\modular-boost\build\boost\bin.v2\libs\vmd\doc\gcc-mingw-5.1\debug\vmd.docbook
>>
>> The result, however, is an xslt error because xslt does not recognize the
>> '%3a' as a colon ( : ) and so I get:
>
> In URLs the colon is a separator between the schema and the path, so a
> windows path like E:\path' is interpreted as a URL with the schema
> 'E', which wouldn't work. That's why the href has to be something like
> 'file:///E:/Programming/....'. So I guess the fix is to add support
> for this URL syntax to quickbook, or perhaps to use relative paths
> (tricky because it isn't clear where the build is going to be done
> from).

Thanks for catching that ! Then the bug is in generating an invalid URL 
somewhere in the Boost build process by a Boost build tool.

> What does the boostbook file look like?

What do you mean by "What does the boostbook file look like?" ? Do you 
want me to list the entire vmd.docbook ? It's pretty large, some 7691 
lines. I could of course put it on pastebin.

I am just using quickbook .qbk file and a doc jamfile.v2, along with my 
local user-config.jam, for converting my quickbook files to HTML and 
PDF. All of the intermediate files are created by the Boost build bjam 
process running against my doc's jamfile. You can see my VMD doc's 
jamfile in the VMD source in the VMD doc subdirectory.

The sequence of building as I understand it from the jamfile is that the 
'doxygen' tool builds the XML reference file from my doxygen source 
comments, called in this case 'vmd_reference'. Despite my 
'--build-dir=C:\some_directory' this file is built locally in my VMD 
source's local doc directory and not within my build directory path. 
Then the 'xml' tool takes my quickbook files and the vmd_reference as a 
dependency and creates a vmd.xml within my build directory path. Here I 
can see the URL error since there is the line:

<xi:include 
href="E%3a/Programming/VersionControl/modular-boost/libs/vmd/doc/vmd_reference.xml"

in the vmd.xml with the incorrect URL path. So I think the bug is in the 
Boost build 'xml' tool. From vmd.xml the bug gets propagated into 
vmd.docbook by the 'boostbook' tool.

I think this is the sequence but you may know better. if it is it 
appears that the Boost build 'xml' tool is at fault when it combines the 
quickbook files and doxygen reference file into the vmd.xml file.