Re: [Boost-docs] function.xml vs boostbook.dtd

Subject: Re: [Boost-docs] function.xml vs boostbook.dtd
From: Adder (adder.thief_at_[hidden])
Date: 2008-07-22 22:13:13

>> After un-commenting lines 27-36 of boostbook.dtd, xsltproc
>> successfully processes files that contain xi:include !

DJ> You can build the documentation now?

With those modifications to boostbook.dtd, I've got over the errors
I've mentioned. Indeed, I can build documentation for "function" and
other libraries that use <xi:include href="..." />.

If there are no problems with these modifications on other platforms,
I would humbly suggest they are committed.

Unfortunately, I am now stuck at a later point. As I didn't get any
pictures or links to other libs when building from
"trunk/libs/function/doc", I have moved to "trunk/doc" and run "bjam"
from that folder.

After 10 minutes of work, I got several repetitions of these error
messages ("cerr output"):

    runtime error: file file://...trunk/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl line 226 element element
    Variable 'actual-class-key' has not been declared.
    xmlXPathCompiledEval: evaluation failed
    runtime error: file file://...trunk/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl line 226 element element
    xsl:element: The attribute 'name' is missing.

The "cout output" was:

    xslt-xsltproc E:\Users\Adder\Projects\Libs\Boost\boost_SVN\trunk\bin.v2\libs\date_time\xmldoc\borland-5.5.1\debug\date_time_autodoc-xml.boostbook

        set XML_CATALOG_FILES=E:\Users\Adder\Projects\Libs\Boost\boost_SVN\trunk\bin.v2/boostbook_catalog.xml
     "xsltproc" --stringparam boost.doxygen.reftitle "Date Time Reference" --xinclude -o "E:\Users\Adder\Projects\Libs\Boost\boost_SVN\trunk\bin.v2\libs\date_time\xmldoc\borland-5.5.1\debug\date_time_autodoc-xml.boostbook" "E:\Users\Adder\Projects\Libs\Boost\boost_SVN\trunk\tools\boostbook\xsl\doxygen\doxygen2boostbook.xsl" "E:\Users\Adder\Projects\Libs\Boost\boost_SVN\trunk\bin.v2\libs\date_time\xmldoc\borland-5.5.1\debug\date_time_autodoc-xml.doxygen"

    common.copy ..\libs\date_time\xmldoc\date_time_autodoc.xml

        copy "E:\Users\Adder\Projects\Libs\Boost\boost_SVN\trunk\bin.v2\libs\date_time\xmldoc\borland-5.5.1\debug\date_time_autodoc-xml.boostbook" "..\libs\date_time\xmldoc\date_time_autodoc.xml"

    The system cannot find the file specified.
    ...failed common.copy ..\libs\date_time\xmldoc\date_time_autodoc.xml...
    ...failed updating 1 target...
    ...updated 1 target...

DJ> From the comment, it looks like Douglas Gregor didn't find the time to
DJ> work it out. I don't know if anyone here really understand DTDs. Maybe
DJ> we should look into the more recent schema languages, which are meant
DJ> to be simpler.

I have also heard that they ("XML Schema Definition") are more
expressive (than "DTD"), but I'm just a noob. For example, I have
tried to add "xmlns:xi CDATA #IMPLIED" to the list of allowed
attributes for <library>, but I still got the same "error" (more like
a warning)...

DJ> You could probably suppress the error with the '--novalid' flag.
DJ> Actually, I wonder if you've previously configured an XML tool to be
DJ> 'strict'? Maybe an environment variable or something like that?

Nothing of that kind.

>> I have unpacked the two xsltproc versions in separate folders; none of
>> them is in the PATH. I have xsltproc.bat in the path, redirecting to
>> the xsltproc.exe of my choice, which loads the .dll's from its own
>> folder.

DJ> You shouldn't need to do that - if you set xsltproc's location in your
DJ> user-config.jam it doesn't need to be in the path.

That was really just so that I can easily summon xsltproc for other
tasks, without adding its folder to the PATH.

IMHO, the instructions should be updated so that new users can get
started more easily.

--
Thank you again,
Adder