[Boost-docs] [quickbook] Macros and scoping

Subject: [Boost-docs] [quickbook] Macros and scoping
From: Joel de Guzman (joel_at_[hidden])
Date: 2007-07-28 09:04:14

Hi,

Eons ago, Eric wrote quickbook's include support. At one point he
specifically asked me if scoping the macros at include scope is
a good idea. I said yes. After some time, we all realized that
it's probably not. Isn't it bad that when we do:

[include something.qbk]

then try to use the includes in the file, all the macros are gone!
Why, because the scope of the macros ends with something.qbk.

Now, I am of the opinion that the proper scope should be the
document (global) and section (local), which, unlike include,
is properly scoped with nesting.

I'd add that the template definition is also a good scope.
That is, all macros (and templates!) declared inside a section
or template body should be local to that section or template
body and all macros and templates before the first section is
global to all the sections.

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?

1 Keep the current behavior and introduce a new symbol table for
   conditionals.
2 Change the old scoping behavior for old macros and templates
   starting with 1.4, but maintain backward compatibility for
   1.3 and older docs.
3 Always use templates, even for conditionals and give templates
   the "proper" scoping behavior. Keep the current behavior for
   macros.

Comments? I tend towards 2.

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