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:51:26

John Maddock wrote:
> 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.

Exactly!

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

Great!

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

Plausible. However, 1.4 is not officially released yet. I'm not sure
if having 1.5 ahead of 1.4's release is a good idea. Also, 1.4
may have at least two potentially breaking change:

* Nested comments are now allowed.
* Simple markups can now span a whole block.

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

Yep. That's the idea.

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

I guess not. __macro__ is just a convention. In some docs that
Rene and I are writing, we use :macro: convention.

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

Yes. Possible.

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

Right. I'll have more on macro naming in another email.

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