Continue doc refinement.

doc/conversion.html

@@ -129,7 +129,8 @@ provided.</p>
 <p>The only supported types are four byte <code>float</code> and eight byte
 <code>double</code>. Even after endianness has been accounted for, floating 
 point values will not be portable between systems that use different floating 
-point formats.</p>
+point formats. Systems where the integer endianness and floating point 
+endianness are not supported.</p>
 
 </blockquote>
 
@@ -137,8 +138,8 @@ point formats.</p>
 
 <blockquote>
 
-<p>Only 16-bit, 32-bit, and 64-bit integers are supported. No tests have been 
+<p>Only 16-bit, 32-bit, and 64-bit integers are supported. Tests have been 
-performed on machines that do not use two's complement arithmetic.</p>
+performed on machines that  use two's complement arithmetic.</p>
 
 </blockquote>
 
@@ -367,7 +368,7 @@ convert(x, some_order, order::native);  // convert to native byte order if neede
 <p>Recent compilers, including GCC, Clang, and Microsoft, supply intrinsic built-in support for byte swapping. Such support is automatically detected and used since it results in smaller and much faster generated code for release builds.</p><p>Defining BOOST_ENDIAN_NO_INTRINSICS will suppress use of the intrinsics. Please try defining it if you get compiler errors, such as header byteswap.h not being found.</p><p>The macro BOOST_ENDIAN_INTRINSIC_MSG is defined as either <code>&quot;no byte swap intrinsics&quot;</code> or a string describing the particular set of intrinsics being used.</p><h2><a name="Acknowledgements">Acknowledgements</a></h2><p>Tomas Puverle was instrumental in identifying and articulating the need to 
 support endian conversion as separate from endian integer types. Phil Endecott suggested the form of the value returning signatures. Vicente Botet and other reviewers suggested supporting floating point types and user defined types. General reverse template implementation approach using std::reverse suggested by Mathias Gaunard. Portable implementation approach for 16, 32, and 64-bit integers suggested by tymofey, with avoidance of undefined behavior as suggested by Giovanni Piero Deretta, and a further refinement suggested by Pyry Jahkola. Intrinsic builtins implementation approach for 16, 32, and 64-bit integers suggested by several reviewers, and by David Stone, who provided his Boost licensed macro implementation that became the starting point for <a href="../include/boost/endian/detail/intrinsic.hpp">boost/endian/detail/intrinsic.hpp</a>.</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>
+<p>Last revised: <!--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>
 

doc/index.html

@@ -26,7 +26,7 @@
     <td><b><a href="../../../index.htm">Boost Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
     <a href="index.html">Endian Home</a>&nbsp;&nbsp;&nbsp;&nbsp;
     <a href="conversion.html">Conversion Functions</a>&nbsp;&nbsp;&nbsp;&nbsp;
-    <a href="types.html">Integer Types</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</b></td>
+    <a href="types.html">Endian Types</a>&nbsp;&nbsp;&nbsp;&nbsp; Tutorial</b></td>
   </tr>
 </table>
 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" align="right">
@@ -53,7 +53,7 @@
 </table>
 <h2><a name="Abstract">Abstract</a></h2>
 
-<p>Boost.Endian provides facilities to manipulate the byte ordering of integers.</p>
+<p>Boost.Endian provides two facilities to manipulate the byte ordering of integers.</p>
 <ul>
   <li>The primary use case is binary I/O of integers for portable exchange with 
   other systems, via either file or network transmission.<br>
@@ -64,16 +64,7 @@
 &nbsp;</li>
   <li>Two distinct approaches to byte ordering are provided. Each approach has a 
   long history of successful use, and each approach has use cases where it is 
-  superior to the other approach.<br>
+  superior to the other approach.</li>
-&nbsp;<ul>
-    <li>The explicit approach provides <a href="conversion.html">conversion 
-    functions</a> to reorder bytes. All four combinations of non-modifying or 
-    modifying, and unconditional or conditional, functions are provided.<br>
-&nbsp;</li>
-    <li>The implicit approach provides <a href="types.html">integer types</a> 
-    that mimic the built-in integers, implicitly handling all byte reordering.</li>
-  </ul>
-  </li>
 </ul>
 
 <h2><a name="Introduction-to-endianness">Introduction to endianness</a></h2>
@@ -82,16 +73,16 @@
 
 <blockquote>
   <pre>int16_t i = 0x0102;
-FILE * file = fopen(&quot;test&quot;, &quot;wb&quot;);   // MUST BE BINARY
+FILE * file = fopen(&quot;test.bin&quot;, &quot;wb&quot;);   // MUST BE BINARY
 fwrite(&amp;i, sizeof(int16_t), 1, file);
 fclose(file);</pre>
 </blockquote>
-<p>On an Apple, Linux, or Windows computer with an Intel CPU, a hex dump 
+<p>On OS X, Linux, or Windows systems with an Intel CPU, a hex dump 
-of the &quot;test&quot; output file produces:</p>
+of the &quot;test.bin&quot; output file produces:</p>
 <blockquote>
   <p><code>0201</code></p>
 </blockquote>
-<p>On an Apple or other computer with a PowerPC CPU, or an Oracle/Sun Solaris computer with a SPARC CPU, a hex dump of the &quot;test&quot; 
+<p>On OS X systems with a PowerPC CPU, or Solaris systems with a SPARC CPU, a hex dump of the &quot;test.bin&quot; 
 output file produces:</p>
 <blockquote>
   <p><code>0102</code></p>
@@ -111,9 +102,10 @@ at different ends.</p>
 <p>See the Wikipedia's
 <a href="http://en.wikipedia.org/wiki/Endianness">Endianness</a> article for an 
 extensive discussion of endianness.</p>
-<p>Except for reading an occasional core dump, most programmers can ignore 
+<p>Except for reading a core dump on little-endian systems, most programmers can 
-endianness. But when exchanging binary integers with other computer systems, whether by 
+ignore endianness. But when exchanging binary integers and binary floating point 
-file transfers or over a network, programmers have to deal with endianness. </p>
+values between computer systems with differing endianness, whether by physical file transfer or over a network, programmers have to deal with endianness 
+in their code. </p>
 <h2><a name="Introduction">Introduction</a> to the Boost.Endian library</h2>
 
 <p>The Boost.Endian library provides two facilities for dealing with endianness.</p>
@@ -185,28 +177,47 @@ application.</p>
   </tr>
 </table>
 
+<h2>Overall <a name="FAQ">FAQ</a></h2>
+<p><b>Why bother with endianness? Does endianness have any uses outside of 
+portable binary file or network I/O formats?</b> </p>
+<blockquote>
+<p>Binary data portability is the primary use case, and that implies I/O.</p>
+<p>Using the 3, 5, 6, and 7 byte integer types to save internal or external 
+memory space is a minor secondary use case.</p>
+</blockquote>
+<p><b>Why bother with binary I/O? Why not just use C++ Standard Library stream 
+inserters and extractors?</b></p>
+<blockquote>
+<p>Binary arithmetic data is smaller and therefore I/O is faster and file sizes 
+are smaller. Transfer between systems is less expensive. Standard interchange 
+formats often specify binary arithmetic data.</p>
+<p>Furthermore, binary arithmetic data is of fixed size, and so fixed-size disk 
+records are possible without padding, easing sorting and allowing direct access. 
+Disadvantages, such as the inability to use text utilities on the resulting 
+files, limit usefulness to applications where the binary I/O advantages are 
+paramount.</p>
+</blockquote>
+
 <h2><a name="Acknowledgements">Acknowledgements</a></h2>
 <p>Comments and suggestions were 
 received from
-Benaka Moorthi,
+Adder, Benaka Moorthi,
 Christopher Kohlhoff,
-Cliff Green, 
+Cliff Green,Daniel James, Gennaro Proto,
-Gennaro Proto,
+Giovanni Piero Deretta, Gordon Woodhull, dizzy, Hartmut Kaiser, Jeff Flinn,
-Giovanni Piero Deretta, dizzy, Jeff Flinn,
+John Filo, John Maddock,
-John Maddock,
 Kim Barrett,
 Marsh Ray,
-Martin Bonner,
+Martin Bonner, Mathias Gaunard, Matias Capeletto,
-Matias Capeletto,
+Neil Mayhew, Paul Bristow, Phil Endecott, Pyry Jahkola, Rene Rivera,
-Neil Mayhew, Phil Endecott, Rene Rivera,
 Robert Stewart, Roland Schwarz, Scott McMurray, 
 Sebastian Redl, 
-Tomas Puverle, Vincente Botet, and
+Tim Blechmann, Tim Moore, tymofey, Tomas Puverle, Vincente Botet, Yuval Ronen 
-Yuval Ronen.</p>
+and Vitaly Budovski,.</p>
 <hr>
 <p>Last revised:
 <!--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><EFBFBD> Copyright Beman Dawes, 2011, 2013</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>
 

doc/types.html

@@ -53,7 +53,7 @@
       <a href="#Design">Design</a><br>
       <a href="#Experience">Experience</a><br>
       <a href="#Motivating-use-cases">Motivating use cases</a><br>
-      <a href="#C++0x">C++0x</a><br>
+      <a href="#C++0x">C++11</a><br>
       <a href="#Compilation">Compilation</a><br>
       <a href="#Acknowledgements">Acknowledgements</a>
     </td>
@@ -178,9 +178,9 @@ because it has constructors, private data members, and a base class. This means
 that common use cases are relying on unspecified behavior in that the C++ 
 Standard does not guarantee memory layout for non-POD types. This has not been a 
 problem in practice since all known C++ compilers do layout memory as if <code>
-endian</code> were a POD type. In C++0x, it will be possible to specify the 
+endian</code> were a POD type. In C++11, it will be possible to specify the 
 default constructor as trivial, and private data members and base classes will 
-no longer disqualify a type from being a POD. Thus under C++0x, <code>endian</code> 
+no longer disqualify a type from being a POD. Thus under C++11, <code>endian</code> 
 will no longer be relying on unspecified behavior.</p>
 <h2><a name="Feature-set">Feature set</a></h2>
 <ul>
@@ -325,7 +325,7 @@ usual operations on integers are supplied.</p>
     public:
       typedef T value_type;
 
-      // if BOOST_ENDIAN_FORCE_PODNESS is defined &amp;&amp; C++0x POD's are not
+      // if BOOST_ENDIAN_FORCE_PODNESS is defined &amp;&amp; C++11 POD's are not
       // available then these two constructors will not be present
       <a href="#endian">endian</a>() = default;       // = default replaced by {} on C++03
       explicit <a href="#explicit-endian">endian</a>(T v);
@@ -477,7 +477,7 @@ alignment, so may be used to save memory in applications not related to I/O.</p>
 compared to arithmetic operations on native integer types. However, these types 
 are usually be faster, and sometimes much faster, for I/O compared to stream 
 inserters and extractors, or to serialization.</p>
-<p><b>Are endian types POD's?</b> Yes for C++0x. No for C++03, although several
+<p><b>Are endian types POD's?</b> Yes for C++11. No for C++03, although several
 <a href="#Compilation">macros</a> are available to force PODness in all cases.</p>
 <p><b>What are the implications endian integer types not being POD's with C++03 
 compilers?</b> They 
@@ -544,8 +544,8 @@ range of computer architectures and applications.</p>
 library: reading TrueType font files from disk and processing the contents. The 
 data format has fixed endianness (big) and has unaligned values in various 
 places. Using Boost.Endian simplifies and cleans the code wonderfully.&quot;</p>
-<h2><a name="C++0x">C++0x</a></h2>
+<h2><a name="C++0x">C++11</a></h2>
-<p>The availability of the C++0x
+<p>The availability of the C++11
 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">
 Defaulted Functions</a> feature is detected automatically, and will be used if 
 present to ensure that objects of <code>class endian</code> are trivial, and 
@@ -557,15 +557,15 @@ any Boost object libraries.</p>
 <ul>
   <li>BOOST_ENDIAN_NO_CTORS causes <code>class endian</code> to have no 
   constructors. The intended use is for compiling user code that must be 
-  portable between compilers regardless of C++0x
+  portable between compilers regardless of C++11
   <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">
   Defaulted Functions</a> support. Use of constructors will always fail, <br>
 &nbsp;</li>
   <li>BOOST_ENDIAN_FORCE_PODNESS causes BOOST_ENDIAN_NO_CTORS to be defined if 
-  the compiler does not support C++0x
+  the compiler does not support C++11
   <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">
   Defaulted Functions</a>. This is ensures that , and so can be used in unions. 
-  In C++0x, <code>class endian</code> objects are POD's even though they have 
+  In C++11, <code>class endian</code> objects are POD's even though they have 
   constructors.</li>
 </ul>
 <h2><a name="Acknowledgements">Acknowledgements</a></h2>
@@ -577,7 +577,7 @@ sign partial specialization to correctly extend the sign when cover integer size
 differs from endian representation size.</p>
 <hr>
 <p>Last revised:
-<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 September, 2011<!--webbot bot="Timestamp" endspan i-checksum="39338" --></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, 2006-2009</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>