[Boost-docs] [quickbook] Changes for 1.43

Subject: [Boost-docs] [quickbook] Changes for 1.43
From: Daniel James (daniel_james_at_[hidden])
Date: 2010-03-01 21:20:52

Hi,

I'm going to make a few changes to quickbook in the new release, I
don't think any of them require a version switch so I'm going to call
this 'quickbook 1.5.1'.

I've changed quickbook to understand a BOM in unicode files. It'll
reject any UTF-16/32 files, and jump over the BOM for UTF-8 files. At
the moment, it'll interpret it as a paragraph and generate some pretty
odd output. This should make it easier to use UTF-8.

It now checks if a template contains mismatched [section] and
[endsect] tags, and returns an error if it does. At the moment it
won't notice but it'll generate badly formed xml. Since templates are
phrase elements they're always surrounded by paragraph tags or
similar, so you can't match a tag in one template with an end tag in
another.

I've changed the simple markup parser (e.g for things like *bold*) so
that it doesn't accept '[' inside the markup. This is pretty much a
bug fix, as it currently prevents markup from being processed and
sometimes matches with the slashes inside link tags. (i.e. foo/bar
[@http://www.boost.org] becomes foo<i>bar [@http:</i>/www.boost.org]).
There are possibly some odd cases where the existing behaviour is
correct, but it's very unlikely.

Finally, I've added a unicode escape, using '\u39C', which is '\u'
followed by 1-4 hexadecimal digits. It's obviously ambiguous, so maybe
it'd be better if it was always 4 digits? I mentioned before that
[&39C] is possible, but I don't like it much as square brackets are
generally for markup, and slashes for escapes. Another possibility is
to use an XML/HTML style delimiter, '\u39C;' which removes the
ambiguity but feels a little odd. Maybe square brackets would be best.
Any opinions? At the moment the unicode escape just generates an XML
escape for anything >= 128.

I think I said I'd escape any UTF-8, but that's tricky with the Spirit
1 implementation. It should be easier to do things like that with the
Spirit 2 version.

Also, I haven't done this yet, but I'd like to restrict the attributes
that can be used in image tags (which can currently be anything).
They're obviously limited by docbook, so although that's sort of a
breaking change, it isn't really in practise. This will make it easier
to support HTML generation.

That's it (apart from some bug fixes) for 1.43. I'll try to get the
Spirit 2 port into 1.44.

Daniel