Re: Understanding MPL

From: David Abrahams (dave_at_[hidden])
Date: 2003-04-17 18:45:34

"Paul Mensonides" <yg-boost-users_at_[hidden]> writes:

> I wouldn't go so far as to say, "fairly detailed."  What we were
> discussing then was more along the lines of a categorical grouping
> of macros with an accompanied, "this group of macros is part of
> mechanism x which does y."  That, IMO, is not a "from-the-ground-up"
> tutorial on the pp-lib.  

No, it is not, and if by "from-the-ground-up" you mean including a
detailed description of CPP fundamentals, that's not what's needed

> It is essentially just a better structured index.  

Not really.  An index makes you click through to various specific
pieces of documentation in order to see any details.  What I described
(or tried to) would have been a single document showing the main areas
of the library with some narrative and examples.

> The macros are already grouped by directories and headers--that
> structure is apparent in the index of headers.  What is lacking is a
> general, simplistic overview of each group of macros (for those that
> can be grouped).

Yep.

>> I draw an analogy to Comeau C++, an inexpensive, very high-quality
>> compiler, but because the installation documentation is presented so
>> inaccessibly, one which most people can't get started with unless they
>> have personal handholding from the implementor.
>
> Comeau C++ is easy to setup.  Especially with the lastest release.  

On Windows?

> Nearly all major problems associated with setting up Comeau have to
> do with paths that contain spaces.  

I never had a problem with that.

> I agree that their documentation is atrocious though.  

That's what I always had a problem with.

> But, at the same time, the pp-lib docs are no where near that
> disorganized.

No, I was drawing an analogy with something that showed an extreme
example of the problem in order to highlight it.

>> The preprocessor library doesn't need to be that way.  Users don't
>> need to understand the ugly workarounds and nitty-gritty details of
>> C++ preprocessor implementations in order to use the library
>> effectively.  I'm living proof of that.  One might say that's the
>> whole point of any high-quality library.  An overview of the
>> concepts and idioms users need to understand in order to make use
>> of the library itself would be a huge help.
>
> I directly recall, in a separate discussion between you and I, the
> words "idioms are what you need, my boy."  

I think I remember that too.  Not sure what I meant at the time
though ;-)

> And this is precisely the problem.  The preprocessor lib is
> implemented in the language Cpp.  This is a _different_ language
> than C and C++, despite the fact that it is part of C and C++.  When
> you write documentation for library X that is written in language Y,
> it is assumed that the user understands (more-or-less) the Y
> language--assuming no cross-language bindings.  With C and C++, you
> have 20+ years of literature on technique and idiom.  Template
> metaprogramming is relatively new, but it is _still_ implemented
> within the core language.  You _still_ don't have to explain that 1
> + 1 == 2 evaluates to true.  With preprocessor metaprogramming,
> there is no such backdrop.  The language is...different.  In some
> contexts, it is imperative, yet the language is definitely not
> imperative as a whole.  In others, it is functional, yet it is not
> entirely functional either.  Discussion of idiom and technique is
> closely tied to the language.  This, in and of itself, is a huge
> subject if taken on solely by the pp-lib docs.  

Yes.  IMO you should avoid it, at least for the time being.

> However, it gets even worse.  All but the most simplistic idioms and
> techniques will not work properly or not work consistently on most
> preprocessors.  

If you use PP library constructs instead of raw CPP you can hide most
of those differences, though.  At least it seems that way to me from
my experience.  I seldom (never?) run into platform-specific CPP bugs
except, e.g., when porting the PP library to a new platform.

> Nearly all of the negative criticism the pp-lib docs get do not
> revolve around how to use the primitives provided.  It is about
> explaining pp-metaprogramming, which, in turn, is largely about the
> language defined by Cpp.  

I *really* think you have been misinterpreting the criticisms.  As
long as you hear them as complaints that you've not explained the
details of CPP, you will probably never write the tutorial that people
need to get into the library.

> This is exactly why I say that you don't know what you're asking
> for.  

Why not give me the benefit of the doubt?  I could write something
prescriptive myself that would be a big help to new users, and I
probably don't understand PP metaprogramming at the level you think
neccessary.  I'm mostly over the hump and out of time, though -- and I
really think the library author ought to take this one on.

> A general overview of what the library can do is _not_ going
> to help in this regard, and a detailed explaination of how the
> preprocessor works and all the techniques and idioms that I know
> regarding pp-metaprogramming would require several hundred pages
> minimum.  Discussion of workarounds and hacks would make it even
> worse.  The fundamental problem, IMO, is not the pp-lib docs, it is
> that prospective users do not understand the Cpp language.

To me it looks like people keep telling you what they need, and you
keep telling them they need something else, so nothing moves.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com