Working on docs

[SVN r12612]

doc/reference/cat.htm

@@ -9,50 +9,12 @@
 <hr>
 
 <H2><a name="BOOST_PP_CAT">#define BOOST_PP_CAT</a>(X,Y)</H2>
- <P>Delays the catenation of X and Y.</P>
+ <P>Catenates X and Y after they are macro expanded.</P>
 
-<P>For example,</P>
+<H3>Example</H3>
-
+<UL>
-<PRE>
+  <LI><a href="../../example/static_assert.c">static_assert.c</a>
-  #define STATIC_ASSERT(EXPR)\
+</UL>
-    enum\
-    { <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(static_check_,__LINE__) = (EXPR) ? 1 : -1\
-    };\
-    typedef char\
-      <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(static_assert_,__LINE__)\
-      [ <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>(static_check_,__LINE__)\
-      ]
-
-  // ...
-
-  STATIC_ASSERT(sizeof(int) <= sizeof(long));
-</PRE>
-
-<P>expands to:</P>
-
-<PRE>
-  enum
-  { static_check_152 = (sizeof(int) <= sizeof(long)) ? 1 : -1
-  };
-  typedef char
-    static_assert_152
-    [ static_check_152
-    ];
-</PRE>
-
-<P>Using <a href="cat.htm#BOOST_PP_CAT">BOOST_PP_CAT</a>() above lets the PP expand the __LINE__. If the above
-code would use the ## operator directly then __LINE__ would not be expanded and
-the above would expand to:</P>
-
-<PRE>
-  enum
-  { static_check___LINE__ = (sizeof(int) <= sizeof(long)) ? 1 : -1
-  };
-  typedef char
-    static_assert___LINE__
-    [ static_check___LINE__
-    ];
-</PRE>
 
 <hr>
 

doc/reference/for.htm

@@ -39,8 +39,7 @@
 <H3><a href="repeat.htm#BOOST_PP_REPEAT">BOOST_PP_REPEAT</a>() vs <a href="for.htm#BOOST_PP_FOR">BOOST_PP_FOR</a>()</H3>
 
 <P><a href="for.htm#BOOST_PP_FOR">BOOST_PP_FOR</a>() is a generalization of <a href="repeat.htm#BOOST_PP_REPEAT">BOOST_PP_REPEAT</a>(). This means that
-<a href="repeat.htm#BOOST_PP_REPEAT">BOOST_PP_REPEAT</a>() can be implemented using <a href="for.htm#BOOST_PP_FOR">BOOST_PP_FOR</a>(). Unfortunately,
+<a href="repeat.htm#BOOST_PP_REPEAT">BOOST_PP_REPEAT</a>() can be implemented using <a href="for.htm#BOOST_PP_FOR">BOOST_PP_FOR</a>(). However,
-<a href="for.htm#BOOST_PP_FOR">BOOST_PP_FOR</a>() is slower than <a href="repeat.htm#BOOST_PP_REPEAT">BOOST_PP_REPEAT</a>(). In addition,
 <a href="repeat.htm#BOOST_PP_REPEAT">BOOST_PP_REPEAT</a>() was introduced earlier, is generally easier to use, and is
 still quite useful on its own.</P>
 

doc/reference/identity.htm

@@ -26,8 +26,9 @@ invoked.</P>
   X
 </PRE>
 
-<P>NOTE: If <a href="identity.htm#BOOST_PP_IDENTITY">BOOST_PP_IDENTITY</a>() is not invoked, the expansion will not be
+<H3>Note</H3>
-usable.</P>
+
+<P><a href="identity.htm#BOOST_PP_IDENTITY">BOOST_PP_IDENTITY</a>() needs to be invoked.</P>
 
 <hr>
 

doc/reference/limits.htm

@@ -24,11 +24,12 @@ library.</P>
 <P>This is also the limit of the repetition primitives (<a href="enum.htm#BOOST_PP_ENUM">BOOST_PP_ENUM</a> family
 and <a href="repeat.htm#BOOST_PP_REPEAT">BOOST_PP_REPEAT</a> family).</P>
 
-<P>NOTES:</P>
+<H3>Note</H3>
 <UL>
   <LI>Only decimal integer literals in the range [0,<a href="limits.htm#BOOST_PP_LIMIT_MAG">BOOST_PP_LIMIT_MAG</a>]
       are supported.
-  <LI>All arithmetic operations (ADD,SUB,MUL,DIV) use saturation arithmetic.
+  <LI>All arithmetic operations (<a href="arithmetic_add.htm#BOOST_PP_ADD">BOOST_PP_ADD</a>(),<a href="arithmetic_sub.htm#BOOST_PP_SUB">BOOST_PP_SUB</a>(),<a href="arithmetic_mul.htm#BOOST_PP_MUL">BOOST_PP_MUL</a>(),
+      <a href="arithmetic_div.htm#BOOST_PP_DIV">BOOST_PP_DIV</a>(),...) use saturation arithmetic.
   <LI>The maximum repetition count supported by the library may not be reached
       due to compiler limitations.
 </UL>

doc/reference/list_fold_left.htm

@@ -27,7 +27,9 @@
   )
 </PRE>
 
-<P>Note that folding, or accumulation, is a very general pattern of computation.
+<H3>Note</H3>
+
+<P>Folding, or accumulation, is a very general pattern of computation.
 Most list operations can be implemented in terms of folding.</P>
 
 <H3>See</H3>

doc/reference/list_to_tuple.htm

@@ -19,7 +19,9 @@
 
 <P>expands to (A,B,C).</P>
 
-<P>NOTE: The supported size of the list being converted to a tuple is limited by
+<H3>Note</H3>
+
+<P>The supported size of the list being converted to a tuple is limited by
 <a href="limits.htm#BOOST_PP_LIMIT_MAG">BOOST_PP_LIMIT_MAG</a> rather than <a href="limits.htm#BOOST_PP_LIMIT_TUPLE">BOOST_PP_LIMIT_TUPLE</a>.</P>
 
 <H3>Uses</H3>

doc/reference/stringize.htm

@@ -9,32 +9,12 @@
 <hr>
 
 <H2><a name="BOOST_PP_STRINGIZE">#define BOOST_PP_STRINGIZE</a>(X)</H2>
- <P>Delays the stringization of X.</P>
+ <P>Stringizes X after it is macro expanded.</P>
 
-<P>For example,</P>
+<H3>Example</H3>
-
+<UL>
-<PRE>
+  <LI><a href="../../example/note.c">note.c</a>
-  #define NOTE(STR)\
+</UL>
-    message(__FILE__ "(" <a href="stringize.htm#BOOST_PP_STRINGIZE">BOOST_PP_STRINGIZE</a>(__LINE__) ") : " STR)
-
-  // ...
-
-  #pragma NOTE("TBD!")
-</PRE>
-
-<P>expands to:</P>
-
-<PRE>
-  #pragma message("examples.cpp" "(" "20" ") : " "TBD!")
-</PRE>
-
-<P>The use of <a href="stringize.htm#BOOST_PP_STRINGIZE">BOOST_PP_STRINGIZE</a>() above lets the PP expand the __LINE__
-before stringizing it. If # would be used directly, the code would
-expand to:</P>
-
-<PRE>
-  #pragma message("examples.cpp" "(" "__LINE__" ") : " "TBD!")
-</PRE>
 
 <hr>
 

doc/reference/tuple_to_list.htm

@@ -11,9 +11,23 @@
 <H2><a name="BOOST_PP_TUPLE_TO_LIST">#define BOOST_PP_TUPLE_TO_LIST</a>(N,T)</H2>
  <P>Converts a tuple to a list.</P>
 
+<P>For example,</P>
+
+<PRE>
+  <a href="tuple_to_list.htm#BOOST_PP_TUPLE_TO_LIST">BOOST_PP_TUPLE_TO_LIST</a>(3,(A,B,C))
+</PRE>
+
+<P>expands to the same as</P>
+
+<PRE>
+  <a href="list_adt.htm#BOOST_PP_LIST_CONS">BOOST_PP_LIST_CONS</a>(A,
+  <a href="list_adt.htm#BOOST_PP_LIST_CONS">BOOST_PP_LIST_CONS</a>(B,
+  <a href="list_adt.htm#BOOST_PP_LIST_CONS">BOOST_PP_LIST_CONS</a>(C,
+  <a href="list_adt.htm#BOOST_PP_LIST_NIL">BOOST_PP_LIST_NIL</a>)))
+</PRE>
+
 <H3>See</H3>
 <UL>
-  <LI><a href="list_adt.htm#BOOST_PP_LIST_CONS">BOOST_PP_LIST_CONS</a>()
   <LI><a href="limits.htm#BOOST_PP_LIMIT_TUPLE">BOOST_PP_LIMIT_TUPLE</a>
 </UL>
 

doc/reference/while.htm

@@ -33,61 +33,23 @@
       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.
+      C++ preprocessor. Note that the value of the D parameter may exceed
+      <a href="limits.htm#BOOST_PP_LIMIT_MAG">BOOST_PP_LIMIT_MAG</a>.
 </UL>
 
-<P>NOTE: The value of the D parameter may exceed <a href="limits.htm#BOOST_PP_LIMIT_MAG">BOOST_PP_LIMIT_MAG</a>.</P>
+<H3>Note</H3>
-
-<H3>Caveat</H3>
 
 <P>Using <a href="while.htm#BOOST_PP_WHILE">BOOST_PP_WHILE</a>() 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 <a href="arithmetic_add.htm#BOOST_PP_ADD">BOOST_PP_ADD</a>() for additional
+various PREPROCESSOR library primitives such as <a href="arithmetic_add.htm#BOOST_PP_ADD">BOOST_PP_ADD</a>() for
-examples.</P>
+additional examples.</P>
 
 <H3>Example</H3>
 <UL>
   <LI><a href="../../example/count_down.c">count_down.c</a>
+  <LI><a hreF="../../example/linear_fib.c">linear_fib.c</a>
 </UL>
 
-<P>For a more complex example, let's take a look at an implementation of
-<a href="arithmetic_mul.htm#BOOST_PP_MUL">BOOST_PP_MUL</a>().</P>
-
-<PRE>
-  #define <a href="arithmetic_mul.htm#BOOST_PP_MUL">BOOST_PP_MUL</a>(X,Y) BOOST_PP_MUL_D(0,X,Y)
-  // Since the macro is implemented using WHILE, the actual implementation
-  // takes a depth as a parameter so that it can be called inside a WHILE.
-  // The above easy-to-use version simply uses 0 as the depth and can not be
-  // called inside a WHILE.
-
-  #define BOOST_PP_MUL_D(D,X,Y)\
-    <a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(3,0,<a href="while.htm#BOOST_PP_WHILE">BOOST_PP_WHILE</a>##D(BOOST_PP_MUL_C,BOOST_PP_MUL_F,(0,X,Y)))
-  //                    ^^^               ^^^             ^^             ^^ ^^^^^^^
-  //                    #1                #2              #3             #3 #1
-  //
-  // #1) The state is a 3-tuple. After the iteration is finished, the first
-  // element of the tuple is the result.
-  //
-  // #2) The WHILE primitive is "invoked" directly. <a href="while.htm#BOOST_PP_WHILE">BOOST_PP_WHILE</a>(D,...)
-  // can't be used because it would not be expanded by the C++ preprocessor.
-  //
-  // #3) ???_C is the condition and ???_F is the iteration macro.
-
-  #define BOOST_PP_MUL_C(D,P)\
-    <a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(3,2,P)
-  // Iteration is finished when the counter reaches 0.
-
-  #define BOOST_PP_MUL_F(D,P)\
-    ( BOOST_PP_ADD_D(D,<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(3,0,P),<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(3,1,P))\
-    , <a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(3,1,P)\
-    , <a href="dec.htm#BOOST_PP_DEC">BOOST_PP_DEC</a>(<a href="tuple_elem.htm#BOOST_PP_TUPLE_ELEM">BOOST_PP_TUPLE_ELEM</a>(3,2,P))\
-    )
-  // ( The result is increased by the multiplier.
-  // , The multiplier is retained without change.
-  // , The counter is decreased.
-  // )
-</PRE>
-
 <H3>Implementation rationale</H3>
 <UL>
   <LI>The maximum iteration depth is greater than 2*<a href="limits.htm#BOOST_PP_LIMIT_MAG">BOOST_PP_LIMIT_MAG</a> to make

doc/tutorial.htm

@@ -15,8 +15,8 @@
   <li><a href="#Techniques">Preprocessor Metaprogramming Techniques</a> 
     <ul>
       <li><a href="#Local Macro">Use a Local Macro to avoid small scale repetition</a></li>
-      <li><a href="#UNUSED">Use BOOST_PP_EMPTY() as an unused parameter in Local Macro 
+      <li><a href="#UNUSED">Use BOOST_PP_EMPTY as an unused parameter in Local 
-        instantiations</a></li>
+        Macro instantiations</a></li>
       <li><a href="#CAT">Use BOOST_PP_CAT instead of ## when necessary</a></li>
       <li><a href="#STRINGIZE">Use BOOST_PP_STRINGIZE instead of # whenever necessary</a></li>
       <li><a href="#ENUM_PARAMS">Avoid O(N) repetition on lists in general</a></li>
@@ -154,21 +154,21 @@ the line continuation operator when they are aligned.</P>
   metaprogramming.</P>
 <HR>
 <P><B><a name="UNUSED"></a><a href="examples_preprocessed.htm#UNUSED">EXAMPLE</a>:</B> 
-  Use BOOST_PP_EMPTY() as an unused parameter in Local Macro instantiations</P>
+  Use BOOST_PP_EMPTY as an unused parameter in Local Macro instantiations</P>
 
 <blockquote> 
   <pre>#define BOOST_PP_DEF(CV)  \
   template&lt;class base&gt;    \
-  CV typename implement_subscript_using_begin_subscript&lt;base&gt;::value_type&amp;\
+  CV() typename implement_subscript_using_begin_subscript&lt;base&gt;::value_type&amp;\
     implement_subscript_using_begin_subscript&lt;base&gt;::operator[]\
     ( index_type          \
         i                 \
-    ) CV                  \
+    ) CV()                \
 { return base::begin()[i];\
 }
 
-BOOST_PP_DEF(BOOST_PP_EMPTY())
+BOOST_PP_DEF(BOOST_PP_EMPTY)
-BOOST_PP_DEF(const)
+BOOST_PP_DEF(const BOOST_PP_EMPTY)
 #undef BOOST_PP_DEF
 </pre>
 </blockquote>