Re: [boost] Preprocessor: Nested loops

From: David Abrahams (dave_at_[hidden])
Date: 2006-02-17 20:29:47

Oliver Kullmann <O.Kullmann_at_[hidden]> writes:

> On Fri, Feb 17, 2006 at 01:44:52PM -0500, David Abrahams wrote:
>> Simon Carter <simon.carter_at_[hidden]> writes:
>> 
>> >> On Tue, Feb 14, 2006 at 04:58:20AM -0800, Paul Mensonides wrote:
>> >
>> >> 
>> >> If I enter the current documentation, then first I get to the
>> >> short introduction page with a link to the chapter from the mpl
>> >> book, which is based on earlier chapter in the book, and thus
>> >> cannot be used as an introduction.
>> >
>> > [snip]
>> >
>> > Completely & utterly agree. I only learnt how to use BOOST_PP by reading the
>> > source, and that can't be right.
>> 
>> Knowing what the code to be generated means has nothing to do with
>> knowing how to generate it.  Did you really try to understand that
>> tutorial, or did you just give up when it seemed to refer back to
>> earlier material you hadn't read?
>> 
>
> I can only speak about myself: Just seeing a reference to something
> obviously unrelated puts me off; 

Well, for a PP tutorial to be useful there needs to be something to
generate -- which will necessarily be unrelated to the topic at hand:
how to use the PP library.  Why is the example used there worse than
any other?

> I'm not a student anymore, and don't need holding by the hand and
> going through a "learning experience", first showing two wrong
> solutions, then two half-solution, then a 3/4-solution, and
> promising to see the whole solution somewhere later in the book

Are you claiming that the PP tutorial does that?  If so, please point
out where, because AFAICT it only shows correct code.  If not, my good
man, what *are* you talking about, and what relevance does it have to
our PP tutorial?

And if you don't want a "learning experience" you probably shouldn't
be reading tutorials in the first place.

> --- where actually I'm not interested in the solution, but I need
> precise and complete technical information to the point *for
> something else*.

I don't know what you mean but it sounds like you're describing the PP
reference docs; they do that job pretty well.

> I actually have read the MPL book (in parts), and I quickly browsed
> through that chapter on Boost PP, but it didn't speak about *my*
> problem (that problem of nesting loops; and related that problem of
> "recursion").

Nope, that's why that "chapter" is actually an appendix.  One could
write a whole separate book on PP metaprogramming, and I hope someday
Paul will do that.

> It is understandable, but nevertheless wrong in my opinion, that
> authors of documentation assume the reader will read the whole
> thing, from the begin to the end, with devotion (and
> time). Typically I have a concrete problem, and now just need the
> right tool to solve it.  Thus I don't want to understand for example
> the whole Boost PP library, but I just want to create a
> double-nested loop with simple content (just as an example). Giving
> me general advice about good programming style and how to use the
> library in a good way, not to use it for the wrong purposes, might
> at some time interest me, but this should go into some special
> section (actually, it would be good to have this general discussion
> for a library; but as I said, I believe it should go to its own
> place, with appropriate links to it).

Several people (including me) have had this discussion with Paul many
times.  Although I disagree with him about this, I respect Paul's
point of view in the matter.  I suggest, unless you can find some new
angle to the argument, that nothing new will come of repeating what
others before you have tried and failed at.

> This purpose, getting the right information "zack zack", is in my
> understanding best served by avoiding creating additional problems
> like introducing the preprocessor library by means of an example
> which first needs to understood by itself, 

Which example is that?

> and where furthermore understanding this use case won't help me a
> jota with understanding how to use the preprocessor library.

I can't imagine what sort of example you would say didn't need to be
"understood by itself" if you feel you had to understand the one used in
the tutorial appendix by itself.  What does "by itself" mean anyway?

> A final word: I know it from myself (not regarding documentation,
> but articles) that we tend to make a big fuss about our products,
> how it relates to so much other things, and how much a proper
> understanding of our product will help so much the reader. So we
> tend to obscure that actually what we are doing is quite simple ---
> and can be used quite simply.

For most people, the PP lib gives the illusion of being quite simple
and familiar, but then there are issues like this recursion thing that
you ran into, which don't map neatly onto the ordinary programming
paradigms we're used to.  I think those phenomena are harder to
explain simply.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com