----- Original Message ----- From: "Edward Diener" <[EMAIL PROTECTED]>
> I see many pre-processor macros in the reference section of the > documentation but I don't see any good overview explaining the various > macros or groups of macros and the ideas behind them. The directory groupings of the library's headers are a pretty obvious clue for most of the preprocessor library (e.g. directory names such as "arithmetic" and "repetition"). While there is no "general overview" for the time being, you can look at the directory structure (which is included in the documentation) and get a pretty good idea of what is in the library. The library includes facilities for arithmetic, logical, and comparison operations, repetition constructs (horizontal and vertical), control structures (such as "if" and "while"), manipulation of several data types with unique properties, and a myriad of miscellaneous tools and facilities to help with using the afore mentioned groups. > What I am looking for > is a good overview of what macros are in the library. One section shows > examples, but they seem very random and don't seem to explain functionality > or ideas very well. Nearly every reference document for a particular macro includes a simple example. The examples in those parts don't usually do anything incredibly useful. They just exist to show how the respective macro *can* be used. There is no set group of domains to which the pp-lib caters. You use it to do whatever it is that you want to do. (The pp-lib does, however, excel at repetition.) Many of the facilities in the library are similar to the low-level capabilities of a regular old "if" or "while". Discussing at length what constructs like this are good for would only complicate the documentation even more than it already is. The documentation provides a reference of all macros (etc.) in the library and shows how to use them. How you use them and what you use them for is up to you. If you have a specific question or a general idea of what you want to accomplish, you can always ask me. I can point you in the right direction, give you advice, and tell you if it can or cannot be done. Dealing with the preprocessor as a programming environment is like learning a whole new language--one that doesn't even have many language features that are taken for granted (i.e. arithmetic, looping, flow control, etc.), so you have to expect that it takes some experimentation and experience to understand it. I will help you in every way that I can. > The preprocessor library would be much more understandable if the ideas > behind the macros were discussed and if an overview allowed end users to > understand what is in the library. The fundamental reason that the library is inaccessable and has such a step learning curve is that the library is not written in C++ (or even C). It is written in Cpp. Furthermore, it is like any other library written to be used by a specific language. You must have a reasonable understanding of the language in order to use the library. This requires more than a minimal conceptual understanding of Cpp, but a nitty-gritty "what-happens-when-and-what-doesn't-happen-and-why". That is what makes it steep. I agree that the documentation can be improved considerably, but that is also a massive undertaking. Consider the available documentation on C++ idioms. The literature is spread over thousands of books, articles, and decades of algorithmic lore. The available literature for programming in Cpp is largely confined to one place (that I know of), and that is the documentation for Boost's pp-lib. I am certainly not saying that Cpp is on par with a general purpose programming language (such as C++) as far as the raw number of unique idioms, but it has great many nonetheless, and the primary purpose of the documentation is to describe the library, not the language. > I have a feeling there are some valuable > techniques there, as the library has been muched praised, but I can't > discern how they macros are organized to provide functionality. I'm not sure what you mean here. Are you saying that the docs should discuss the implementation of the library as well as what the library can do? The internal implementation of the library uses some fairly advanced techniques, and it is hacked into incomprehensibility to support extremely buggy preprocessors (such as Metrowerks and Microsoft). The high-precision arithmetic support, which I have working on everything but Metrowerks, uses more advanced techniques than the entire rest of the library combined (which is what makes Metrowerks such a pain in the ***), not to mention the amount of tricks involving C99's variadic macros and placeholder arguments that I have up my sleve. (BTW, Dave, any word on the "work" Metrowerks is supposedly doing on their preprocessor?) The documentation does have some significant articles on the library facilities that require the user to use more advanced techniques, but the discussion is limited to the use of the library rather than the techniques themselves. As I mentioned previously, feel free to contact me personally, via the Boost list, or via the Boost-Users list if you need help, and I will be happy to help as I am able. Paul Mensonides _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost