Re: [Boost-docs] Boostbook DTD clash

Subject: Re: [Boost-docs] Boostbook DTD clash
From: Daniel James (daniel_james_at_[hidden])
Date: 2008-12-02 21:19:37

2008/12/2 Paul A. Bristow <pbristow_at_[hidden]>:
>
> But I am unclear what effect this has when my user-config.jam has the
> version specified (and clearly uses this rather than the version 4.2
> previously specified because the warnings appeared before I changed the line
> above from 4.2 to 4.5:

There's a good chance that you were never using 4.2. Boost build
creates 'bin.v2/boostbook-catalog.xml' which contains a rewrite for
the 4.2 url. It rewrites it to the path given in your user-config.jam,
or the one detected by 'boostbook-config'. If it's setup to use a
local copy of the a different version's dtd, you'll be using the wrong
dtd. Also, boost build doesn't regenerate the file when you change
your settings, so if you change user-config.jam you also need to
delete the file. So it's quite easy to use the wrong version.

I think that requiring the full versioned path in user-config.jam
might have been a mistake. But fixing it would require everyone to
change their setup as most of the documentation setup instructions
don't install it into a '4.2' path.

> What should I do now?

OK, I've been looking into it. I was worried before about updating the
dtd correctly, but it turns out that it's already pretty messed up.
According to the dtd file, its uri is
"http://www.boost.org/tools/boostbook/dtd/1.1/boostbook.dtd", but
there was never anything there, the dtd is still in the 1.0 location
(actually, it isn't - the new website redirect to another location
which returns a 404 error). And consequently all the boostbook
documentation files still use a 1.0 doctype.

So there isn't much point in worrying about getting that right now.
I'll look into fixing it in the future.

There is a small problem with moving to 4.5. It isn't packaged in
debian stable and cygwin, and I've been trying to use their package
systems to make installation simple so I would prefer 4.4, the
additions in 4.5 don't seem that useful.

As well as updating the dtd, we'll also need to update the build
system (tools/build/v2/tools/boostbook.jam and
tools/build/v2/tools/boostbook-config.jam I think) and update the
various tool documentation pages. I can help with this if needed.

We'll also need to ask everyone to update their setup, an email to the
documentation list as the change hits trunk should be fine. And then a
note in the release announcement. But there might not be any real
problems with continuing to use the 4.2 dtd.

Finally, we might want to change the way the xsl deals with the code
node. Again, I think that can wait.

Daniel