Re: [Boost-build] [boostbook] Building Boost documentation

From: Edward Diener (eldiener_at_[hidden])
Date: 2007-11-20 20:51:36

Ilya Sokolov wrote:
> Edward Diener wrote:
>> Ilya Sokolov wrote:
>>> Edward Diener wrote:
>>>> Rene Rivera wrote:
>>>>> Edward Diener wrote:
>>>>>> ...updating 1 target...
>>>>>> xslt-xsltproc-dir html\function-doc_HTML.manifest
>>>>>>
>>>>>>    set XML_CATALOG_FILES=..\..\..\bin.v2/boostbook_catalog.xml
>>>>>>   "xsltproc" --stringparam manifest "function-doc_HTML.manifest" 
>>>>>> --xinclude -o "h
>>>>>> tml/" "E:\Programming\Version 
>>>>>> Control\Subversion\Boost\tools\boostbook\xsl\html.
>>>>>> xsl" "..\..\..\bin.v2\libs\function\doc\msvc-8.0\debug\function.docbook"
>>>>>>
>>>>>> ...failed xslt-xsltproc-dir html\function-doc_HTML.manifest...
>>>>>> ...failed updating 1 target..."
>>>>>>
>>>>>> What does the failure mean ?
>>>>> That's weird. Usually programs tell you why things fail. Try running the 
>>>>> same commands in a shell to see if you get the same problem. Or if it 
>>>>> gives some useful errors.
>>>> Running:
>>>>
>>>> "xsltproc" --stringparam manifest "function-doc_HTML.manifest" 
>>>> --xinclude -o "html/" "E:\Programming\Version 
>>>> Control\Subversion\Boost\tools\boostbook\xsl\html.xsl" 
>>>> "..\..\..\bin.v2\libs\function\doc\msvc-8.0\debug\function.docbook"
>>>>
>>>> from the command line succeeds. 
>>> are you sure? how did you determine that? (i think i've seen exactly 
>>> this problem already)
>> By succeed I mean that it returns no errors to stderr or stdout and 
>> returns no error code of 1 or above.
> 
> Has it produced something?

There is no other output to stderr or stdout. It does look as if the 
xsltproc command is trying to write output to "html/" but my 
understanding is that the -o option is supposed to be a file but the 
option in the command line above points to a directory. Is that what is 
perhaps causing the problem ? Of course somewhere in the bowels of Boost 
Build the xsltproc command line is being generated so I have no idea why 
the -o option points to a directory rather than a file. There is nothing 
being output in the "html/" relative directory on my machine after 
xsltproc is run.

What is most annoying about Boost Build is that one gets back no idea 
why something is said to have failed. I find this a real weakness of 
Boost Build from the end user's perspective.

> BTW, error code may be less than zero on windows

That may be possible but I have no idea how to check if the errorlevel 
is less than zero in a cmd batch file.

> 
>>>> I have no idea why bjam would say it 
>>>> fails. What the command is supposed to do I do not know.
>>> 1. try "bjam onehtml"
>> What is that supposed to do ?
> 
>  From 
> http://boost.org/doc/html/boostbook/getting/started.html#boostbook.setup.running:
> 
> <quote>
> html     HTML output (multiple files). This is the default
> onehtml  HTML output in a single HTML file.
> </quote>
> 
> With metacomm' xsltproc installed, 'bjam html' (or just 'bjam') silently 
> fails for me, but 'bjam onehtml' works. Binaries from 
> http://www.zlatkovic.com/libxml.en.html work in both cases.

That "onehtml" worked ! Thanks ! However this points out the fact that 
something is still broken since without "onehtml" it gives the same 
error as before.

> 
>>> 2. try another xsltproc (e.g. http://www.zlatkovic.com/libxml.en.html)
>> I will give it a try, but this business of trying to setup and use the 
>> Boost documentation system, according to instructions, and failing to be 
>> able to do so, is getting old. I think Boost should either consider 
>> something better than this mess or get it working someday in this century.
>>
>> I did get the xsltproc directly from the link in the The BoostBook 
>> Documentation Format, and that link is at 
>> http://www.meta-comm.com/engineering/boost/xsltproc-win32.zip. Is that 
>> link's implementation of xsltproc broken perhaps ?
> 
> AFAICT, its purpose is to contain this old fix:
> http://mail.gnome.org/archives/xslt/2004-November/msg00030.html

'its' meaning the metacomm link ?

> 
> BoostBook docs should be updated to point to binary packages made by 
> Igor Zlatkovic, IMHO.

I will try those binaries instead, but if they are better than the 
metacomm link, then that metacomm link should have been updated or the 
metacomm distribution should have been updated to include fixes in the 
other implementation.

It is a real pain when someone like me tries to use the xsltproc in the 
documentation, it does not work, and everyone thinks that is par for the 
course and not important enough to be fixed, even for the next person 
who will run into exactly the same problem. It is understandable only in 
that the Boost developers are justifiably far more concerned about 
whether their code works rather than whether one can build documentation 
from their instructions. The only reason I, as an end user, wanted to 
build the code rather than wait for the next release, is because their 
were some interesting libraries in the latest Subversion head, whose 
documentation I wanted to read, but that documentation must be built.