diff --git a/include/boost/preprocessor/arithmetic/add.hpp b/include/boost/preprocessor/arithmetic/add.hpp
index dad0faa..c1f3397 100644
--- a/include/boost/preprocessor/arithmetic/add.hpp
+++ b/include/boost/preprocessor/arithmetic/add.hpp
@@ -26,6 +26,9 @@
 /** Expands to the sum of X and Y.
 
 For example, BOOST_PP_ADD(4,3) expands to 7 (a single token).
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_ADD(X,Y) BOOST_PP_ADD_D(0,X,Y)
 
diff --git a/include/boost/preprocessor/arithmetic/div.hpp b/include/boost/preprocessor/arithmetic/div.hpp
index df3f7f5..5e4e5e3 100644
--- a/include/boost/preprocessor/arithmetic/div.hpp
+++ b/include/boost/preprocessor/arithmetic/div.hpp
@@ -24,6 +24,9 @@
 /** Expands to the quotient of X and Y.
 
 For example, BOOST_PP_DIV(4,3) expands to 1 (a single token).
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_DIV(X,Y) BOOST_PP_DIV_D(0,X,Y)
 
diff --git a/include/boost/preprocessor/arithmetic/mod.hpp b/include/boost/preprocessor/arithmetic/mod.hpp
index 9340920..8b95ccc 100644
--- a/include/boost/preprocessor/arithmetic/mod.hpp
+++ b/include/boost/preprocessor/arithmetic/mod.hpp
@@ -23,6 +23,9 @@
 /** Expands to the remainder of X and Y.
 
 For example, BOOST_PP_MOD(4,3) expands to 1 (a single token).
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_MOD(X,Y) BOOST_PP_MOD_D(0,X,Y)
 
diff --git a/include/boost/preprocessor/arithmetic/mul.hpp b/include/boost/preprocessor/arithmetic/mul.hpp
index f6a1e7b..4b63c23 100644
--- a/include/boost/preprocessor/arithmetic/mul.hpp
+++ b/include/boost/preprocessor/arithmetic/mul.hpp
@@ -23,6 +23,9 @@
 /** Expands to the product of X and Y.
 
 For example, BOOST_PP_MUL(4,3) expands to 12 (a single token).
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_MUL(X,Y) BOOST_PP_MUL_D(0,X,Y)
 
diff --git a/include/boost/preprocessor/arithmetic/sub.hpp b/include/boost/preprocessor/arithmetic/sub.hpp
index 3f89eb9..715d35c 100644
--- a/include/boost/preprocessor/arithmetic/sub.hpp
+++ b/include/boost/preprocessor/arithmetic/sub.hpp
@@ -25,6 +25,9 @@
 /** Expands to the difference of X and Y.
 
 For example, BOOST_PP_SUB(4,3) expands to 1 (a single token).
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_SUB(X,Y) BOOST_PP_SUB_D(0,X,Y)
 
diff --git a/include/boost/preprocessor/comma.hpp b/include/boost/preprocessor/comma.hpp
index 967e048..7f8e200 100644
--- a/include/boost/preprocessor/comma.hpp
+++ b/include/boost/preprocessor/comma.hpp
@@ -20,7 +20,8 @@
 
 /** Expands to a comma. Can be used with BOOST_PP_IF().
 
-See BOOST_PP_COMMA_IF().
+<H3>See</H3>
+- BOOST_PP_COMMA_IF()
 */
 #define BOOST_PP_COMMA() ,
 
diff --git a/include/boost/preprocessor/comma_if.hpp b/include/boost/preprocessor/comma_if.hpp
index de124d7..63ed0e0 100644
--- a/include/boost/preprocessor/comma_if.hpp
+++ b/include/boost/preprocessor/comma_if.hpp
@@ -23,7 +23,6 @@
 #include <boost/preprocessor/if.hpp>
 
 /** Expands to a comma if C != 0 and nothing if C == 0. */
-
 #define BOOST_PP_COMMA_IF(C) BOOST_PP_IF(C,BOOST_PP_COMMA,BOOST_PP_EMPTY)()
 
 /** Obsolete. Use BOOST_PP_COMMA_IF(). */
diff --git a/include/boost/preprocessor/comparison/equal.hpp b/include/boost/preprocessor/comparison/equal.hpp
index eb4b2e6..051a69c 100644
--- a/include/boost/preprocessor/comparison/equal.hpp
+++ b/include/boost/preprocessor/comparison/equal.hpp
@@ -21,7 +21,11 @@
 #include <boost/preprocessor/comparison/not_equal.hpp>
 #include <boost/preprocessor/logical/not.hpp>
 
-/** Expands to 1 if X==Y and 0 otherwise. */
+/** Expands to 1 if X==Y and 0 otherwise.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
+*/
 #define BOOST_PP_EQUAL(X,Y) BOOST_PP_EQUAL_D(0,X,Y)
 
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
diff --git a/include/boost/preprocessor/comparison/greater.hpp b/include/boost/preprocessor/comparison/greater.hpp
index 89fcc0a..de7afca 100644
--- a/include/boost/preprocessor/comparison/greater.hpp
+++ b/include/boost/preprocessor/comparison/greater.hpp
@@ -20,7 +20,11 @@
 
 #include <boost/preprocessor/comparison/less.hpp>
 
-/** Expands to 1 if X>Y and 0 otherwise. */
+/** Expands to 1 if X>Y and 0 otherwise.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
+*/
 #define BOOST_PP_GREATER(X,Y) BOOST_PP_GREATER_D(0,X,Y)
 
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
diff --git a/include/boost/preprocessor/comparison/greater_equal.hpp b/include/boost/preprocessor/comparison/greater_equal.hpp
index 250fd9c..a732b1b 100644
--- a/include/boost/preprocessor/comparison/greater_equal.hpp
+++ b/include/boost/preprocessor/comparison/greater_equal.hpp
@@ -20,7 +20,11 @@
 
 #include <boost/preprocessor/comparison/less_equal.hpp>
 
-/** Expands to 1 if X>=Y and 0 otherwise. */
+/** Expands to 1 if X>=Y and 0 otherwise.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
+*/
 #define BOOST_PP_GREATER_EQUAL(X,Y) BOOST_PP_GREATER_EQUAL_D(0,X,Y)
 
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
diff --git a/include/boost/preprocessor/comparison/less.hpp b/include/boost/preprocessor/comparison/less.hpp
index deefe0d..98e9fe6 100644
--- a/include/boost/preprocessor/comparison/less.hpp
+++ b/include/boost/preprocessor/comparison/less.hpp
@@ -22,7 +22,11 @@
 #include <boost/preprocessor/comparison/not_equal.hpp>
 #include <boost/preprocessor/logical/and.hpp>
 
-/** Expands to 1 if X<Y and 0 otherwise. */
+/** Expands to 1 if X<Y and 0 otherwise.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
+*/
 #define BOOST_PP_LESS(X,Y) BOOST_PP_LESS_D(0,X,Y)
 
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
diff --git a/include/boost/preprocessor/comparison/less_equal.hpp b/include/boost/preprocessor/comparison/less_equal.hpp
index 7fa493d..87f746d 100644
--- a/include/boost/preprocessor/comparison/less_equal.hpp
+++ b/include/boost/preprocessor/comparison/less_equal.hpp
@@ -21,7 +21,11 @@
 #include <boost/preprocessor/arithmetic/sub.hpp>
 #include <boost/preprocessor/logical/not.hpp>
 
-/** Expands to 1 if X<=Y and 0 otherwise. */
+/** Expands to 1 if X<=Y and 0 otherwise.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
+*/
 #define BOOST_PP_LESS_EQUAL(X,Y) BOOST_PP_LESS_EQUAL_D(0,X,Y)
 
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
diff --git a/include/boost/preprocessor/comparison/not_equal.hpp b/include/boost/preprocessor/comparison/not_equal.hpp
index 0455d21..739ed2a 100644
--- a/include/boost/preprocessor/comparison/not_equal.hpp
+++ b/include/boost/preprocessor/comparison/not_equal.hpp
@@ -22,7 +22,11 @@
 #include <boost/preprocessor/arithmetic/sub.hpp>
 #include <boost/preprocessor/logical/bool.hpp>
 
-/** Expands to 1 if X!=Y and 0 otherwise. */
+/** Expands to 1 if X!=Y and 0 otherwise.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
+*/
 #define BOOST_PP_NOT_EQUAL(X,Y) BOOST_PP_NOT_EQUAL_D(0,X,Y)
 
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
diff --git a/include/boost/preprocessor/enum.hpp b/include/boost/preprocessor/enum.hpp
index b1f9bb5..1c03581 100644
--- a/include/boost/preprocessor/enum.hpp
+++ b/include/boost/preprocessor/enum.hpp
@@ -30,7 +30,8 @@ In other words, expands to the sequence:
   F(0,P), F(1,P), ..., F(N-1,P)
 \endverbatim</PRE>
 
-NOTE: The implementation uses BOOST_PP_REPEAT().
+<H3>Uses</H3>
+- BOOST_PP_REPEAT()
 */
 #define BOOST_PP_ENUM(N,F,P) BOOST_PP_REPEAT(N,BOOST_PP_ENUM_F,(F,P))
 
diff --git a/include/boost/preprocessor/enum_params.hpp b/include/boost/preprocessor/enum_params.hpp
index 66c8aef..5b56f5a 100644
--- a/include/boost/preprocessor/enum_params.hpp
+++ b/include/boost/preprocessor/enum_params.hpp
@@ -29,7 +29,8 @@ In other words, expands to the sequence:
   P##0, P##1, ..., P##N-1
 \endverbatim</PRE>
 
-NOTE: The implementation uses BOOST_PP_REPEAT().
+<H3>Uses</H3>
+- BOOST_PP_REPEAT()
 */
 #define BOOST_PP_ENUM_PARAMS(N,P) BOOST_PP_ENUM(N,BOOST_PP_ENUM_PARAMS_F,P)
 
diff --git a/include/boost/preprocessor/enum_params_with_a_default.hpp b/include/boost/preprocessor/enum_params_with_a_default.hpp
index 5a07917..b6ab820 100644
--- a/include/boost/preprocessor/enum_params_with_a_default.hpp
+++ b/include/boost/preprocessor/enum_params_with_a_default.hpp
@@ -29,7 +29,8 @@ In other words, expands to the sequence:
   P##0 = D, P##1 = D, ..., P##N-1 = D
 \endverbatim</PRE>
 
-NOTE: The implementation uses BOOST_PP_REPEAT().
+<H3>Uses</H3>
+- BOOST_PP_REPEAT()
 */
 #define BOOST_PP_ENUM_PARAMS_WITH_A_DEFAULT(N,P,D) BOOST_PP_ENUM(N,BOOST_PP_ENUM_PARAMS_WITH_A_DEFAULT_F,(P,D))
 
diff --git a/include/boost/preprocessor/enum_params_with_defaults.hpp b/include/boost/preprocessor/enum_params_with_defaults.hpp
index b8c7c62..e79d4d8 100644
--- a/include/boost/preprocessor/enum_params_with_defaults.hpp
+++ b/include/boost/preprocessor/enum_params_with_defaults.hpp
@@ -29,7 +29,8 @@ In other words, expands to the sequence:
   P##0 = D##0, P##1 = D##1, ..., P##N-1 = D##N-1
 \endverbatim</PRE>
 
-NOTE: The implementation uses BOOST_PP_REPEAT().
+<H3>Uses</H3>
+- BOOST_PP_REPEAT()
 */
 #define BOOST_PP_ENUM_PARAMS_WITH_DEFAULTS(N,P,D) BOOST_PP_ENUM(N,BOOST_PP_ENUM_PARAMS_WITH_DEFAULTS_F,(P,D))
 
diff --git a/include/boost/preprocessor/enum_shifted.hpp b/include/boost/preprocessor/enum_shifted.hpp
index 8290794..4515253 100644
--- a/include/boost/preprocessor/enum_shifted.hpp
+++ b/include/boost/preprocessor/enum_shifted.hpp
@@ -30,7 +30,8 @@ In other words, expands to the sequence:
   F(1,P), F(2,P), ..., F(N-1,P)
 \endverbatim</PRE>
 
-NOTE: The implementation uses BOOST_PP_REPEAT().
+<H3>Uses</H3>
+- BOOST_PP_REPEAT()
 */
 #define BOOST_PP_ENUM_SHIFTED(N,F,P) BOOST_PP_ENUM(BOOST_PP_DEC(N),BOOST_PP_ENUM_SHIFTED_F,(F,P))
 
diff --git a/include/boost/preprocessor/enum_shifted_params.hpp b/include/boost/preprocessor/enum_shifted_params.hpp
index e1a6a2f..c0ed3dd 100644
--- a/include/boost/preprocessor/enum_shifted_params.hpp
+++ b/include/boost/preprocessor/enum_shifted_params.hpp
@@ -29,9 +29,10 @@ In other words, expands to the sequence:
   P##1, P##2, ..., P##N-1
 \endverbatim</PRE>
 
-NOTE: The implementation uses BOOST_PP_REPEAT().
+<H3>Uses</H3>
+- BOOST_PP_REPEAT()
 
-RATIONALE:
+<H3>Rationale</H3>
 - This macro facilitates a typical usage of the library. Shifted parameter
 lists are common in template metaprograms. 
 */
diff --git a/include/boost/preprocessor/for.hpp b/include/boost/preprocessor/for.hpp
index 14272ce..6c91db4 100644
--- a/include/boost/preprocessor/for.hpp
+++ b/include/boost/preprocessor/for.hpp
@@ -33,20 +33,16 @@ The length of the sequence is determined by C(R,X).
 
 <H3>Legend</H3>
 
-<B>X</B> is the current state of iteration. The state is usually a tuple.
-
-<B>C</B> is the condition for iteration. It must expand to a decimal integer
+- <B>X</B> is the current state of iteration. The state is usually a tuple.
+- <B>C</B> is the condition for iteration. It must expand to a decimal integer
 literal.
-
-<B>F</B> is the iterated macro. Note that if the state is a tuple, then
+- <B>F</B> is the iterated macro. Note that if the state is a tuple, then
 F(R,X) usually expands to a tuple of the same number of elements.
-
-<B>I</B> is the state instantiation macro.
-
-<B>R</B> is the recursion depth and should only be used as a parameter to
+- <B>I</B> is the state instantiation macro.
+- <B>R</B> is the recursion depth and should only be used as a parameter to
 other macros implemented using BOOST_PP_FOR() or for invoking
 BOOST_PP_FOR##R() directly. For each macro implemented using BOOST_PP_FOR(),
-there is a version of the macro, distinguished by the _R suffix, that accepts
+there is a version of the macro, distinguished by the R suffix, that accepts
 an additional recursion depth as the first parameter. This technique is
 necessary to avoid recursively expanding the same macro again, which is not
 permitted by the C++ preprocessor.
diff --git a/include/boost/preprocessor/list/adt.hpp b/include/boost/preprocessor/list/adt.hpp
index 5d5dbfd..4c509a6 100644
--- a/include/boost/preprocessor/list/adt.hpp
+++ b/include/boost/preprocessor/list/adt.hpp
@@ -53,13 +53,15 @@ Both of the above lists contain 5 elements: 1, 2, 3, 4 and 5.
 
 /** List nil constructor.
 
-See BOOST_PP_LIST_CONS().
+<H3>See</H3>
+- BOOST_PP_LIST_CONS()
 */
 #define BOOST_PP_LIST_NIL (_,_,0)
 
 /** Expands to 1 if the list is not nil and 0 otherwise.
 
-See BOOST_PP_LIST_IS_NIL().
+<H3>See</H3>
+- BOOST_PP_LIST_IS_NIL()
 */
 #if !defined(BOOST_NO_COMPILER_CONFIG) && defined(__MWERKS__) && __MWERKS__ <= 0x2406
 #  define BOOST_PP_LIST_IS_CONS(L) BOOST_PP_TUPLE_ELEM(3,2,L)
@@ -69,7 +71,8 @@ See BOOST_PP_LIST_IS_NIL().
 
 /** Expands to 1 if the list is nil and 0 otherwise.
 
-See BOOST_PP_LIST_IS_CONS().
+<H3>See</H3>
+- BOOST_PP_LIST_IS_CONS()
 */
 #if !defined(BOOST_NO_COMPILER_CONFIG) && defined(__MWERKS__) && __MWERKS__ <= 0x2406
 #  define BOOST_PP_LIST_IS_NIL(L) BOOST_PP_NOT(BOOST_PP_TUPLE_ELEM(3,2,L))
@@ -87,7 +90,8 @@ For example,
 
 expands to 1.
 
-See BOOST_PP_LIST_REST().
+<H3>See</H3>
+- BOOST_PP_LIST_REST()
 */
 #if !defined(BOOST_NO_COMPILER_CONFIG) && defined(__MWERKS__) && __MWERKS__ <= 0x2406
 #  define BOOST_PP_LIST_FIRST(L) BOOST_PP_TUPLE_ELEM(3,0,L)
@@ -105,7 +109,8 @@ For example,
 
 expands to a list containing 2, 3, 4 and 5.
 
-See BOOST_PP_LIST_FIRST().
+<H3>See</H3>
+- BOOST_PP_LIST_FIRST()
 */
 #if !defined(BOOST_NO_COMPILER_CONFIG) && defined(__MWERKS__) && __MWERKS__ <= 0x2406
 #  define BOOST_PP_LIST_REST(L) BOOST_PP_TUPLE_ELEM(3,1,L)
diff --git a/include/boost/preprocessor/list/append.hpp b/include/boost/preprocessor/list/append.hpp
index 3231844..1611b8f 100644
--- a/include/boost/preprocessor/list/append.hpp
+++ b/include/boost/preprocessor/list/append.hpp
@@ -32,6 +32,9 @@ For example,
 \endverbatim</PRE>
 
 produces a list containing 1, 2, 3 and 4.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_LIST_APPEND(L,P) BOOST_PP_LIST_APPEND_D(0,L,P)
 
diff --git a/include/boost/preprocessor/list/at.hpp b/include/boost/preprocessor/list/at.hpp
index 2cc8277..c800db4 100644
--- a/include/boost/preprocessor/list/at.hpp
+++ b/include/boost/preprocessor/list/at.hpp
@@ -29,6 +29,9 @@ For example,
 \endverbatim</PRE>
 
 expands to B.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_LIST_AT(L,I) BOOST_PP_LIST_AT_D(0,L,I)
 
diff --git a/include/boost/preprocessor/list/cat.hpp b/include/boost/preprocessor/list/cat.hpp
index a320cd3..122572e 100644
--- a/include/boost/preprocessor/list/cat.hpp
+++ b/include/boost/preprocessor/list/cat.hpp
@@ -30,6 +30,9 @@ For example,
 \endverbatim</PRE>
 
 expands to 123.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_LIST_CAT(L) BOOST_PP_LIST_CAT_D(0,L)
 
diff --git a/include/boost/preprocessor/list/enum.hpp b/include/boost/preprocessor/list/enum.hpp
index 7bc4eb4..02fcca3 100644
--- a/include/boost/preprocessor/list/enum.hpp
+++ b/include/boost/preprocessor/list/enum.hpp
@@ -34,6 +34,9 @@ expands to:
 <PRE>\verbatim
   A, B, C
 \endverbatim</PRE>
+
+<H3>Uses</H3>
+- BOOST_PP_FOR().
 */
 #define BOOST_PP_LIST_ENUM(L) BOOST_PP_LIST_ENUM_R(0,L)
 
diff --git a/include/boost/preprocessor/list/filter.hpp b/include/boost/preprocessor/list/filter.hpp
index d20c9c3..71b9620 100644
--- a/include/boost/preprocessor/list/filter.hpp
+++ b/include/boost/preprocessor/list/filter.hpp
@@ -29,6 +29,9 @@ For example,
 \endverbatim</PRE>
 
 expands to a list containing 1 and 3.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_LIST_FILTER(F,P,L) BOOST_PP_LIST_FILTER_D(0,F,P,L)
 
diff --git a/include/boost/preprocessor/list/first_n.hpp b/include/boost/preprocessor/list/first_n.hpp
index c525bf7..e83de72 100644
--- a/include/boost/preprocessor/list/first_n.hpp
+++ b/include/boost/preprocessor/list/first_n.hpp
@@ -31,6 +31,9 @@ For example,
 \endverbatim</PRE>
 
 expands to a list containing + and -.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_LIST_FIRST_N(N,L) BOOST_PP_LIST_FIRST_N_D(0,N,L)
 
diff --git a/include/boost/preprocessor/list/fold_left.hpp b/include/boost/preprocessor/list/fold_left.hpp
index 2da106f..5e3d44b 100644
--- a/include/boost/preprocessor/list/fold_left.hpp
+++ b/include/boost/preprocessor/list/fold_left.hpp
@@ -42,7 +42,11 @@ expands to:
 Note that folding, or accumulation, is a very general pattern of computation.
 Most list operations can be implemented in terms of folding.
 
-See BOOST_PP_LIST_FOLD_RIGHT().
+<H3>See</H3>
+- BOOST_PP_LIST_FOLD_RIGHT()
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_LIST_FOLD_LEFT(F,P,L) BOOST_PP_LIST_FOLD_LEFT_D(0,F,P,L)
 
diff --git a/include/boost/preprocessor/list/fold_right.hpp b/include/boost/preprocessor/list/fold_right.hpp
index d672346..783a210 100644
--- a/include/boost/preprocessor/list/fold_right.hpp
+++ b/include/boost/preprocessor/list/fold_right.hpp
@@ -46,7 +46,11 @@ expands to:
   )
 \endverbatim</PRE>
 
-See BOOST_PP_LIST_FOLD_LEFT().
+<H3>See</H3>
+- BOOST_PP_LIST_FOLD_LEFT()
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_LIST_FOLD_RIGHT(F,L,P) BOOST_PP_LIST_FOLD_RIGHT_D(0,F,L,P)
 
diff --git a/include/boost/preprocessor/list/for_each.hpp b/include/boost/preprocessor/list/for_each.hpp
index 096ea74..4dd3b77 100644
--- a/include/boost/preprocessor/list/for_each.hpp
+++ b/include/boost/preprocessor/list/for_each.hpp
@@ -32,7 +32,11 @@ In other words, expands to the sequence:
   F(R,P,BOOST_PP_LIST_AT(L,BOOST_PP_DEC(BOOST_PP_LIST_SIZE(L))))
 \endverbatim</PRE>
 
-See BOOST_PP_FOR() for an explanation of the R parameter.
+<H3>Example</H3>
+- <a href="../../example/catch_builtin.cpp">catch_builtin.cpp</a>
+
+<H3>Uses</H3>
+- BOOST_PP_FOR()
 */
 #define BOOST_PP_LIST_FOR_EACH(F,P,L) BOOST_PP_LIST_FOR_EACH_R(0,F,P,L)
 
diff --git a/include/boost/preprocessor/list/for_each_product.hpp b/include/boost/preprocessor/list/for_each_product.hpp
index b5ad2d2..dc4f116 100644
--- a/include/boost/preprocessor/list/for_each_product.hpp
+++ b/include/boost/preprocessor/list/for_each_product.hpp
@@ -31,9 +31,12 @@ This macro is useful for generating code to avoid combinatorial explosion.
 
 <B>X</B> is an element of the cartesian product of the lists LL.
 
-<H3>Examples</H3>
+<H3>Example</H3>
 - <a href="../../example/is_integral.cpp">is_integral.cpp</a>
 - <a href="../../example/array_arithmetic.c">array_arithmetic.c</a>
+
+<H3>Uses</H3>
+- BOOST_PP_FOR()
 */
 #define BOOST_PP_LIST_FOR_EACH_PRODUCT(F,P,LL) BOOST_PP_LIST_FOR_EACH_PRODUCT_R(0,F,P,LL)
 
diff --git a/include/boost/preprocessor/list/rest_n.hpp b/include/boost/preprocessor/list/rest_n.hpp
index df2a831..f3c252c 100644
--- a/include/boost/preprocessor/list/rest_n.hpp
+++ b/include/boost/preprocessor/list/rest_n.hpp
@@ -31,6 +31,9 @@ For example,
 \endverbatim</PRE>
 
 expands to a list containing * and /.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_LIST_REST_N(N,L) BOOST_PP_LIST_REST_N_D(0,N,L)
 
diff --git a/include/boost/preprocessor/list/reverse.hpp b/include/boost/preprocessor/list/reverse.hpp
index 263218f..4b4e796 100644
--- a/include/boost/preprocessor/list/reverse.hpp
+++ b/include/boost/preprocessor/list/reverse.hpp
@@ -29,6 +29,9 @@ For example,
 \endverbatim</PRE>
 
 expands to a list containing C, B and A.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_LIST_REVERSE(L) BOOST_PP_LIST_REVERSE_D(0,L)
 
diff --git a/include/boost/preprocessor/list/size.hpp b/include/boost/preprocessor/list/size.hpp
index 1001200..1a5f251 100644
--- a/include/boost/preprocessor/list/size.hpp
+++ b/include/boost/preprocessor/list/size.hpp
@@ -30,6 +30,9 @@ For example,
 \endverbatim</PRE>
 
 expands to 3.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_LIST_SIZE(L) BOOST_PP_LIST_SIZE_D(0,L)
 
diff --git a/include/boost/preprocessor/list/to_tuple.hpp b/include/boost/preprocessor/list/to_tuple.hpp
index b5f315b..d0bf3a0 100644
--- a/include/boost/preprocessor/list/to_tuple.hpp
+++ b/include/boost/preprocessor/list/to_tuple.hpp
@@ -33,6 +33,9 @@ expands to (A,B,C).
 
 NOTE: The supported size of the list being converted to a tuple is limited by
 BOOST_PP_LIMIT_MAG rather than BOOST_PP_LIMIT_TUPLE.
+
+<H3>Uses</H3>
+- BOOST_PP_FOR()
 */
 #define BOOST_PP_LIST_TO_TUPLE(L) BOOST_PP_LIST_TO_TUPLE_R(0,L)
 
diff --git a/include/boost/preprocessor/list/transform.hpp b/include/boost/preprocessor/list/transform.hpp
index 3423be8..ad3cec3 100644
--- a/include/boost/preprocessor/list/transform.hpp
+++ b/include/boost/preprocessor/list/transform.hpp
@@ -39,6 +39,9 @@ For example,
 \endverbatim</PRE>
 
 expands to a list containing 3 and 4.
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_LIST_TRANSFORM(F,P,L) BOOST_PP_LIST_TRANSFORM_D(0,F,P,L)
 
diff --git a/include/boost/preprocessor/max.hpp b/include/boost/preprocessor/max.hpp
index 041382a..4bcebd2 100644
--- a/include/boost/preprocessor/max.hpp
+++ b/include/boost/preprocessor/max.hpp
@@ -24,6 +24,9 @@
 /** Expands to the maximum of X and Y.
 
 For example, BOOST_PP_MAX(5,7) expands to 7 (a single token).
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_MAX(X,Y) BOOST_PP_MAX_D(0,X,Y)
 
diff --git a/include/boost/preprocessor/min.hpp b/include/boost/preprocessor/min.hpp
index f5cbd69..3c4b2b5 100644
--- a/include/boost/preprocessor/min.hpp
+++ b/include/boost/preprocessor/min.hpp
@@ -24,6 +24,9 @@
 /** Expands to the minimum of X and Y.
 
 For example, BOOST_PP_MIN(5,7) expands to 5 (a single token).
+
+<H3>Uses</H3>
+- BOOST_PP_WHILE()
 */
 #define BOOST_PP_MIN(X,Y) BOOST_PP_MIN_D(0,X,Y)
 
diff --git a/include/boost/preprocessor/repeat.hpp b/include/boost/preprocessor/repeat.hpp
index fe50579..4f1f35c 100644
--- a/include/boost/preprocessor/repeat.hpp
+++ b/include/boost/preprocessor/repeat.hpp
@@ -18,7 +18,7 @@
 <a href="../../../../boost/preprocessor/repeat.hpp">Click here to see the header.</a>
 */
 
-/** Repeats the macro M(I,P) for I = 0 to N-1.
+/** Repeats the macro M(I,P) for I = [0,N-1[.
 
 In other words, expands to the sequence:
 
@@ -26,61 +26,17 @@ In other words, expands to the sequence:
   M(0,P) M(1,P) ... M(N-1,P)
 \endverbatim</PRE>
 
-See BOOST_PP_LIMIT_MAG.
-
 <H3>2D and 3D repetition</H3>
 
 2D and 3D repetition are supported with the BOOST_PP_REPEAT_2ND() and
-BOOST_PP_REPEAT_3RD() macros. For example,
+BOOST_PP_REPEAT_3RD() macros.
 
-<PRE>\verbatim
-   * A generalized macro for generating 2D arrays
-  #define ARRAY_2D(W,H,M,P)\
-    BOOST_PP_REPEAT_2ND\
-    ( H\
-    , ARRAY_2D_ROW\
-    , (W,H,M,P)\
-    )
-  #define ARRAY_2D_ROW(Y,WHMP)\
-    BOOST_PP_EXPAND\
-    ( BOOST_PP_REPEAT\
-      ( BOOST_PP_TUPLE_ELEM(4,0,WHMP)\
-      , ARRAY_2D_ELEM\
-      , (Y,BOOST_PP_TUPLE4_ENUM WHMP)\
-      )\
-    )
-  #define BOOST_PP_TUPLE4_ENUM(A,B,C,D) A,B,C,D
-  #define ARRAY_2D_ELEM(X,YWHMP)\
-    BOOST_PP_TUPLE_ELEM(5,3,YWHMP)\
-    BOOST_PP_EXPAND\
-    ( ( X\
-      , BOOST_PP_TUPLE_ELEM(5,0,YWHMP)\
-      , BOOST_PP_TUPLE_ELEM(5,1,YWHMP)\
-      , BOOST_PP_TUPLE_ELEM(5,2,YWHMP)\
-      , BOOST_PP_TUPLE_ELEM(5,4,YWHMP)\
-      )\
-    )
+<H3>Example</H3>
+- <a href="../../example/repeat_2d.c">repeat_2d.c</a>
 
-   * Here we use the above macro to generate something
-  #define ELEM(X,Y,W,H,E) BOOST_PP_COMMA_IF(BOOST_PP_OR(X,Y)) E##_##X##_##Y
-
-  ARRAY_2D(3,4,ELEM,elem)
-\endverbatim</PRE>
-
-expands to:
-
-<PRE>\verbatim
-  elem_0_0, elem_1_0, elem_2_0,
-  elem_0_1, elem_1_1, elem_2_1,
-  elem_0_2, elem_1_2, elem_2_2,
-  elem_0_3, elem_1_3, elem_2_3
-\endverbatim</PRE>
-
-Since recursive expansion of macros is not allowed by the C++ preprocessor,
-replacing the BOOST_PP_REPEAT_2ND above with BOOST_PP_REPEAT, would not
-produce the above expansion.
-
-See BOOST_PP_FOR().
+<H3>See</H3>
+- BOOST_PP_FOR()
+- BOOST_PP_LIMIT_MAG
 */
 #define BOOST_PP_REPEAT(N,M,P) BOOST_PP_REPEAT_DELAY(N,M,P)
 
diff --git a/include/boost/preprocessor/tuple/elem.hpp b/include/boost/preprocessor/tuple/elem.hpp
index a6d354b..0016283 100644
--- a/include/boost/preprocessor/tuple/elem.hpp
+++ b/include/boost/preprocessor/tuple/elem.hpp
@@ -38,7 +38,8 @@ Examples of tuples:
   4-tuple: (A B C, D, EF, 34)
 \endverbatim</PRE>
 
-See BOOST_PP_LIMIT_TUPLE.
+<H3>See</H3>
+- BOOST_PP_LIMIT_TUPLE
 */
 #define BOOST_PP_TUPLE_ELEM(N,I,T) BOOST_PP_TUPLE_ELEM_DELAY(N,I,T)
 
diff --git a/include/boost/preprocessor/tuple/to_list.hpp b/include/boost/preprocessor/tuple/to_list.hpp
index dc0894d..5166484 100644
--- a/include/boost/preprocessor/tuple/to_list.hpp
+++ b/include/boost/preprocessor/tuple/to_list.hpp
@@ -22,9 +22,9 @@
 
 /** Converts a tuple to a list.
 
-See BOOST_PP_LIST_CONS() for an example.
-
-See BOOST_PP_LIMIT_TUPLE.
+<H3>See</H3>
+- BOOST_PP_LIST_CONS()
+- BOOST_PP_LIMIT_TUPLE
 */
 #define BOOST_PP_TUPLE_TO_LIST(N,T) BOOST_PP_TUPLE_TO_LIST_DELAY(N,T)
 
diff --git a/include/boost/preprocessor/while.hpp b/include/boost/preprocessor/while.hpp
index af3bcb8..0af7612 100644
--- a/include/boost/preprocessor/while.hpp
+++ b/include/boost/preprocessor/while.hpp
@@ -23,50 +23,42 @@
 
 /** Iterates F(D,X) while C(D,X) is true.
 
+In other words, expands to:
+
+<PRE>\verbatim
+  F(D, ... F(D, F(D,X) ) ... )
+\endverbatim</PRE>
+
+The depth of iteration is determined by C(D,X).
+
 <H3>Legend</H3>
 
-<B>X</B> is the current state of iteration. The state is usually a tuple.
-
-<B>C</B> is the condition for iteration. It must expand to a decimal integer
-literal.
-
-<B>F</B> is the iterated macro. Note that if the state is a tuple, then
+- <B>X</B> is the current state of iteration. The state is usually a tuple.
+- <B>C</B> is the condition for iteration. It must expand to a decimal
+integer literal.
+- <B>F</B> is the iterated macro. Note that if the state is a tuple, then
 F(D,X) usually expands to a tuple of the same number of elements.
-
-<B>D</B> is the recursion depth and should only be used as a parameter to
-other macros implemented using BOOST_PP_WHILE(). Such macros include
+- <B>D</B> is the recursion depth and should only be used as a parameter
+to other macros implemented using BOOST_PP_WHILE(). Such macros include
 BOOST_PP_ADD() and other arithmetic operations. For each macro implemented
 using BOOST_PP_WHILE(), there is a version of the macro, distinguished by
-the _D suffix (e.g. BOOST_PP_ADD_D()), that accepts an additional recursion
+the D suffix (e.g. BOOST_PP_ADD_D()), that accepts an additional recursion
 depth as the first parameter. This technique is necessary to avoid
 recursively expanding the same macro again, which is not permitted by the
 C++ preprocessor.
 
 NOTE: The value of the D parameter may exceed BOOST_PP_LIMIT_MAG.
 
-<H3>Usage</H3>
+<H3>Caveat</H3>
 
 Using BOOST_PP_WHILE() is a bit tricky. This is due to the C++ preprocessor
 limitations. It is recommended to take a look at the implementations of the
 various PREPROCESSOR library primitives such as BOOST_PP_ADD() for additional
 examples.
 
-Here is a trivial example that simply counts down from N to 0 ultimately
-expanding to a 0:
+<H3>Example</H3>
 
-<PRE>\verbatim
-  #define COUNT_DOWN(N) BOOST_PP_WHILE(COUNT_DOWN_C,COUNT_DOWN_F,N)
-  // Above is the macro we are implementing using BOOST_PP_WHILE().
-
-  #define COUNT_DOWN_C(D,N) N
-  // Above is the condition. It expands to the current N.
-
-  #define COUNT_DOWN_F(D,N) BOOST_PP_DEC(N)
-  // Above is the iteration macro. It decrements N.
-
-  COUNT_DOWN(50)
-  // The above expands to 0.
-\endverbatim</PRE>
+- <a href="../../example/count_down.c">count_down.c</a>
 
 For a more complex example, let's take a look at an implementation of
 BOOST_PP_MUL().
@@ -106,9 +98,8 @@ BOOST_PP_MUL().
   // )
 \endverbatim</PRE>
 
-<H3>Implementation</H3>
+<H3>Implementation rationale</H3>
 
-RATIONALE:
 - The maximum iteration depth is greater than 2*BOOST_PP_LIMIT_MAG to make
 it possible to compute N*N functions.
 */