On Fri, Feb 17, 2006 at 01:44:52PM -0500, David Abrahams wrote:
Simon Carter <simon.carter@ttplabtech.com> 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