David Abrahams wrote:

"Edward Diener" writes:

...

I am trying to understand how the MPL library works. I first read "The Boost C++ Metaprogramming Library" by Aleksey Gurtovoy and David Abrahams. When I get to Basic Usage I see this:

template< typename Condition , typename T1 , typename T2 > struct if_ { typedef /*unspecified*/ type; };

I am really having trouble understanding the next to last line. How can "typedef type;" be a valid C++ construct and,

It's not.

...

if it is, what does it mean ?

There's an unspecified type-expression which goes where the /*unspecified*/ comment is.

...

I always though that a typedef must specify an actual type but I don't see any in the expression above.

The point is that we're not showing it to you ;-)

I suspected that but I couldn't figure out why you wouldn't show it. However it made it hard for me to understand how mpl::if_<> really works without understanding what actually goes there.

If you are coming to the ACCU conference in Oxford, I'll be giving a talk which describes how the MPL works in detail.

Much too far away if Oxford means England as I suspect. If it meant Mississippi I could come<g>.

"Joel de Guzman" writes:

Edward Diener wrote:

...

David Abrahams wrote:

...

"Edward Diener" writes:

...

...

There's an unspecified type-expression which goes where the /*unspecified*/ comment is.

...

I always though that a typedef must specify an actual type but I don't see any in the expression above.

The point is that we're not showing it to you ;-)

I suspected that but I couldn't figure out why you wouldn't show it. However it made it hard for me to understand how mpl::if_<> really works without understanding what actually goes there.

Because it's an implementation detail :-) You need not know the guts of how if_ really works, as long as it works. The same way as you don't need to know how if (c) a; else b; works, (in terms of low level code) as long as it works.

However, perhaps the /*unspecified*/ would better be enhanced by pseudo-code?

template< typename Condition , typename T1 , typename T2 > struct if_ { /* if (Condition) T1 else T2 */ typedef /* implementation detail */ type; };

Thoughts? Dave? Aleksey?

We're not hacking the paper at this point (working on the book instead ;-)) -- Dave Abrahams Boost Consulting www.boost-consulting.com

Markus Werle wrote:

David Abrahams wrote:

...

We're not hacking the paper at this point (working on the book instead)

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.

In the meantime Edward could be grateful for a hint to the book from the guy who explained some of the techniques in detail, even though his lib could not enter the boost tree due to reasons I do not know of:

The book to buy until David's book is out is "Modern C++ Design" from Andrei Alexandrescu. See http://www.moderncppdesign.com/

I already have it and have read it. The techniques explained in the Boost MPL library seem to be different from many of the techniques explained in Mr. Alexandrescu's fine book. I hope when the Boost book is out, it is more readable and deliberate in explaining how things work than the paper above which I find heavy going. But that's reasonable since papers often assume a level of understanding, and take appropriate shortcuts on that assumption, than a book which has more space to explain things a little more slowly. Perhaps my difficulty with the paper is just my own failing but I will stick to it and see what I can get out of it, and ask further questions if necessary.

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

Paul Mensonides wrote:

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.

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. The topic section does not do this. Instead it jumps around through various ideas I find almost impossible to understand. Furthermore nearly everything is done at this level by showing examples rather than explaining what things are. I admit I hate this mode of explaining computer programming which gives an example with little explanation and an attitude of "get it yet ?". Documentation needs to explain concepts in a regularized way and present them to the end user slowly and logically so that people can build up an understanding of things to do. Take the beginning motivation topic. I am told, as an example of the pp-lib, that the library can make it easier to generate repetitive overloaded metafunctions. Then at the bottom I am shown a series of Boost preprocessing macros to do this which are completely non-understandable to anyone coming to the pp-lib. I skip the "known problems of the preprocessor section" and go on to techniques. Here I am presented with a series of examples before any macros have been explained. This is documentation ? I have no ideas what these macros are or what they do. The second technique mentions using BOOST_PP_EMPTY and then this doesn't appear in the example at all. I am then told to use various pp-lib macros for various general tasks without any explanation of what these macros are and what they do. Again this isn't documentation as I define it. The next section of incompatibilities mentions various macros with again no explanation of what these are about. Etc. etc. Now I realize there is a reference section which lists each macro alphabetically. But this isn't to me an explanation of the areas of functionality of the pp-lib presented in any logical order. What the pp-lib docs need is a logical explanation of its functionality so that others may understand what is being done here, why it is being done, and how it is supposed to be used to supplement normal C++ programming, whether that programming involves template programming or otherwise. I don't mean to be harsh in my criticism of the documentation but to me it was created for the already "initiated" and not for the C++ programmer who is trying to gain an idea about the functionality of the preprocessor library as to each of its general parts and uses. The doc needs to be rewritten and presented in a logical manner to those who are coming to the pp-lib for the first time and are trying to understand its purpose and what problems it hopes to solve or what programming tasks it hopes to make easier. The various macros need to be grouped in categories which make it easier to understand what functionality exists and why.

David Abrahams wrote:

"Edward Diener" 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

Edward Diener wrote:

The general user does know how to use preprocessing macros and does understand how the macros may get expanded to code which can be used to accomplish tasks.

This is flat out not true. The general user understands that macros are relatively simple textual expansions. The general user does not understand the details of macro expansion, and these details are extremely important for any effective use of the preprocessor metaprogramming. Preprocessor metaprogramming and, to a large extent, template metaprogramming is all about manipulating/exploiting the "details" of their respective parts of the language. I absolutely guarantee that this level of understanding does not generally exist--for template metaprogramming and especially for preprocessor metaprogramming.

The general user does not understand the areas of functionality in the Boost pp-lib, what they are and how they may be used, because there is no good organizational explanation about the various areas in which the Boost pp-lib can be effectively used to accomplish either template programming goals or just useful code generation goals.

Both and more. As I said in the post I just sent a few minutes ago, I will address this this weekend. I'll try to write up a decent overview of the functionality available and send it to you so you can tell me what you think. However, there is no getting around the complexity involved because Cpp works against encapsulation.

What is needed, even given the difficulty of trying to understand how the macros actually work with various possibly broken preprocessors, is an explanation of the pp-lib from a user's point of view, ie. what is there and what can it accomplish in terms of helping to simplify program code generation and/or use.

What can be accomplished is an open-ended question. I can only provide examples of a few things that can be accomplished--which both Vesa and I have already done.

As an example, I understand that there is part of the Boost pp-lib which deals with easing the specification of repetitive constructs. That could be discussed, macros which solve repetitive generation problems can be discussed and explained, and the general user will now have an idea of what macros in the pp-lib help with repetitive programming problems and how a given macro may be used in that way.

As I've said before, this categorization is already there: docs/headers/repetition/* I agree that this organization is not explicit, but it is there for anybody who cares to look deeply at it. There are examples of how to use every interface macro in the library. You seem to be asking me to enumerate an open-ended set of possibilities. How can I possibly do that? Examples already exist, there are sections devoted entirely to the more complex aspects of the library. Given a general overview, what else can I do that would please you?

You may be right that the general user must first attempt to master the arcana of macro expansion and what does and does not work many macros attempt to expand inner macros in different situations in order to even use the pp-lib at all.

This is definitely part of it, but it has more to do with the vertical dependencies associated with the implementation of each primitive in the library. How primitive X is implemented is a direct concern to primitive Y. Expansion order is a significant factor as well. Encapsulation is a huge issue that causes use of the library to be closely tied to the implementation of the library. I have spent an excessive amount of time attempting to minimize these dependancies.

Or that likewise one must understand what can be done or not done given broken preprocessors in various implementations to use the pp-lib. I wouldn't say that is a failing of trying to use the pp-lib when the complexity goes up to a high level, but I would say if that were really the case, then the pp-lib has to attempt to create documentation which very patiently and in a well-organized way attempts to explain the above issues to the end-user.

This is the fundamental problem with what you propose. Unlike virtually *every other library in every other language*, programming with the preprocessor is one large system all at once (for the most part). Normal programming is broken into smaller manageable pieces that interact via well-defined interfaces. This is simply not possible given the limitations of the preprocessor. It is more like manageable pieces that depend greatly on exactly how other manageable pieces are _implemented_, not just their interfaces. Any user-defined functionality or, indeed, any actual use of the library inherently becomes part of the full system. That, combined with the lack of understanding of Cpp, is why the learning curve is so steep. It is not possible to construct documentation that "eases" the user through the harsh realities of preprocessor metaprogramming. The simple fact is that you have to get a "feel" for it by getting your hands dirty. Once you have that "feel," it becomes a powerful tool. In fact, the combination of the MPL and the pp-lib (especially the "strict" pp-lib that I'm working on (which blows the CVS version out of the water)) is--by far--the most powerful combination of tools for compile-time, generative, and reflective metaprogramming that has ever existed in _any_ language (short of a full-fledged intentional programming environment, of course. :) )

Creating examples of already complicated uses of pp-lib macros, which the end-user can't possibly fathom yet, is not the way to explain these issues.

What examples do you refer to? The examples that exist for each macro in the reference section and the examples that exist in the topical sections are, for the most part, as simple as can be. You are saying that I should thoroughly explain every macro used in examples at the point of the example, which is unreasonable.

It is possible that the Boost pp-lib is so intimately tied to template metaprogramming ideas that it is not really for the normal end-user who is just interested in knowing what it is all about and interested in seeing whether or not its functionality can be applied to other tasks. I will except this and, because I am not a template metaprogrammer in the Boost sense although I am very interested in what can be done in this area, it is simply not for me to understand or use. That's fine but I wonder if this is really the case with the Boost pp-lib. Most other Boost implementations do not require that sort of knowledge simply to be used by a C++ programming end-user. I understand the MPL does and perhaps the Boost pp-lib does too.

A level of competence with the preprocessor is required for all but the most trivial (a.k.a. useless) application of the pp-lib. This competence can be gained through understanding of Cpp in detail and hands-on experience. It is inherently complex, which I can only obviate to a certain degree. Preprocessor metaprogramming _is_ closely linked to template metaprogramming, but it is not tied to it. It just happens that in many contexts the two conspire to provide a solution to a given problem reasonably well. As far as broken preprocessors are concerned, because of the encapsulation issues that I mentioned earlier, there are no hard and fast workarounds. Also, I simply don't want to promote workarounds for deficient preprocessors. Rather I want to encourage vendors to fix their preprocessors. Again, I will write up an overview of the library this weekend and find out what you think. Regards, Paul Mensonides

David Abrahams wrote:

...

This is flat out not true. The general user understands that macros are relatively simple textual expansions. The general user does not understand the details of macro expansion, and these details are extremely important for any effective use of the preprocessor metaprogramming.

That is flat out not true. I have made some effective use of PP metaprogramming without understanding the details of macro expansion.

But you also, to a degree, understand the problems associated with the types of things that you have done with the pp-lib. Your understanding of it may not be as extensive as mine, but it is certainly greater than the average user. BTW, I'm not disagreeing that a sort of "synopsis" needs to exist; I'm just dubious of how helpful it will be in flattening the learning curve.

...

Preprocessor metaprogramming and, to a large extent, template metaprogramming is all about manipulating/exploiting the "details" of their respective parts of the language. I absolutely guarantee that this level of understanding does not generally exist--for template metaprogramming and especially for preprocessor metaprogramming.

In general libraries like MPL/Type Traits and Boost PP allow users to ignore (or actually be ignorant of) many of those "details" and concentrate on the task at hand. That's in part what makes them so powerful.

Yes.

...

...

The general user does not understand the areas of functionality in the Boost pp-lib, what they are and how they may be used, because there is no good organizational explanation about the various areas in which the Boost pp-lib can be effectively used to accomplish either template programming goals or just useful code generation goals.

Both and more. As I said in the post I just sent a few minutes ago, I will address this this weekend. I'll try to write up a decent overview of the functionality available and send it to you so you can tell me what you think.

Is it done yet? Can I see?

I started it. I got through CAT, STRINGIZE, WSTRINGIZE, EXPAND, EMPTY, and IDENTITY, but then I realized that I was already well over 1000 words. At that pace, I don't have time to deal with it immediately, so I either have to deal with it later, or rethink my "strategy."

...

However, there is no getting around the complexity involved because Cpp works against encapsulation.

Do you mean for example the leaking of information like recursion levels and different recursion mechanisms into the library interface? If so, I think that stuff is graspable without having to understand the reasons for it. You can just give people rules to follow and be done with it.

Only to a point. User code has to deal with this issue also. For instance, the reasons why things like is are unsafe: #define USER_A(n) class BOOST_PP_CAT(T, n) #define USER_B(n) BOOST_PP_CAT(T, n) #define MACRO(x) \ BOOST_PP_CAT( \ USER_, \ BOOST_PP_IF(x, A, B)(1) \ ) \ /**/

What you haven't done is to write something like, "C and C++ code (especially library code) often contains lots of boilerplate repetition, leading to fragile systems that are tedious to write and maintain. The Boost PP lib provides a programmatic framework for code generation which can be used to eliminate repeated boilerplate and factor out common textual patterns in code." ...and take it from there.

Do mean a sort of "descriptive table of contents"?

...

...

As an example, I understand that there is part of the Boost pp-lib which deals with easing the specification of repetitive constructs. That could be discussed, macros which solve repetitive generation problems can be discussed and explained, and the general user will now have an idea of what macros in the pp-lib help with repetitive programming problems and how a given macro may be used in that way.

As I've said before, this categorization is already there: docs/headers/repetition/* I agree that this organization is not explicit, but it is there for anybody who cares to look deeply at it.

The problem is that a general sense of the library and its capabilities should be possible without looking deeply.

What I'm stuck on is this.... There is a big difference between "a general sense of the library and its capabilities" and "a sense of how to use the library effectively." Are you referring to the former or the latter? The former is easy, the latter is not.

...

...

You may be right that the general user must first attempt to master the arcana of macro expansion and what does and does not work many macros attempt to expand inner macros in different situations in order to even use the pp-lib at all.

This is definitely part of it, but it has more to do with the vertical dependencies associated with the implementation of each primitive in the library. How primitive X is implemented is a direct concern to primitive Y. Expansion order is a significant factor as well. Encapsulation is a huge issue that causes use of the library to be closely tied to the implementation of the library. I have spent an excessive amount of time attempting to minimize these dependancies.

And you did a good job, which means that most users don't need to worry about it.

It means that most users don't have to worry about it with *certain constructs*, but not in general. Regards, Paul Mensonides

Paul Mensonides wrote:

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

From my (quite recent) experience with the PP library: The docs were adequate for what I needed, but I came to the library with a specific task to solve, so I was happy to jump around and find the topics I needed. Perhaps a few fully worked examples of solving real-world problems would help introduce some of the sections.

The end result is that I have a better idea of how a subset of the library works (conditional compilation) and a better idea of how to use it, but am still largely in the dark on the rest of the library, and what sort of problems I should consider using it for. The problem I faced was fairly simple - reinventing the TRACE macro. We want the facility to set a trace 'level' and depending on that level traces are omitted. Trace level can vary at run-time (to get a more detailed log from a user experiencing a problem) but we can also set a 'minimum level' for the compiler to completely omit low-level traces from release builds or enable particularly intense logging when targetting particular debug builds. And of course, minimum level can be set on a per-file basis, and may be suitably defaulted. Throw in a little intrusive profiling using the same scheme, and it was natural to turn to something like PP library that has already pre-packaged fixes around many of the problems I may meet, including hacks for bugs in a given compiler. Given my aversion to the pre-processor till now that was important, as I would not recognise a compiler bug as distict to my own!! PP made this quite easy and approachable to someone who has religiously avoided writing macros since starting with the language 7 years ago, so I think that is proof the library delivers! It definitely helps to have a goal in mind though (but isn't that true of learning most any programming topic?) -- AlisdairM

Edward Diener wrote:

...

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.

The pp-lib does not contain that type of hierarchal structure. The structure that does exist is fairly general. What you propose would cause me to have to repeat vast amounts of data that is properly reference data, and would actually make things more complex and significantly more of a pain to use for those that _are_ initiated.

The topic section does not do this. Instead it jumps around through various ideas I find almost impossible to understand. Furthermore nearly everything is done at this level by showing examples rather than explaining what things are. I admit I hate this mode of explaining computer programming which gives an example with little explanation and an attitude of "get it yet ?".

The topics section, at least the parts that I wrote, addresses parts of the library that are more advanced and require more of an overall picture of the library design. It is not intended to act like a reference, it is intended to provide an explanation for why certain parts of the library are the way they are. It also has a few sections on groups of macros/facilities that must be used in concert--which is unlike the rest of the library. I think you have an unrealistic picture of what the pp-lib docs should be. I seems that you think that documentation alone can make preprocessor metaprogramming obvious and relatively easy. That, by documentation alone, the learning curve can be gradual and straightforward. That, after reading through the documentation, you should have a relatively secure grip on how to use the library without actually getting your hands dirty. However, this is _fundamentally_ not the case. You're dealing with Cpp here, and Cpp is the antithesis of what is considered good language design. ;) It has very little support for data abstraction and encapsulation. Systems implemented within it are very dependent on the interactions of various parts--and how those parts are implemented themselves. There is no pure barrier called "interface." This is a fundamental issue with the preprocessor and cannot be "documented" away. It causes the learning curve to be steep and only experience can make you comfortable with it.

Documentation needs to explain concepts in a regularized way and present them to the end user slowly and logically so that people can build up an understanding of things to do.

This is not possible, IMO.

Take the beginning motivation topic. I am told, as an example of the pp-lib, that the library can make it easier to generate repetitive overloaded metafunctions. Then at the bottom I am shown a series of Boost preprocessing macros to do this which are completely non-understandable to anyone coming to the pp-lib.

That is what the reference section is for, and I'm not about to explain what a macro does every time it is referenced anywhere in the documentation.

I skip the "known problems of the preprocessor section" and go on to techniques. Here I am presented with a series of examples before any macros have been explained. This is documentation ? I have no ideas what these macros are or what they do.

Then look them up. I do not have to tools to insert inline definitions of everything everywhere they are referred to. I am not allowed to use scripting and XML/XSLT does not allow for the generation of multiple documents from a single source (even though most XSLT processors do).

The second technique mentions using BOOST_PP_EMPTY and then this doesn't appear in the example at all.

This one is my fault, I think. It should have the usage also. The idea is this: #define macro(cv) cv() macro( BOOST_PP_EMPTY ) // nil macro( const BOOST_PP_EMPTY ) // const ...I'll fix this this weekend.

I am then told to use various pp-lib macros for various general tasks without any explanation of what these macros are and what they do. Again this isn't documentation as I define it.

There is a huge amount of explanation of what each macro does. It takes very little effort to look them up in the reference section.

The next section of incompatibilities mentions various macros with again no explanation of what these are about. Etc. etc.

Of course not, they are incompatibilities that are only relevent to people that have existing experience and/or an existing codebase.

Now I realize there is a reference section which lists each macro alphabetically. But this isn't to me an explanation of the areas of functionality of the pp-lib presented in any logical order.

In this you are right. There is no explicit categorization. There is an implicit one by the library structure and the headers section.

What the pp-lib docs need is a logical explanation of its functionality so that others may understand what is being done here, why it is being done, and how it is supposed to be used to supplement normal C++ programming, whether that programming involves template programming or otherwise.

1) "...what is being done here..." This already exists, however, a categorical index does not. To be honest, things can be "categorized" in only the loosest sense of the word except in a relatively few cases. 2) "...why is it being done..." This is simple, to provide facilities _of all kinds_ to manipulate programs at compile-time with the preprocessor. They are fairly low-level tools to aid in generative metaprogramming. 3) "...how it is supposed to be used to supplement normal C++ programming..." This one is not simple. In fact, it is a thoroughly open-ended question. Many types of things can be done. Some usages already exist, some do not. However, that is like asking what 'if', 'while', and 'for' can be used for in programming. The preprocessor library has no explicit usage pattern--it is too low-level for that. It is, essentially, an implementation of core language facilities for the preprocessor, in order to make Cpp useful as a programming environment.

I don't mean to be harsh in my criticism of the documentation but to me it was created for the already "initiated" and not for the C++ programmer who is trying to gain an idea about the functionality of the preprocessor library as to each of its general parts and uses.

I will write up a library overview this weekend. However, I will not attempt to structure the documentation in a way that makes the documentation massively repetitive or in a way the inhibits ease of use. The "general parts" that you describe only exist in a few areas, and there are a large number of macros that are not part of any given group or mechanism.

The doc needs to be rewritten and presented in a logical manner to those who are coming to the pp-lib for the first time and are trying to understand its purpose and what problems it hopes to solve or what programming tasks it hopes to make easier.

These are all completely open-ended and naive questions. There already are examples of problems that have been solved with the pp-lib, yet you say you don't like learning from examples. However, these are just a few possibilities. One of the primary uses of the pp-lib today is repetition of various kinds (the primary use by the Python library and the MPL is in this area), but that is only a small portion of the library. The question of applicability is incredibly context sensitive. I guess my advice in this regard is simple, if it cannot be done reasonably with template metaprogramming, examine whether it is possible to do it with preprocessor metaprogramming--where "it" is a placeholder for whatever you might want to do at compile-time. There are, of course, limitations to both template metaprogramming and preprocessor metaprogramming, but only experience with both can tell you whether something is doable or not or how it might be done.

The various macros need to be grouped in categories which make it easier to understand what functionality exists and why.

These are the categories that actually exist: - Unsigned saturation arithmetic in the range of 0 to 256. - Manipulation of the "array" data type. - Unsigned numeric comparisons in the range of 0 to 256. - Control flow constructs (such as 'if', 'while', etc.) - Vertical repetition (a.k.a. iteration) - Manipulation of the "list" data type. - Logical operations such as 'and' and 'or'. - Punctuation operators for problem characters like commas and parentheses. - Horizontal repetition constructs - Manipulation of the "sequence" data type. - Evaluated slots. - Manipulation of the "tuple" data type. ...and a host of other non-groupable macros. Paul Mensonides

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.

Nope. I talk about all those WE_SUPPORT_EVEN_THE_STUPIDEST_MSVC() and GCC_HAS_A_BUG_BUT(WE_KNOW_HOW_TO_DEAL_WITH_IT) OTOH I must admit that I was yet just too unmotivated to figure out all those workarounds, since I hvae Intel's C++ which does not complain about the products of my wicked mind. My own lib, Daixtrose, simply ignores compilers that do not fit (unfortunately even gcc now fails). C++ is much more fun this way. I _should_ indeed take the time to make it more portable, this is why I am interested in tricks like BOOST_MPL_AUX_VOID_SPEC_PARAM(C) BOOST_MPL_AUX_VALUE_WKND(C)::value BOOST_MPL_AUX_LAMBDA_SUPPORT OTOH do not hesitate to write a book about the prepro lib. It's so powerful and I have it in mind for future usage. I offer proofreading without fees ... Best regards, Markus -- Compile time analytic differentiation? Yes, at http://daixtrose.sourceforge.net/

David Abrahams wrote: [...]

...

I always though that a typedef must specify an actual type but I don't see any in the expression above.

The point is that we're not showing it to you ;-)

``job security is what meta-programming in C++ is all about.'' regards, alexander.

David Abrahams wrote:

Alexander Terekhov writes:

...

David Abrahams wrote: [...]

...

...

I always though that a typedef must specify an actual type but I don't see any in the expression above.

The point is that we're not showing it to you ;-)

``job security is what meta-programming in C++ is all about.''

Hiding irrelevant implementation details is what high-level libraries are all about. If you care about the implementation you can always use the source, Luke.

That's okay, Theo. skywalker-ly y'rs, regards, alexander.