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

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index a3f9b43ccbe84e2b1820323b97587cbd6d72919a..b00f7d3ab7861029eda7d89f6184686a1998d052 100644 (file)
--- 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 495d7395564ba010fdb3034866146c03ef78cb5f..8988e4559a6479907e3ba0292d29cb29bf68e59b 100644 (file)
--- 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 8e4a3fa7273b66f7677fa480681b1d8bb54a27a8..c818bd86605321f5ca7630968b54d673c5914bd3 100644 (file)
--- 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>