Re: [Boost-docs] [quickbook] Macros and scoping

Subject: Re: [Boost-docs] [quickbook] Macros and scoping
From: Joel de Guzman (joel_at_[hidden])
Date: 2007-07-28 23:34:06

Darren Garvey wrote:
> Hey Joel,
> 
> On 28/07/07, *Joel de Guzman* <joel_at_[hidden] 
> <mailto:joel_at_[hidden]>> wrote:
> 
>     I'd say that this is the only sensible behavior. Alas,
>     it will also potentially break existing docs. Yet, I need those
>     symbols for conditional generation with the scoping behavior
>     mentioned above. What should we do?
> 
>  
> Breaking the old pre-docs doesn't sound nice... 

Ahh.. I wasn't clear. No, old pre-docs will not break. Only versions
that's explicitly 1.4 and above (well, John suggests 1.5). FYI, 1.4
is not officially released yet. It only lives in the CVS at the moment.

I'm all for 100% backward compatibility with old docs. They will
work as-is without modification. It's only when you want to bump
your version to 1.4 (or 1.5) that you have to be aware of the
changes. IOTW, if you state your document as 1.4 (or 1.5) then
you better know what you are doing.

> How much would it break? 
> Just the use of defines? 

Just the defines. For example:

foo.qbk:

     [def __foo__ FooMan]

main.qbk:

     [include foo.qbk]
     __foo__

with old 1.3 and below, will print:

     __foo__

and with 1.4 (or 1.5) and above.:

     FooMan

I think the change is reasonable because due to the problems with
the scoping behavior of 1.3 and below, we tend to place macros
somewhere that's accessible to the whole document: right before
the first section in the main qbk file. I seldom see [defs in
included qbk files. If there are, it's easy to find them and if
they occur inside sections, fine! If not, move them inside.

> Would a syntax like:
> [include <file_name> <scope>]
> where <scope> defaults to 'local' not give enough flexibility to make 
> conditionals useful, without breaking old code? It might even be useful 
> in some normal-use cases (like conditionally including different macro 
> definition files).
>  
> I'm not sure if this would work well with quickbook; maybe that would 
> mean using something like 1) then?

Perhaps. It's unnecessarily verbose though (IMO). Please review my
intent (above) and see if you still object.

Regards,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net