[boost] Re: MPL documentation

From: Edward Diener (eddielee_at_[hidden])
Date: 2004-11-21 12:12:48

David Abrahams wrote:
> "Edward Diener" <eddielee_at_[hidden]> writes:
>
>> The MPL documentation is better than before and the reference is
>> excellent. However I do not believe the tutorial is adequate for
>> bringing new programmers interested in understanding metaprogramming
>> using MPL into a general understanding of how MPL works and how to
>> use it. This is because the tutorial does not start at the beginning
>> of defining MPL concepts but jumps into high order metafunctions
>> without explaining the basis of metafunctions or metaprogramming
>> classes to begin with.
>
> That's because it's not a tutorial.  It's really just a chapter from
> the book that's been lifted.  Aleksey and I had some disagreement
> about calling it a "tutorial."

I vote for whoever feels it should not be called a tutorial, which I guess
is you rather than Aleksey. But in keeping with the efforts of Boost library
implementors to provide either a generalized tutorial, or an overview of
functionality, I think either should be offered rather than a chapter from
your book.

>
>
>> I understand the problem, that metaprogramming is a large concept
>> and that understanding the basics would entail starting at a point
>> where explaining anything further takes up much more space than a
>> mere tutorial would normally encompass. The answer no doubt is to
>> buy Mr. Abrahams and Mr.  Gurtovoy's book.
>
> I think it's a reasonable answer.  An online reference manual for an
> STL implementation shouldn't be expected to explain generic
> programming, and an online reference for an OO GUI framework
> shouldn't be expected to explain OO.

An online reference for a GUI framework should be expected to explain the
basic structure of the GUI framework, and how to use it, before it denotes
the class structure of that framework. Perhaps this explanation of the
basics should be called an overview.

>
>> However despite the good intent of the tutorial, I think that it
>> only performs the function of bringing further knowledge of the MPL
>> library to those who already understand how the basics of the
>> library already work.
>
> Oh come now.  Someone who know C++ well but doesn't already understand
> the basics of library won't be helped *at all* by this document?
> That's really hard to believe.  It provides significant explanation,
> example, and walkthrough material.

It is clearly now what I said that "Someone who know C++ well but doesn't
already understand the basics of library won't be helped *at all* by this
document". The tutorial provides significant information and is very well
written. But it starts somewhere beyond the beginning of the subject matter.
To you and Aleksey, and probably to those who have already been using the
MPL library such as many current developers, the beginning understanding is
already known. To those first starting with the MPL, even those with
template programming experience, I do not believe that is the case. While I
think that I may be able to understand enough from your tutorial to fill out
the missing pieces of what is probably chapters 1 and 2 of your book, try
considering whether this is the case for everyone else. Furthermore do you
want it to be the case ? Wouldn't it be better to provide a real overview,
or tutorial if you like, that would explain the general concepts of MPL from
the beginning and then rely on the programmer to figure out the rest through
their use of it and the documentation in the reference section ?

>
>> For those C++ programmers who want to learn to
>> understand how to use the MPL library from scratch, I do not think
>> the tutorial is adequate.
>
> Perhaps so.
>
>> Perhaps MPL was never meant to appeal to those without a knowledge
>> of its precepts to begin with, but by assuming that I think that the
>> tutorial will either leave C++ programmers who would like to learn
>> to use MPL feeling pretty cold about it, or force them to buy the
>> book in order to understand how it works.
>
> It's not intended to force anything.  I hope it isn't viewed as a
> cynical attempt to generate book sales, because including it and
> labelling it a tutorial was really a last-minute choice designed to
> (partially) fill an obvious gap.

I certainly do not view it is an attempt, cynical or otherwise, to generate
sales. In fact by offering an entire, and evidently key, chapter from your
book, you will probably hurt your sales <g>. By "force them to buy the book"
I merely meant that the information from then first few chapters probably
provides the necessary conceptual groundwork for understanding the library
which a C++ programmer may need. We can argue all day whether the tutorial
provides a good enough explanation for your fairly intelligent C++
programmer who understands the basics of programming template functions and
classes, as opposed to just using them, to understand how to use the MPL to
do template metaprogramming, but I think if you honestly ask yourself
whether a better overview, or tutorial if you like, is needed which makes it
easier for the novice template metaprogrammer to use the MPL, your answer
will be yes. As far as the writing, and explanation in the tutorial you
provide, it is quite good and I am not questioning that. Perhaps the idea is
to summarize the beginning information in chapters 1 and 2 in your book
briefly and then present chapter 3 as you have done.