[Boost-docs] Quickbook glob includes..

Subject: [Boost-docs] Quickbook glob includes..
From: Daniel James (dnljms_at_[hidden])
Date: 2011-12-03 14:33:21

On 1 December 2011 04:39, Rene Rivera <grafikrobot_at_[hidden]> wrote:
> I've just checked in the ability to "[include *.qbk]" multiple files at
> once. This is in the quickbook dev branch. The implementation of glob is a
> port to C++ from the C one present inside the b2 engine. Note, I didn't
add
> tests for this. Will do that later after some time for people to look at
it
> and doing any needed changes from that.

It looks good although it shouldn't store globs as filesystem paths, as
filesystem can interpret special characters differently on different
platforms. This means escapes won't work on windows (because filesystem
will think they're separators). I think it'd be better to convert the
filesystem paths to UTF-8 and always do the glob in that form. That means
it'll be using the same algorithm everywhere (case sensitivity is a problem
though) and it will make it a lot easier to deal with multibyte characters
since there's only one variety to deal with.

I don't like double escaping much, it's also inconsistent between paths and
globs. I've been thinking about unifying path and url representation so
maybe percent encoding could be used for literal characters? Or perhaps
quickbook unicode escapes. It's such a rare use-case that it shouldn't
matter too much if it's a bit horrible. If I get round to it, file urls
will be another way to say use a path isn't a glob (i.e. 'file:x?' will be
equivalent to 'x\\?' in the current version).

It's a pity that square brackets need to be escaped. I was going to suggest
changing the quickbook parser to deal with them, although that would make
it more difficult to support templates in paths at a later date. Might be
possible to have an alternative quickbook markup, so that something like
'[=a-z]' would be converted to '\[a-z\]'.