techniques.html: It is usually okay to use a standard macro name like BOOST_PP_DEF for this kind of code because the macro is both defined and undefined in the immediate site of its use. I was really confused by the use of the word "standard". This would be clearer: 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. Although I don't know why you'd want to advocate that over using a descriptive name. ------ A clearer divider between examples would be a *huge* help visually. An <hr> would be enough, for example. Example - Use BOOST_PP_EMPTY as an unused parameter in local macro instantiations. #define BOOST_PP_DEF(cv) /* ... */ \ template<class base> \ cv() typename implement_subscript_using_begin_subscript<base>::value_type& \ implement_subscript_using_begin_subscript<base>::operator[](index_type i) cv() { \ return base::begin()[i]; \ } \ /**/ ?? Where is BOOST_PP_EMPTY used in this example? I think I know what you mean, but really, you need to show it! How: BOOST_PP_EMPTY() expands to nothing and can be used as an unused parameter. Note: BOOST_PP_EMPTY with the () never gets expanded. This sounds self-contradictory. Just above you said it expands (to nothing)! The () is necessary to invoke a function-like macro. No duh; I think stating the obvious that way only adds confusion. Caveat: You cannot safely use concatenation while using BOOST_PP_EMPTY(). That's way too vague and general. I certainly can use concatenation and BOOST_PP_EMPTY "together", for many reasonable definitions of that word! I think you need to be more specific, or strike it. ------ 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, but in particular if you're just getting acquainted with the library at this point you may not have any idea what some of those macros do. You're advocating that people use them here, but unless the reader has some idea of what they generate, it's lost on her. Showing not-even-correct details of BOOST_PP_REPEAT's implementation doesn't help here. I'd strike it. Furthermore, BOOST_PP_ENUM_PARAMS and its variations use BOOST_PP_REPEAT. BOOST_PP_COMMA_IF(I) expands to a comma if I != 0. BOOST_PP_INC(I) essentially expands to "I+1," and BOOST_PP_DEC(I) essentially expands to "I-1.". I'd strike that too. You haven't said a word about BOOST_PP_INC/DEC yet, so the reader is left wondering why you're giving their implementation details. ----- Example - Use BOOST_PP_REPEAT and a token look-up function to eliminate categorical repetition. Is this really better than iterating over a SEQ of categories in any way other than efficiency? ----- Example - Use BOOST_PP_REPEAT to avoid O(n*n) repetition. It's unclear to me how that example avoids O(n*n) repetition. It certainly seems to have that complexity, and that appears to be intrinsic to the code it generates. Maybe you mean Example - Use BOOST_PP_REPEAT for O(n*n) repetition. Or something? ----- BOOST_PP_IF enables convenient generation of lists using BOOST_PP_REPEAT. This statement, without an example, is too vague to be helpful. ----- Implementation details of BOOST_PP_IF don't help: How: BOOST_PP_IF is defined for the entire repeat range (psuedo code): #define BOOST_PP_IF(c, THEN, ELSE) BOOST_PP_IF ## c(THEN, ELSE) #define BOOST_PP_IF0(THEN, ELSE) ELSE #define BOOST_PP_IF1(THEN, ELSE) THEN #define BOOST_PP_IF1(THEN, ELSE) THEN ^ especially since they appear to be wrong. I think the point is that BOOST_PP_IF works on first arguments other than 0 or 1. If so, you should just say that it works on numeric arguments up to N (whatever N is). --------- 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". -- Dave Abrahams Boost Consulting http://www.boost-consulting.com