Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r59514 - in trunk/libs/config/doc: . html html/boost_config
From: john_at_[hidden]
Date: 2010-02-05 13:12:36


Author: johnmaddock
Date: 2010-02-05 13:12:35 EST (Fri, 05 Feb 2010)
New Revision: 59514
URL: http://svn.boost.org/trac/boost/changeset/59514

Log:
Add BOOST_WORKAROUND docs.
Fixes #3782.
Text files modified:
   trunk/libs/config/doc/html/boost_config/acknowledgements.html | 4 +-
   trunk/libs/config/doc/html/boost_config/boost_macro_reference.html | 51 ++++++++++++++++++++++++++++++++++++++-
   trunk/libs/config/doc/html/boost_config/guidelines_for_boost_authors.html | 22 ++++++----------
   trunk/libs/config/doc/html/boost_config/rationale.html | 4 +-
   trunk/libs/config/doc/html/index.html | 8 +++---
   trunk/libs/config/doc/macro_reference.qbk | 28 +++++++++++++++++++++
   6 files changed, 93 insertions(+), 24 deletions(-)

Modified: trunk/libs/config/doc/html/boost_config/acknowledgements.html
==============================================================================
--- trunk/libs/config/doc/html/boost_config/acknowledgements.html (original)
+++ trunk/libs/config/doc/html/boost_config/acknowledgements.html 2010-02-05 13:12:35 EST (Fri, 05 Feb 2010)
@@ -1,6 +1,6 @@
 <html>
 <head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
 <title>Acknowledgements</title>
 <link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
 <meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
@@ -47,7 +47,7 @@
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 <td align="left"></td>
-<td align="right"><div class="copyright-footer">Copyright © 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock<p>
+<td align="right"><div class="copyright-footer">Copyright &#169; 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock<p>
         Distributed under the Boost Software License, Version 1.0. (See accompanying
         file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
       </p>

Modified: trunk/libs/config/doc/html/boost_config/boost_macro_reference.html
==============================================================================
--- trunk/libs/config/doc/html/boost_config/boost_macro_reference.html (original)
+++ trunk/libs/config/doc/html/boost_config/boost_macro_reference.html 2010-02-05 13:12:35 EST (Fri, 05 Feb 2010)
@@ -1,6 +1,6 @@
 <html>
 <head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
 <title>Boost Macro Reference</title>
 <link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
 <meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
@@ -2851,6 +2851,53 @@
 <tr>
 <td>
               <p>
+ <code class="computeroutput"><span class="identifier">BOOST_WORKAROUND</span></code>
+ </p>
+ </td>
+<td>
+ <p>
+ This macro is used where a compiler specific workaround is required
+ that is not otherwise described by one of the other Boost.Config
+ macros. To use the macro you must first
+</p>
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">detail</span><span class="special">/</span><span class="identifier">workaround</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ usage is then:
+</p>
+<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#if</span> <span class="identifier">BOOST_WORKAROUND</span><span class="special">(</span><span class="identifier">MACRONAME</span><span class="special">,</span> <span class="identifier">CONDITION</span><span class="special">)</span>
+ <span class="comment">// workaround code goes here...
+</span><span class="preprocessor">#else</span>
+ <span class="comment">// Standard conforming code goes here...
+</span><span class="preprocessor">#endif</span>
+</pre>
+<p>
+ where <code class="computeroutput"><span class="identifier">MACRONAME</span></code> is
+ a macro that usually describes the version number to be tested against,
+ and <code class="computeroutput"><span class="identifier">CONDITION</span></code> is
+ a comparison operator followed by a value. For example <code class="computeroutput"><span class="identifier">BOOST_WORKAROUND</span><span class="special">(</span><span class="identifier">BOOST_INTEL</span><span class="special">,</span>
+ <span class="special">&lt;=</span> <span class="number">1010</span><span class="special">)</span></code> would evaluate to <code class="computeroutput"><span class="number">1</span></code> for Intel C++ 10.1 and earlier.
+ </p>
+ <p>
+ The macro can also be used with <code class="computeroutput"><span class="identifier">BOOST_TESTED_AT</span></code>
+ if all current compiler versions exhibit the issue, but the issue
+ is expected to be fixed at some later point.
+ </p>
+ <p>
+ For example <code class="computeroutput"><span class="identifier">BOOST_WORKAROUND</span><span class="special">(</span><span class="identifier">__BORLANDC__</span><span class="special">,</span> <span class="identifier">BOOST_TESTED_AT</span><span class="special">(</span><span class="number">0x590</span><span class="special">))</span></code> would normally evaluate to <code class="computeroutput"><span class="number">1</span></code> for all values of <code class="computeroutput"><span class="identifier">__BORLANDC__</span></code>
+ <span class="emphasis"><em>unless</em></span> the macro <code class="computeroutput"><span class="identifier">BOOST_DETECT_OUTDATED_WORKAROUNDS</span></code>
+ is defined, in which case evaluates to <code class="computeroutput"><span class="special">(</span><span class="identifier">__BORLANDC__</span> <span class="special">&lt;=</span>
+ <span class="number">0x590</span><span class="special">)</span></code>.
+ </p>
+ <p>
+ <span class="bold"><strong>Note</strong></span>: the ultimate source of documentation
+ for this macro is in boost/detail/workaround.hpp.
+ </p>
+ </td>
+</tr>
+<tr>
+<td>
+ <p>
                 <code class="computeroutput"><span class="identifier">BOOST_DEDUCED_TYPENAME</span></code>
               </p>
               </td>
@@ -3534,7 +3581,7 @@
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 <td align="left"></td>
-<td align="right"><div class="copyright-footer">Copyright © 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock<p>
+<td align="right"><div class="copyright-footer">Copyright &#169; 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock<p>
         Distributed under the Boost Software License, Version 1.0. (See accompanying
         file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
       </p>

Modified: trunk/libs/config/doc/html/boost_config/guidelines_for_boost_authors.html
==============================================================================
--- trunk/libs/config/doc/html/boost_config/guidelines_for_boost_authors.html (original)
+++ trunk/libs/config/doc/html/boost_config/guidelines_for_boost_authors.html 2010-02-05 13:12:35 EST (Fri, 05 Feb 2010)
@@ -1,11 +1,10 @@
 <html>
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
-<title>Guidelines for
- Boost Authors</title>
+<title>Guidelines for Boost Authors</title>
 <link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
-<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
-<link rel="start" href="../index.html" title="Boost.Config">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../index.html" title="Boost.Config">
 <link rel="up" href="../index.html" title="Boost.Config">
 <link rel="prev" href="boost_macro_reference.html" title="Boost Macro Reference">
 <link rel="next" href="rationale.html" title="Rationale">
@@ -25,8 +24,7 @@
 </div>
 <div class="section" lang="en">
 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="boost_config.guidelines_for_boost_authors"></a><a href="guidelines_for_boost_authors.html" title="Guidelines for
- Boost Authors">Guidelines for
+<a name="boost_config.guidelines_for_boost_authors"></a><a class="link" href="guidelines_for_boost_authors.html" title="Guidelines for Boost Authors">Guidelines for
     Boost Authors</a>
 </h2></div></div></div>
 <div class="toc"><dl>
@@ -107,8 +105,7 @@
 </ul></div>
 <div class="section" lang="en">
 <div class="titlepage"><div><div><h3 class="title">
-<a name="boost_config.guidelines_for_boost_authors.warnings"></a><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.warnings" title="
- Disabling Compiler Warnings">
+<a name="boost_config.guidelines_for_boost_authors.warnings"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.warnings" title="Disabling Compiler Warnings">
       Disabling Compiler Warnings</a>
 </h3></div></div></div>
 <p>
@@ -187,8 +184,7 @@
 </div>
 <div class="section" lang="en">
 <div class="titlepage"><div><div><h3 class="title">
-<a name="boost_config.guidelines_for_boost_authors.adding_new_defect_macros"></a><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros" title="Adding
- New Defect Macros">Adding
+<a name="boost_config.guidelines_for_boost_authors.adding_new_defect_macros"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_defect_macros" title="Adding New Defect Macros">Adding
       New Defect Macros</a>
 </h3></div></div></div>
 <p>
@@ -289,8 +285,7 @@
 </div>
 <div class="section" lang="en">
 <div class="titlepage"><div><div><h3 class="title">
-<a name="boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros"></a><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros" title="Adding
- New Feature Test Macros">Adding
+<a name="boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.adding_new_feature_test_macros" title="Adding New Feature Test Macros">Adding
       New Feature Test Macros</a>
 </h3></div></div></div>
 <p>
@@ -314,8 +309,7 @@
 </div>
 <div class="section" lang="en">
 <div class="titlepage"><div><div><h3 class="title">
-<a name="boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers"></a><a href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers" title="Modifying
- the Boost Configuration Headers">Modifying
+<a name="boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers"></a><a class="link" href="guidelines_for_boost_authors.html#boost_config.guidelines_for_boost_authors.modifying_the_boost_configuration_headers" title="Modifying the Boost Configuration Headers">Modifying
       the Boost Configuration Headers</a>
 </h3></div></div></div>
 <p>

Modified: trunk/libs/config/doc/html/boost_config/rationale.html
==============================================================================
--- trunk/libs/config/doc/html/boost_config/rationale.html (original)
+++ trunk/libs/config/doc/html/boost_config/rationale.html 2010-02-05 13:12:35 EST (Fri, 05 Feb 2010)
@@ -1,6 +1,6 @@
 <html>
 <head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
 <title>Rationale</title>
 <link rel="stylesheet" href="../../../../../doc/html/boostbook.css" type="text/css">
 <meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
@@ -121,7 +121,7 @@
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 <td align="left"></td>
-<td align="right"><div class="copyright-footer">Copyright © 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock<p>
+<td align="right"><div class="copyright-footer">Copyright &#169; 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock<p>
         Distributed under the Boost Software License, Version 1.0. (See accompanying
         file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
       </p>

Modified: trunk/libs/config/doc/html/index.html
==============================================================================
--- trunk/libs/config/doc/html/index.html (original)
+++ trunk/libs/config/doc/html/index.html 2010-02-05 13:12:35 EST (Fri, 05 Feb 2010)
@@ -1,6 +1,6 @@
 <html>
 <head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
 <title>Boost.Config</title>
 <link rel="stylesheet" href="../../../../doc/html/boostbook.css" type="text/css">
 <meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
@@ -26,9 +26,9 @@
 <div><div class="authorgroup"><div class="author"><h3 class="author">
 <span class="firstname">Vesa Karvonen, John Maddock</span> <span class="surname">Beman Dawes</span>
 </h3></div></div></div>
-<div><p class="copyright">Copyright © 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock</p></div>
+<div><p class="copyright">Copyright &#169; 2001 -2007 Beman Dawes, Vesa Karvonen, John Maddock</p></div>
 <div><div class="legalnotice">
-<a name="id770460"></a><p>
+<a name="id771940"></a><p>
         Distributed under the Boost Software License, Version 1.0. (See accompanying
         file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
       </p>
@@ -960,7 +960,7 @@
 </div>
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: August 06, 2009 at 09:16:56 GMT</small></p></td>
+<td align="left"><p><small>Last revised: February 05, 2010 at 17:46:05 GMT</small></p></td>
 <td align="right"><div class="copyright-footer"></div></td>
 </tr></table>
 <hr>

Modified: trunk/libs/config/doc/macro_reference.qbk
==============================================================================
--- trunk/libs/config/doc/macro_reference.qbk (original)
+++ trunk/libs/config/doc/macro_reference.qbk 2010-02-05 13:12:35 EST (Fri, 05 Feb 2010)
@@ -633,6 +633,34 @@
 [table
 [[Macro ][Description ]]
 
+[[`BOOST_WORKAROUND`][
+This macro is used where a compiler specific workaround is required that is not otherwise
+described by one of the other Boost.Config macros. To use the macro you must first
+``
+#include <boost/detail/workaround.hpp>
+``
+usage is then:
+``
+#if BOOST_WORKAROUND(MACRONAME, CONDITION)
+ // workaround code goes here...
+#else
+ // Standard conforming code goes here...
+#endif
+``
+where `MACRONAME` is a macro that usually describes the version number to be tested against, and `CONDITION`
+is a comparison operator followed by a value. For example `BOOST_WORKAROUND(BOOST_INTEL, <= 1010)` would
+evaluate to `1` for Intel C++ 10.1 and earlier.
+
+The macro can also be used with `BOOST_TESTED_AT` if all
+current compiler versions exhibit the issue, but the issue is expected to be fixed at some later point.
+
+For example
+`BOOST_WORKAROUND(__BORLANDC__, BOOST_TESTED_AT(0x590))` would normally evaluate to `1` for all values
+of `__BORLANDC__` /unless/ the macro `BOOST_DETECT_OUTDATED_WORKAROUNDS` is defined, in which case evaluates to
+`(__BORLANDC__ <= 0x590)`.
+
+[*Note]: the ultimate source of documentation for this macro is in [@../../../../boost/detail/workaround.hpp boost/detail/workaround.hpp].
+]]
 [[`BOOST_DEDUCED_TYPENAME`][
 Some compilers don't support the use of typename for dependent types in deduced
 contexts. This macro expands to nothing on those compilers, and typename


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk