[boost] Re: MPL documentation

From: Edward Diener (eddielee_at_[hidden])
Date: 2004-11-22 18:43:43

David Abrahams wrote:
> "Edward Diener" <eddielee_at_[hidden]> writes:
>
>> 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

>From these topics I would guess that a good overview before your chapter 3
would entail a basic explanation of:

1.4.1
1.4.2
2.2
2.3
2.6
2.7

and anything related to them regarding values and types you want to say. I
would leave out all but the simplest examples showing exactly what you mean
and just explain the ideas.

What I am simple saying is that if you want to make it fairly easy for the
non-experienced MPL programmer to pick up the MPL library you will include
some material about the information above. I could even say to you, although
it is purely your and Mr. Gurtovoy's choice, that you might think of making
chapters 1 and 2 available online as you have chapter 3. Of course you may
well feel that by doing this you are giving away what you feel you should
earn via book sales, as well it may be that your book contract does not
allow this anyway. I do think that it is possible to understand your MPL
library without the information in chapters 1 and 2, but that it becomes
more difficult, and more work, for the beginning MPL programmer to do so.

Personally I get discouraged when documentation does not give me a good
overview of concepts, not because I think that I can not pick up the
information if I were willing to investigate and work at it but because I
get annoyed that those who are doing good work are not providing me with the
information I need to make learning easier. Perhaps I am not in the
majority, but my view of the importance of good documentation is not that of
the majority either. I realize that both you and Mr. Gurtovy may be tired of
explaining MPL now that you have written a book about it, and documented it
in the Boost MPL reference, to write anything more. I can only say to you
that you put yourself in the place of programmers who may be interested in
your ideas, who are intelligent, who follow the Boost libraries, but do not
know what you do about metaprogramming and how you designed the library to
make it easier for people to metaprogramming in C++. If you think you have
given enough, fine. If not, consider one more effort at a basic number of
pages of introduction, perhaps very few in number and very basic, which
leads programmers to be interested in your ideas. Thanks for listening !