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
* When [some_name] is seen, then warn if "some_name" is not a defined

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]

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

Thanks, John.

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:40 UTC