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