[boost] Re: MPL documentation

From: David Abrahams (dave_at_[hidden])
Date: 2004-11-21 22:50:00

"Edward Diener" <eddielee_at_[hidden]> writes:

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

Fortunately neither of us is running for office (as far as I know)
;-).

> 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 agree.  There wasn't time for this release... and after writing the
book I'm not sure if either one of us is motivated enough to do it
soon.

>>> 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, 

Yeah, and I think that omitting some mention of the relationship to
the STL on the front page of the docs was a mistake.

> and how to use it,

I do think the Metafunctions chapter does that.

> before it denotes the class structure of that framework. Perhaps
> this explanation of the basics should be called an overview.

Sounds good to me.

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

No, to quote:

  ...I think 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.

which means that you think that chapter will bring no further
knowledge of MPL to anyone who hasn't seen the MPL before.  I just
think that's a gross exaggeration, if not an outright falsehood.

> The tutorial provides significant information and is very well
> written. 

Thank you.

> But it starts somewhere beyond the beginning of the subject matter.

Yes.  It's chapter 3 in the book.

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

Correct.  But the "what is metaprogramming?" and "why
metaprogramming?" questions really should be left to the book.  And
the 2nd chapter in the book describes traits and type manipulation,
and shows how simple generic programming problems can be solved using
the Boost Type Traits library.  

I can't imagine what to do on the Boost website other than say, "if
you have no idea what this is, you probably should get familiar with
Boost.Type Traits and think about how type information can be useful
in your programs..."  but at that point, well, the next step ought to
be the book.

So if you have specific ideas about what should be covered in such an
overview, in such a way that it doesn't become our book all over
again, I'm all ears.

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

I'm sure it isn't 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 ?

Not sure what "from the beginning" means.

That chapter does explain the general concepts of MPL, except for one
crucial concept that really needs to be filled in before you can
understand it.  It's really a glaring omission that the "tutorial"
doesn't describe what a _Metafunction_ is.  

>>> 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, 

That's not the case.

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

I don't think it does (and never claimed it did).  Probably if you
fill in the missing definition of _Metafunction_ it would serve
pretty well, though.

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

You are correct.  That was part of my objection to calling that
chapter a tutorial.

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

Here is the detailed TOC for the first 2 chapters.  Most of what's
covered in chapter 1 should be clear from what's shown below.  The
discussion of alternatives (5.1/5.2) examines strategies other than
metaprogramming and analyzes their advantages and disadvantages.
Most of chapter 2 is built around a look at how type information can
be used to implement std::iter_swap effectively.  But, crucially, it
also introduces metafunctions.

I honestly don't see how to summarize these things.  We made a huge
effort in the book to be concise.  For someone who doesn't know
what's going on already, there isn't much that can be pruned.

o Introduction 
  1   Getting Started 
  2   So What's a Metaprogram? 
  3   Metaprogramming in the Host Language 
  4   Metaprogramming in C++ 
    4.1   Numeric Computations 
    4.2   Type Computations 
  5   Why Metaprogramming? 
    5.1   Alternative 1: Runtime Computation 
    5.2   Alternative 2: User Analysis 
    5.3   Why C++ Metaprogramming? 
  6   When Metaprogramming? 
  7   Why a Metaprogramming Library? 

o Traits And Type Manipulation 
  1   Type Associations 
    1.1   Using a Direct Approach 
    1.2   Taking the Long Way Around 
    1.3   Finding a Shortcut 
  2   Metafunctions 
  3   Numerical Metafunctions 
  4   Making Choices at Compile Time 
    4.1   More iter_swap 
    4.2   A Fly in the Ointment 
    4.3   Another Fly! 
    4.4   The Flyswapper 
  5   A Brief Tour of the Boost Type Traits Library 
    5.1   General 
    5.2   Primary Type Categorization 
    5.3   Secondary Type Categorization 
    5.4   Type Properties 
    5.5   Relationships Between Types 
    5.6   Type Transformations 
  6   Nullary Metafunctions 
  7   Metafunction Defintion 
  8   History 
  9   Details 
  10   Exercises 

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com