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

Subject: Re: [Boost-docs] [quickbook] Macros and scoping
From: John Maddock (john_at_[hidden])
Date: 2007-07-28 15:43:57

Joel de Guzman wrote:
> 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.

Yep, in order to implement "libraries" of quickbbok templates we need them 
to escape from an include directive.

> 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 like the sound of that.

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

Or introduce the new behaviour for quickbook *1.5* and newer?

Quickbook would start off in 1.5 (or whatever the current version is mode), 
and then "downgrade" when a document type block is encountered.

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

Me too.

I wonder is it possible to introduce some warnings:

* When __some_name is seen, then warn if "__some_name" is not defined as a 
macro.
* When [some_name] is seen, then warn if "some_name" is not a defined 
template.

As well as aiding migration to the next quickbook version, this would also 
be a big help in catching typos in template/macro expansions, that currently 
can only be caught by proof-reading the generated docs.

One other request: can we have multiple document type declarations [library 
... ] in the same document?

It would allow us to have composite documents:

[include library1.qbk]
[include library2.qbk]
[include library3.qbk]
[/etc]

that have multiple chapters, each possibly targetting a different quickbook 
version.  Is this possible?

Thanks, John.