Re: [boost] Preprocessor: documentation comment

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2002-06-14 06:17:12

From: "Paul Mensonides" <pmenso57_at_[hidden]>

> I have been corresponding with Vesa about some of this stuff already (not
the
> docs, but the implementation),

I noticed!

> and I think that it is hard to finalize at this
> point.  For instance, Vesa's implementation of BOOST_PP_WHILE represents
about
> 256 iterations.  If he was to apply automatic recursion to that entire
list of
> macros, then every one of those *_D macros (i.e. ADD_D, MUL_D, etc.)
could be
> gotten rid of entirely because they would be unnecessary.  The problem
though is
> that would be massively inefficient to perform that kind of check
linearly on
> 256 macros.

I'll have to trust you on that. FWIW, reports from the field indicate some
anecdotal compilation slowdown from recent changes.

> There are several alternatives that I'm looking into (and Vesa is
> also), such as only 'allocating' batches of iterations (i.e. only check
every 5
> or 10) or using a binary search (or a weighted binary search, or both) to
> improve the efficiency of such a strategy.

Sounds promising.

> As far as the documentation goes, it really needs a full-fledge
introduction to
> preprocessor meta-programming.  I.e. what kinds of idioms and techniques
are
> available, how to avoid certain traps, etc..  It also needs tutorials
sections
> about each separate subset of the library (i.e. working with tuples,
working
> with cons-lists, working with loops, working with arithmetic, etc.), and
lastly
> the documentation needs step-by-step examples (not just completed
examples).

Agreed on all counts. It sounds like you have the right idea.

> My main problem is that I don't thoroughly know the Boost.Preprocessor
library.
> I am getting to know it better as time goes by, but I have never actually
*used*
> it at all--just looked at, comprehended the implementation, and compared
it to
> my own implementation of the same type of thing.  Sometimes I like how it
does
> things better, sometimes not.  Also, I don't know if I have enough
experience
> with preprocessor meta-programming to make a relatively comprehensive
> introduction to the techniques involved.  Though I may be more equipped
for it
> than many--and possibly more importantly, I have some interest in it.

Yes. In fact, the hardest part of doing this well is understanding what
needs to be covered and how it must be structured. Once you make the
outline, filling in details is often easy enough for an experienced library
user to do it.

> Of course, this whole preprocessor thing was a huge side-trip from what I
was
> working on before (template meta-programming), which in turn was a huge
> side-trip from what I was working on before that.

Life is a series of those, I think ;-)

> However, I have been talking with Vesa, and things are improving (at this
point
> the implementation).  Also, Vesa has told me that he plans to renovate
the
> documentation (except the reference part).  The hard part is coming up
with
> worthwhile examples that aren't really complicated--and that is why
discourses
> on feature sets are necessary.

We could reduce some of the real-world examples needed by the Boost.Python
library, if that's any help.

-Davce