Re: [Boost-docs] Boostbook DTD clash

Subject: Re: [Boost-docs] Boostbook DTD clash
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2008-12-03 10:13:58

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-
> bounces_at_[hidden]] On Behalf Of Daniel James
> Sent: 02 December 2008 21:20
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] Boostbook DTD clash
> 
> 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.

Well thanks for this - I'm now even more confused than I was before ;-)

But I begin to understand why at least.

I'll await your suggestions and meanwhile leave the 42 worms wriggling in
the can.
Sorry I even looked inside!

There is also a completely new system version 5 so perhaps it is futile to
upgrade to 4.5 when that is itself a 'legacy' system?

Paul

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