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

Subject: Re: [Boost-docs] [quickbook] Macros and scoping
From: Stjepan Rajko (stipe_at_[hidden])
Date: 2007-07-29 17:23:05

On 7/28/07, Joel de Guzman <joel_at_[hidden]> wrote:
>
> 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.
>

This sounds great to me.  One question - are the template/macro
definitions going to be usable "retroactively" within the appropriate
scope?  What I mean is, if:

[include file_with_some_templates.qbk]
[include subsection.qbl] [/ uses templates from file_with_some_templates.qbk]

works, would

[include subsection.qbl] [/ uses templates from file_with_some_templates.qbk]
[include file_with_some_templates.qbk]

also work?

This would be useful if one wanted to define templates that link to
different section content in the same file as the the section content
(but outside the [section], of course), and had two sections that
cross-referenced each other.  I imagine this is the behavior you
envisioned but just making sure.

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

2 seems to make the most sense to me also.

Stjepan