Re: [boost] Preprocessor: Nested loops

From: Oliver Kullmann (O.Kullmann_at_[hidden])
Date: 2006-02-17 16:58:06

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; 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 --- where actually I'm not
interested in the solution, but I need precise and complete technical information
to the point *for something else*.

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

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

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, and where furthermore understanding
this use case won't help me a jota with understanding how to use the preprocessor library.

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.

Oliver