Re: Understanding MPL

From: Paul Mensonides (yg-boost-users_at_[hidden])
Date: 2003-04-02 01:39:28

Edward Diener wrote:
> Paul Mensonides wrote:
>> Markus Werle wrote:
>>
>>> Ah! Earning money with Open Source via Closed Docs ;-)
>>> Not exactly what RMS was dreaming of, but perfectly OK for me:
>>> I will buy that book ASAP. I hope You also explain all those
>>> macros that make the code so uneasy to read.
>>
>> I think your talking about the usage of the preprocessor lib here.
>> If David and Aleksey are writing a book on the MPL, they've got
>> enough on their plate without trying to explain the pp-lib also.
>
> The doc on the pp-lib really needs to be better. I admit I gave up
> trying to understand it because I really don't waste my own time
> anymore reading bad documentation, even though I know many people
> consider adequate documentation what I consider bad. I am sure there
> is much good functionality in the pp-lib and that many people
> understand it but I don't think I ever will.

Actually, there are only a few that understand the implementation--mostly
because there are only a few that actually care to.  Do you want to understand
how it works?  Or do you want to understand its interface and how to use it?
Or, do you want to understand _when_ to use it?

> I really do hope the pp-lib people take it to heart that they need to
> provide better doc about it which explains it from the ground floor
> up.

What specifically would you have me do?  The pp-lib docs do not attempt to
explain the implementation of the pp-lib itself.  This is because the pp-lib's
implementation is actually a mess of hacks working around major problems in the
preprocessors of nearly every major compiler vendor, and, frankly, I don't feel
that it is 1) necessary for a library implementor to fully document the
internals of a library, and 2) only a very few people would be interested in the
pp-lib's internals.  To many, the pp-lib is simply a tool, in the form of a
library, that they use to do other things that are relevant to their needs.
Yes, I could explain how everything would/could be implemented in an ideal
world, but very little would work on people's compilers.  To be accurate,
_exactly_ two preprocessors would be able to handle it:  GCC and the Wave
preprocessor (i.e. the Spirit sample, which is currently in beta).  I agree that
the docs could be better, but you seem to be asking for a complete,
from-the-ground-up exposé on how the pp-lib does what it does.  That is mostly a
dissertation on the language the library is implemented in (Cpp), not a
dissertation on the design of the library.

I don't mean to be harsh, so please don't take it that way.  I just don't think
that the people that negatively criticize the pp-lib's docs in this area
understand the full extent of what they are asking for.  There is, absolutely,
room for improvement.  In fact, there is room for major improvement, but the
docs themselves are quite thorough on _how_ to use the primitives provided by
the library.  The primary lack is in applicability.  E.g. the kinds of problems
that the pp-lib can help solve.  Large-scale discussion of idiom and technique
is beyond the scope of the pp-lib.  Rather, that is about programming in the
context of the C and C++ preprocessors and is a _huge_ subject.

On the plus side, I am working on a "strict" version of the pp-lib that goes
_far_ beyond the pp-lib that is in the CVS (and therefore released with Boost
releases).  This implementation diverges in some major ways and uses absolutely
zero workarounds for any preprocessor.  Among the list of major-vendor
preprocessors that can't even come close to handling it:  Microsoft, Metrowerks,
Borland, Sun, IBM, and EDG (e.g. Comeau and Intel--and not just for speed
issues).  There is only two, AFAIK, that can handle it--GCC and Wave.  The
problems with the afore mentioned preprocessors really make learning
pp-metaprogramming discouraging.  This version however is much more suited to
implementation exposition, as it contains no hacks and no clutter.  This is
partially why the Wave project is important in and of itself as well as being an
example of what Spirit can do.  It provides, at minimum, a means for people to
use and try various preprocessor metaprogramming idioms.  This, coupled with the
"strict" pp-lib, could encourage vendors to fix their d*mn preprocessors, which,
in turn allows for effective communication of the idioms necessary to understand
advanced preprocessor generative metaprogramming.

Lastly, I am more than willing to help you personally with usage of the pp-lib
or even with various aspects of preprocessor programming in general.  In fact,
that is an open invitation to anyone and please feel free to post here or email
me directly if you want help.  If people keep asking me over and over about the
same things, that _will_ help improve the documentation because I'll have a
better understanding of the types of problems that people are having.

Regards,
Paul Mensonides