PR69699 document why __GLIBCXX__ macro is useless

	PR libstdc++/69699
	* doc/xml/manual/abi.xml (abi.versioning.history): Explain why the
	_GLIBCXX__ macro is not useful. Remove redundant date information
	and link to the GCC release timeline.
	(abi.versioning.active): Move partial sentence into the previous
	paragraph.
	* doc/html/*: Regenerate.

From-SVN: r244532

3 files changed, 66 insertions, 46 deletions

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index a3f9b43..b00f7d3 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,5 +1,13 @@
 2017-01-17  Jonathan Wakely  <jwakely@redhat.com>
 
+	PR libstdc++/69699
+	* doc/xml/manual/abi.xml (abi.versioning.history): Explain why the
+	_GLIBCXX__ macro is not useful. Remove redundant date information
+	and link to the GCC release timeline.
+	(abi.versioning.active): Move partial sentence into the previous
+	paragraph.
+	* doc/html/*: Regenerate.
+
 	PR libstdc++/79114
 	* libsupc++/nested_exception.h (throw_with_nested): Use decay instead
 	of remove_reference.
diff --git a/libstdc++-v3/doc/html/manual/abi.html b/libstdc++-v3/doc/html/manual/abi.html
index 495d739..8988e45 100644
--- a/libstdc++-v3/doc/html/manual/abi.html
+++ b/libstdc++-v3/doc/html/manual/abi.html
@@ -153,12 +153,33 @@ compatible.
     was released, in compressed ISO date format, as an unsigned long.
     </p><p>
     This macro is defined in the file "c++config" in the
-    "libstdc++-v3/include/bits" directory. (Up to GCC 4.1.0, it was
-    changed every night by an automated script. Since GCC 4.1.0, it is
-    the same value as gcc/DATESTAMP.)
+    "libstdc++-v3/include/bits" directory. Up to GCC 4.1.0, it was
+    changed every night by an automated script. Since GCC 4.1.0 it is set
+    during configuration to the same value as
+    <code class="filename">gcc/DATESTAMP</code>, so for an official release its value
+    is the same as the date of the release, which is given in the <a class="link" href="https://gcc.gnu.org/develop.html#timeline" target="_top">GCC Release
+    Timeline</a>.
+    </p><p>
+    This macro is not useful for determining whether a particular feature is
+    supported by the version of libstdc++ you are using. The date of a release
+    might be after a feature was added to the development trunk, but the
+    release could be from an older branch. For example, in the 5.4.0 release
+    the macro has the value 20160603 which is greater than the 20160427 value
+    of the macro in the 6.1.0 release, but there are features supported in the
+    6.1.0 release that are not supported in 5.4.0 release.
+    You also can't test for the the exact values listed below to try and
+    identify a release, because a snapshot taken from the gcc-5-branch on
+    2016-04-27 would have the same value for the macro as the 6.1.0 release
+    despite being a different version.
+    Many GNU/Linux distributions build their GCC packages from snapshots, so
+    the macro can have dates that doesn't correspond to official releases.
     </p><p>
     It is versioned as follows:
-    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.0.0: 20010615</p></li><li class="listitem"><p>GCC 3.0.1: 20010819</p></li><li class="listitem"><p>GCC 3.0.2: 20011023</p></li><li class="listitem"><p>GCC 3.0.3: 20011220</p></li><li class="listitem"><p>GCC 3.0.4: 20020220</p></li><li class="listitem"><p>GCC 3.1.0: 20020514</p></li><li class="listitem"><p>GCC 3.1.1: 20020725</p></li><li class="listitem"><p>GCC 3.2.0: 20020814</p></li><li class="listitem"><p>GCC 3.2.1: 20021119</p></li><li class="listitem"><p>GCC 3.2.2: 20030205</p></li><li class="listitem"><p>GCC 3.2.3: 20030422</p></li><li class="listitem"><p>GCC 3.3.0: 20030513</p></li><li class="listitem"><p>GCC 3.3.1: 20030804</p></li><li class="listitem"><p>GCC 3.3.2: 20031016</p></li><li class="listitem"><p>GCC 3.3.3: 20040214</p></li><li class="listitem"><p>GCC 3.4.0: 20040419</p></li><li class="listitem"><p>GCC 3.4.1: 20040701</p></li><li class="listitem"><p>GCC 3.4.2: 20040906</p></li><li class="listitem"><p>GCC 3.4.3: 20041105</p></li><li class="listitem"><p>GCC 3.4.4: 20050519</p></li><li class="listitem"><p>GCC 3.4.5: 20051201</p></li><li class="listitem"><p>GCC 3.4.6: 20060306</p></li><li class="listitem"><p>GCC 4.0.0: 20050421</p></li><li class="listitem"><p>GCC 4.0.1: 20050707</p></li><li class="listitem"><p>GCC 4.0.2: 20050921</p></li><li class="listitem"><p>GCC 4.0.3: 20060309</p></li><li class="listitem"><p>GCC 4.1.0: 20060228</p></li><li class="listitem"><p>GCC 4.1.1: 20060524</p></li><li class="listitem"><p>GCC 4.1.2: 20070214</p></li><li class="listitem"><p>GCC 4.2.0: 20070514</p></li><li class="listitem"><p>GCC 4.2.1: 20070719</p></li><li class="listitem"><p>GCC 4.2.2: 20071007</p></li><li class="listitem"><p>GCC 4.2.3: 20080201</p></li><li class="listitem"><p>GCC 4.2.4: 20080519</p></li><li class="listitem"><p>GCC 4.3.0: 20080306</p></li><li class="listitem"><p>GCC 4.3.1: 20080606</p></li><li class="listitem"><p>GCC 4.3.2: 20080827</p></li><li class="listitem"><p>GCC 4.3.3: 20090124</p></li><li class="listitem"><p>GCC 4.3.4: 20090804</p></li><li class="listitem"><p>GCC 4.3.5: 20100522</p></li><li class="listitem"><p>GCC 4.3.6: 20110627</p></li><li class="listitem"><p>GCC 4.4.0: 20090421</p></li><li class="listitem"><p>GCC 4.4.1: 20090722</p></li><li class="listitem"><p>GCC 4.4.2: 20091015</p></li><li class="listitem"><p>GCC 4.4.3: 20100121</p></li><li class="listitem"><p>GCC 4.4.4: 20100429</p></li><li class="listitem"><p>GCC 4.4.5: 20101001</p></li><li class="listitem"><p>GCC 4.4.6: 20110416</p></li><li class="listitem"><p>GCC 4.4.7: 20120313</p></li><li class="listitem"><p>GCC 4.5.0: 20100414</p></li><li class="listitem"><p>GCC 4.5.1: 20100731</p></li><li class="listitem"><p>GCC 4.5.2: 20101216</p></li><li class="listitem"><p>GCC 4.5.3: 20110428</p></li><li class="listitem"><p>GCC 4.5.4: 20120702</p></li><li class="listitem"><p>GCC 4.6.0: 20110325</p></li><li class="listitem"><p>GCC 4.6.1: 20110627</p></li><li class="listitem"><p>GCC 4.6.2: 20111026</p></li><li class="listitem"><p>GCC 4.6.3: 20120301</p></li><li class="listitem"><p>GCC 4.7.0: 20120322</p></li><li class="listitem"><p>GCC 4.7.1: 20120614</p></li><li class="listitem"><p>GCC 4.7.2: 20120920</p></li></ul></div><p></p></li><li class="listitem"><p>
+    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.0.0: 20010615</p></li><li class="listitem"><p>GCC 3.0.1: 20010819</p></li><li class="listitem"><p>GCC 3.0.2: 20011023</p></li><li class="listitem"><p>GCC 3.0.3: 20011220</p></li><li class="listitem"><p>GCC 3.0.4: 20020220</p></li><li class="listitem"><p>GCC 3.1.0: 20020514</p></li><li class="listitem"><p>GCC 3.1.1: 20020725</p></li><li class="listitem"><p>GCC 3.2.0: 20020814</p></li><li class="listitem"><p>GCC 3.2.1: 20021119</p></li><li class="listitem"><p>GCC 3.2.2: 20030205</p></li><li class="listitem"><p>GCC 3.2.3: 20030422</p></li><li class="listitem"><p>GCC 3.3.0: 20030513</p></li><li class="listitem"><p>GCC 3.3.1: 20030804</p></li><li class="listitem"><p>GCC 3.3.2: 20031016</p></li><li class="listitem"><p>GCC 3.3.3: 20040214</p></li><li class="listitem"><p>GCC 3.4.0: 20040419</p></li><li class="listitem"><p>GCC 3.4.1: 20040701</p></li><li class="listitem"><p>GCC 3.4.2: 20040906</p></li><li class="listitem"><p>GCC 3.4.3: 20041105</p></li><li class="listitem"><p>GCC 3.4.4: 20050519</p></li><li class="listitem"><p>GCC 3.4.5: 20051201</p></li><li class="listitem"><p>GCC 3.4.6: 20060306</p></li><li class="listitem"><p>GCC 4.0.0: 20050421</p></li><li class="listitem"><p>GCC 4.0.1: 20050707</p></li><li class="listitem"><p>GCC 4.0.2: 20050921</p></li><li class="listitem"><p>GCC 4.0.3: 20060309</p></li><li class="listitem"><p>
+      GCC 4.1.0 and later: the GCC release date, as shown in the
+      <a class="link" href="https://gcc.gnu.org/develop.html#timeline" target="_top">GCC
+      Release Timeline</a>
+    </p></li></ul></div><p></p></li><li class="listitem"><p>
     Incremental bumping of a library pre-defined macro,
     _GLIBCPP_VERSION. This macro is defined as the released version of
     the library, as a string literal. This is only implemented in
@@ -226,13 +247,12 @@ compatible.
     </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.active"></a>Checking Active</h4></div></div></div><p>
       When the GNU C++ library is being built with symbol versioning
       on, you should see the following at configure time for
-      libstdc++:
+      libstdc++ (showing either 'gnu' or another of the supported styles):
     </p><pre class="screen">
 <code class="computeroutput">
   checking versioning on shared library symbols... gnu
 </code>
 </pre><p>
-  or another of the supported styles.
   If you don't see this line in the configure output, or if this line
   appears but the last word is 'no', then you are out of luck.
 </p><p>
diff --git a/libstdc++-v3/doc/xml/manual/abi.xml b/libstdc++-v3/doc/xml/manual/abi.xml
index 8e4a3fa..c818bd8 100644
--- a/libstdc++-v3/doc/xml/manual/abi.xml
+++ b/libstdc++-v3/doc/xml/manual/abi.xml
@@ -393,10 +393,32 @@ compatible.
 
     <para>
     This macro is defined in the file "c++config" in the
-    "libstdc++-v3/include/bits" directory. (Up to GCC 4.1.0, it was
-    changed every night by an automated script. Since GCC 4.1.0, it is
-    the same value as gcc/DATESTAMP.)
+    "libstdc++-v3/include/bits" directory. Up to GCC 4.1.0, it was
+    changed every night by an automated script. Since GCC 4.1.0 it is set
+    during configuration to the same value as
+    <filename>gcc/DATESTAMP</filename>, so for an official release its value
+    is the same as the date of the release, which is given in the <link
+      xmlns:xlink="http://www.w3.org/1999/xlink"
+      xlink:href="https://gcc.gnu.org/develop.html#timeline">GCC Release
+    Timeline</link>.
     </para>
+
+    <para>
+    This macro is not useful for determining whether a particular feature is
+    supported by the version of libstdc++ you are using. The date of a release
+    might be after a feature was added to the development trunk, but the
+    release could be from an older branch. For example, in the 5.4.0 release
+    the macro has the value 20160603 which is greater than the 20160427 value
+    of the macro in the 6.1.0 release, but there are features supported in the
+    6.1.0 release that are not supported in 5.4.0 release.
+    You also can't test for the the exact values listed below to try and
+    identify a release, because a snapshot taken from the gcc-5-branch on
+    2016-04-27 would have the same value for the macro as the 6.1.0 release
+    despite being a different version.
+    Many GNU/Linux distributions build their GCC packages from snapshots, so
+    the macro can have dates that doesn't correspond to official releases.
+    </para>
+
     <para>
     It is versioned as follows:
     </para>
@@ -427,41 +449,12 @@ compatible.
     <listitem><para>GCC 4.0.1: 20050707</para></listitem>
     <listitem><para>GCC 4.0.2: 20050921</para></listitem>
     <listitem><para>GCC 4.0.3: 20060309</para></listitem>
-    <listitem><para>GCC 4.1.0: 20060228</para></listitem>
-    <listitem><para>GCC 4.1.1: 20060524</para></listitem>
-    <listitem><para>GCC 4.1.2: 20070214</para></listitem>
-    <listitem><para>GCC 4.2.0: 20070514</para></listitem>
-    <listitem><para>GCC 4.2.1: 20070719</para></listitem>
-    <listitem><para>GCC 4.2.2: 20071007</para></listitem>
-    <listitem><para>GCC 4.2.3: 20080201</para></listitem>
-    <listitem><para>GCC 4.2.4: 20080519</para></listitem>
-    <listitem><para>GCC 4.3.0: 20080306</para></listitem>
-    <listitem><para>GCC 4.3.1: 20080606</para></listitem>
-    <listitem><para>GCC 4.3.2: 20080827</para></listitem>
-    <listitem><para>GCC 4.3.3: 20090124</para></listitem>
-    <listitem><para>GCC 4.3.4: 20090804</para></listitem>
-    <listitem><para>GCC 4.3.5: 20100522</para></listitem>
-    <listitem><para>GCC 4.3.6: 20110627</para></listitem>
-    <listitem><para>GCC 4.4.0: 20090421</para></listitem>
-    <listitem><para>GCC 4.4.1: 20090722</para></listitem>
-    <listitem><para>GCC 4.4.2: 20091015</para></listitem>
-    <listitem><para>GCC 4.4.3: 20100121</para></listitem>
-    <listitem><para>GCC 4.4.4: 20100429</para></listitem>
-    <listitem><para>GCC 4.4.5: 20101001</para></listitem>
-    <listitem><para>GCC 4.4.6: 20110416</para></listitem>
-    <listitem><para>GCC 4.4.7: 20120313</para></listitem>
-    <listitem><para>GCC 4.5.0: 20100414</para></listitem>
-    <listitem><para>GCC 4.5.1: 20100731</para></listitem>
-    <listitem><para>GCC 4.5.2: 20101216</para></listitem>
-    <listitem><para>GCC 4.5.3: 20110428</para></listitem>
-    <listitem><para>GCC 4.5.4: 20120702</para></listitem>
-    <listitem><para>GCC 4.6.0: 20110325</para></listitem>
-    <listitem><para>GCC 4.6.1: 20110627</para></listitem>
-    <listitem><para>GCC 4.6.2: 20111026</para></listitem>
-    <listitem><para>GCC 4.6.3: 20120301</para></listitem>
-    <listitem><para>GCC 4.7.0: 20120322</para></listitem>
-    <listitem><para>GCC 4.7.1: 20120614</para></listitem>
-    <listitem><para>GCC 4.7.2: 20120920</para></listitem>
+    <listitem><para>
+      GCC 4.1.0 and later: the GCC release date, as shown in the
+      <link xmlns:xlink="http://www.w3.org/1999/xlink"
+        xlink:href="https://gcc.gnu.org/develop.html#timeline">GCC
+      Release Timeline</link>
+    </para></listitem>
     </itemizedlist>
     <para/>
     </listitem>
@@ -619,7 +612,7 @@ compatible.
     <para>
       When the GNU C++ library is being built with symbol versioning
       on, you should see the following at configure time for
-      libstdc++:
+      libstdc++ (showing either 'gnu' or another of the supported styles):
     </para>
 
 <screen>
@@ -629,7 +622,6 @@ compatible.
 </screen>
 
 <para>
-  or another of the supported styles.
   If you don't see this line in the configure output, or if this line
   appears but the last word is 'no', then you are out of luck.
 </para>