Re: [Boost-docs] [quickbook] Changes for 1.43

Subject: Re: [Boost-docs] [quickbook] Changes for 1.43
From: Joel de Guzman (joel_at_[hidden])
Date: 2010-03-02 02:15:38

On 3/2/2010 5:20 AM, Daniel James wrote:
> Hi,

Hi Daniel,

> 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.

Cool!

> 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.

Don't we support block style templates too? But I see your point.

> 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.

Makes sense.

> 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.

Either brackets or strict 4 digits is good for me. I can't think of
anything better.

> 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.

I'm quite eager to see the Spirit2 port moving forward. I'd love to
work some bit on the template stuff + generic regex based syntax
highlighters and a most requested feature: making it really usable
for non-boost docs.

Regards,
-- 
Joel de Guzman
http://www.boostpro.com
http://spirit.sf.net
http://www.facebook.com/djowel
Meet me at BoostCon
http://www.boostcon.com/home
http://www.facebook.com/boostcon