-----Original Message----- [mailto:boost-bounces@lists.boost.org] On Behalf Of David B. Held
"David Abrahams" <dave@boost-consulting.com> wrote in message news:uaczb9y4f.fsf@boost-consulting.com...
[...] It is usually okay to reuse a single generic macro name like BOOST_PP_DEF throughout your code because the macro is both defined and undefined very close to its point of use.
Yeah, this would make a lot more sense. I was just looking over the docs the other day too, and gave up because it was taking too long to grok.
It takes more than a day to get used to the pp-lib. It takes much more than a day to get used to preprocessor metaprogramming--which is what you are doing every time that you use the pp-lib. It is an entirely different form of programming.
[...] ?? Where is BOOST_PP_EMPTY used in this example? I think I know what you mean, but really, you need to show it!
Yup. You did better than me. I didn't even see the BOOST_PP_EMPTY.
This was an error, probably on my part, the example should be something like: #define QUALIFIER(cv) cv() QUALIFIER( BOOST_PP_EMPTY ) // nothing QUALIFIER( BOOST_PP_IDENTITY(const) ) // const That is what it is referring to--abstraction of "emptiness" and more generally--programmatic emptiness.
[...] The BOOST_PP_ENUM_PARAMS example could benefit greatly from a side-by-side format in a table showing the expansion on the right. In fact, that would help all the examples,
YES! I could not agree with this more!!! It's hard enough getting one's head around the PP lib without having to be an expert in it already.
All of the examples (except the ones in this page) do have the results. Apparently, these did too, but I missed them when I copied the page.
[...] BOOST_PP_IF enables convenient generation of lists using BOOST_PP_REPEAT.
This statement, without an example, is too vague to be helpful.
Yes, many more examples, please.
There are a great many examples. For instance, almost all (if not all--I can't remember) library primitives have accompanying examples.
Also, am I the only one who finds the sparse frame-based layout to be a little counter-intuitive?
It is a reference tool intended to adequately support those developers that are already familiar with the library--that is the purpose of the layout.
Would it be possible to make the docs look a little more Boost-like?
Frankly, I find the Boost-like format to be suboptimal both in style and navigation--it achieves a lowest common denominator worthy of Netscape Gold--which is unnecessary. I'm not saying that the pp-lib docs look good--because they don't without the fonts fixed--but navigation is much easier and much more direct. Other documentation, such as Spirit's docs and Python's "Tutorial Introduction" are much more pleasing to the eye and much more professional. However, I know that some people's focus is on utilitarian presentation. The next iteration of the pp-lib's documentation will be entirely generated and that format can be generated just as easily as any other.
[...] Example: Use arithmetic, logical, and comparison operations when necessary.
With no commentary, and no generated code, this example is really useless. I mean, of course you'd use arithmetic, logical, and comparison operations "when neccessary".
I didn't get that either. It's a shame, because there's a lot of code that would benefit from the PP lib that almost certainly isn't because of the difficult learning curve.
The difficult learning curve is never going to go away. It is an alien environment that is contrary to most forms of programming. That takes time to become familiar with.
Good documentation would go a long way towards making it more usable.
More usable for what? I ask this simply to determine perspective. The documentation is never going to tell you what you can and cannot do with the preprocessor or what you should and should not do with the preprocessor--those are all unbounded sets. The most that the documentation can do is tell you what the _library_ can do and give a few examples. Take ENUM_PARAMS for example, an extremely common use of this primitive is to generate stuff like "class T0, class T1, class T2". However, the library doesn't have a single primitive that generates that string of preprocessing tokens--it only has the general form. It could just as easily generate "0.1, 0.2, 0.3". The point is that the output is a function of the combination of primitives, user-defined macros, and input. The library takes the role of a programming language. As such, it is never going to answer questions like "what things can I do with 'if'?" and "what things can I do with 'while'?". The library really is that low-level. ENUM_PARAMS is about the most underlying-language-oriented primitive in the entire library. There is definitely room for improvement, but I suspect that no matter how much I improve the docs and no matter how many examples that I add, I'm always going to hear the same old argument--the learning curve is too steep. That argument is based on the assumption that documentation (etc.) is enough to reduce every learning curve to a gentle slope--which is naive. The library is hard to learn because the library is different than anything that most programmers have been exposed to and because the many of the techniques and idioms used are different than those used in every other language and in computer science in general. It isn't simple, and it can't be made to be simple. *But* it can be better... Regards, Paul Mensonides