Minor edits to conversion docs. Edits plus add Advantages table to index.html.

doc/conversion.html

@@ -37,7 +37,7 @@
   <tr>
     <td width="100%" bgcolor="#E8F5FF">
       <a href="#Introduction">Introduction</a><br>
-      <a href="#FAQ">FAQ</a><br>
+      <a href="#FAQ">conversion.hpp FAQ</a><br>
       <a href="#Reference">Reference</a><br>
 &nbsp;&nbsp;&nbsp; <a href="#Synopsis">Synopsis</a><br>
 &nbsp;&nbsp;&nbsp; <a href="#Requirements">Requirements</a><br>
@@ -79,7 +79,7 @@ ordering. User defined types are also supported.</p>
   </tr>
 </table>
 
-<h2><a name="FAQ">FAQ</a></h2>
+<h2>conversion.hpp <a name="FAQ">FAQ</a></h2>
 
 <p><b>Is the implementation header only?</b></p>
 
@@ -98,7 +98,7 @@ below.</p>
 
 </blockquote>
 
-<p><b>Why are <code>reverse()</code> and <code>reverse_value()</code> templates 
+<p><b>Why are the template versions of <code>reverse()</code> and <code>reverse_value()</code> 
 in a detail namespace?</b></p>
 
 <blockquote>
@@ -110,14 +110,14 @@ wrong!</p>
 
 </blockquote>
 
-<p><b>Why are both value returning and modify_in_place functions provided?</b></p>
+<p><b>Why are both value returning and modify-in-place functions provided?</b></p>
 
 <blockquote>
 
-<p>Value returning functions are the standard idiom for functions that compute a 
+<p>Returning the result by value is the standard C and C++ idiom for functions that compute a 
-value. Modification in place functions allow cleaner code in many real-world 
+value from an argument. Modify-in-place functions allow cleaner code in many real-world 
-endian use cases and are more efficient for user defined types that have many 
+endian use cases and are more efficient for user defined types that have 
-members such as string data that do not need to be reversed. Thus both are 
+members such as string data that do not need to be reversed. Thus both forms are 
 provided.</p>
 
 </blockquote>
@@ -138,7 +138,7 @@ point formats.</p>
 <blockquote>
 
 <p>Only 16-bit, 32-bit, and 64-bit integers are supported. No tests have been 
-performed on machines that use something other than two's complement arithmetic.</p>
+performed on machines that do not use two's complement arithmetic.</p>
 
 </blockquote>
 

doc/index.html

@@ -116,31 +116,75 @@ endianness. But when exchanging binary integers with other computer systems, whe
 file transfers or over a network, programmers have to deal with endianness. </p>
 <h2><a name="Introduction">Introduction</a> to the Boost.Endian library</h2>
 
-<p>The Boost.Endian library provides facilities to deal with integer endianness.</p>
+<p>The Boost.Endian library provides two facilities for dealing with endianness.</p>
 
 <p>The library provides two approaches to dealing with integer endianness:</p>
 
 <blockquote>
 
-<p><b><a href="conversion.html">Endian conversions</a> for native integers -</b> The application uses the 
+<p><b><a href="conversion.html">Endian conversions</a> -</b> The application 
-built-in integer types, and calls the provided conversion functions to convert 
+uses the built-in integer and floating point types, and calls the provided 
-byte ordering as needed. Both mutating and non-mutating conversions are supplied, and 
+conversion functions to convert byte ordering as needed. Both mutating and 
-each comes in unconditional and conditional variants. This approach is simple 
+non-mutating conversions are supplied, and each comes in unconditional and 
-and usually more efficient, but is less flexible in terms of size and alignment, can be 
+conditional variants. Type <code>long double</code> is not currently supported.</p>
-hard-to-manage and error-prone in code with many logical paths involving endianness transitions, 
-and can foster very hard to debug logic errors. </p>
 
-<p><b><a href="integers.html">Endian integer types</a> -</b> The application uses the provided endian types 
+<p><b><a href="integers.html">Endian types</a> -</b> The application uses the provided endian types 
 which mimic the 
-built-in integer types. For example, <code>big32_t</code> or <code>little64_t</code>. 
+built-in integer types. For example, <code>big32_t</code> or <code>little64_t</code>. Types with lengths of 
-This approach is also simple, but can be less efficient. Types with lengths of 
+1-8 bytes are supported, rather than just&nbsp; 2, 4, and 8 bytes. There are no alignment 
-1-8 bytes are supported, rather than just 1, 2, 4, and 8 bytes. Strict alignment 
+requirements. Floating point types are not currently supported.</p>
-requirements are avoided, and this may allow data to be packed more tightly.</p>
 
 </blockquote>
 
 <p>Boost Endian is a header-only library.</p>
 
+<h2><a name="Choosing">Choosing</a> between endian types and endian 
+conversion functions</h2>
+
+<p>Which approach is best for dealing with endianness depends on the 
+application.</p>
+
+<table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
+  <tr>
+    <th colspan="2">Advantages</th>
+  </tr>
+  <tr>
+    <th width="50%"><b><a href="integers.html">Endian types</a></b></th>
+    <th><b><a href="conversion.html">Endian conversion functions</a></b></th>
+  </tr>
+  <tr>
+    <td valign="top">
+    <ul>
+      <li>Mimic the built-in types. This can simplify use and eliminate logic 
+      errors since there is no need to reason about the current endianness of 
+      variables.<br>
+&nbsp;</li>
+      <li>1, 2, 3, 4, 5, 6, 7, and 8 byte integers are supported. Use of 3, 5, 
+      6, or 7 byte integers can reduce internal and external space usage and 
+      save I/O time.<br>
+&nbsp;</li>
+      <li>Alignment is not required. This can eliminate padding bytes in 
+      structures, reducing internal and external space usage and saving I/O 
+      time.</li>
+    </ul>
+    </td>
+    <td valign="top">
+    <ul>
+      <li>Already familiar to developers who have been using C conversion 
+      functions for years.<br>
+&nbsp;</li>
+      <li>Uses less CPU time, particularly if each variable is used many times 
+      relative to I/O of the variable.<br>
+&nbsp;</li>
+      <li>Easier to pass structures to third-party libraries expecting a 
+      specific structure format.<br>
+&nbsp;</li>
+      <li>Supports <code>float</code> and <code>double</code>.</li>
+    </ul>
+    </td>
+  </tr>
+</table>
+
 <h2><a name="Acknowledgements">Acknowledgements</a></h2>
 <p>Comments and suggestions were 
 received from
@@ -155,13 +199,13 @@ Marsh Ray,
 Martin Bonner,
 Matias Capeletto,
 Neil Mayhew, Phil Endecott, Rene Rivera,
-Roland Schwarz, Scott McMurray, 
+Robert Stewart, Roland Schwarz, Scott McMurray, 
 Sebastian Redl, 
 Tomas Puverle, Vincente Botet, and
 Yuval Ronen.</p>
 <hr>
 <p>Last revised:
-<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->19 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13993" --></p>
+<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->20 May, 2013<!--webbot bot="Timestamp" endspan i-checksum="13976" --></p>
 <p><EFBFBD> Copyright Beman Dawes, 2011</p>
 <p>Distributed under the Boost Software License, Version 1.0. See
 <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/ LICENSE_1_0.txt</a></p>