Re: Understanding MPL

From: Paul Mensonides (yg-boost-users_at_[hidden])
Date: 2003-04-03 13:48:33

David Abrahams wrote:
> "Edward Diener" <eddielee_at_[hidden]> writes:
>
>>> What specifically would you have me do?  The pp-lib docs do not
>>> attempt to explain the implementation of the pp-lib itself.
>>
>> I don't want an explanation of the inner workings of the pp-lib. I
>> would like to see an explanation of the pp-lib which attempts to
>> explain the functionality of it from the user's point of view.
>> Something like a grouping of the macros in it from the point of view
>> of general areas of functionality, with the specific macros grouped
>> and explained within each area.
>
> ...and, to be fair, Paul, this isn't the first time Edward and I have
> described the nature of an introductory section which would help new
> users to get a grip on the library.  If I had any reasonable
> connection bandwidth I'd dig up the Boost messages for you.  As I
> remember, after much discussion we came up with a fairly detailed
> description of what was needed, and at that point the conversation
> stopped.

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.  It is essentially
just a better structured index.  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).

> 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.  Nearly all
major problems associated with setting up Comeau have to do with paths that
contain spaces.  I agree that their documentation is atrocious though.  But, at
the same time, the pp-lib docs are no where near that disorganized.

> 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."  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.  However, it gets even
worse.  All but the most simplistic idioms and techniques will not work properly
or not work consistently on most preprocessors.  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.  This is exactly why I say that you don't
know what you're asking for.  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.

Paul Mensonides