libstdc++-v3/doc/xml/manual/backwards_compatibility.xml

libstdc++-v3/doc/xml/manual/backwards_compatibility.xml

[Gerald Pfeifer]

I noticed this section on "Backwards Compatibility" in the libstdc++
docs that talks about

 - glibc 2.0.x
 - GCC 3.2 (August 2002)
 - GCC 4.1 (February 2006) 

and links to "Migrating to GCC 4.1" and "Migration guide for GCC-3.2"
documents.

Does this still make sense (and serve real users or developers) or
should this be trimmed quite a bit?

Gerald

Re: libstdc++-v3/doc/xml/manual/backwards_compatibility.xml

[Jonathan Wakely]

Sorry for the slow reply ...

On Mon, 1 Feb 2021 at 22:59, Gerald Pfeifer wrote:
>
> I noticed this section on "Backwards Compatibility" in the libstdc++
> docs that talks about
>
>  - glibc 2.0.x
>  - GCC 3.2 (August 2002)
>  - GCC 4.1 (February 2006)
>
> and links to "Migrating to GCC 4.1" and "Migration guide for GCC-3.2"
> documents.
>
> Does this still make sense (and serve real users or developers) or
> should this be trimmed quite a bit?

Yeah, that (and a lot more) should be trimmed from the libstdc++
manual. It's just time consuming to do it.

Re: libstdc++-v3/doc/xml/manual/backwards_compatibility.xml

[Jonathan Wakely]

[-- Attachment #1: Type: text/plain, Size: 920 bytes --]

On 13/04/21 16:19 +0100, Jonathan Wakely via Libstdc++ wrote:
>Sorry for the slow reply ...
>
>On Mon, 1 Feb 2021 at 22:59, Gerald Pfeifer wrote:
>>
>> I noticed this section on "Backwards Compatibility" in the libstdc++
>> docs that talks about
>>
>>  - glibc 2.0.x
>>  - GCC 3.2 (August 2002)
>>  - GCC 4.1 (February 2006)
>>
>> and links to "Migrating to GCC 4.1" and "Migration guide for GCC-3.2"
>> documents.
>>
>> Does this still make sense (and serve real users or developers) or
>> should this be trimmed quite a bit?
>
>Yeah, that (and a lot more) should be trimmed from the libstdc++
>manual. It's just time consuming to do it.

It turned out to be pretty easy in this case, as the ancient text was
so obviously useless now that it can just be ripped out.

The remaining parts of the page should probably be evaluated too, but
at least the truly prehistoric stuff is gone with this patch.

Pushed to trunk.



[-- Attachment #2: patch.txt --]
[-- Type: text/x-patch, Size: 20316 bytes --]

commit 989e512f719a44fafca0030d7b8a1f5bf5f1baf7
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Tue Apr 13 16:30:16 2021

    libstdc++: Remove outdated docs on libg++ and libstdc++-v2
    
    The libstdc++-v3 manual doesn't need to document how to use its
    predecessors.
    
    libstdc++-v3/ChangeLog:
    
            * doc/xml/manual/backwards_compatibility.xml: Remove porting
            notes for libg++ and libstdc++-v2, and bibliography.
            * doc/html/*: Regenerated.

diff --git a/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml b/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml
index cce553380e1..6a4a5ccedfb 100644
--- a/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml
+++ b/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml
@@ -22,7 +22,7 @@ dinosaur.
 
 <para>Some background: libg++ was designed and created when there was no
 ISO standard to provide guidance.  Classes like linked lists are now
-provided for by <classname>list&lt;T&gt;</classname> and do not need to be
+provided for by <classname>std::list&lt;T&gt;</classname> and do not need to be
 created by <function>genclass</function>.  (For that matter, templates exist
 now and are well-supported, whereas genclass (mostly) predates them.)
 </para>
@@ -34,41 +34,13 @@ Committee couldn't include everything, and so a lot of those
 <quote>obvious</quote> classes didn't get included.
 </para>
 
-<para>Known Issues include many of the limitations of its immediate ancestor.</para>
-
-<para>Portability notes and known implementation limitations are as follows.</para>
-
-<section xml:id="backwards.first.ios_base"><info><title>No <code>ios_base</code></title></info>
-
-
-<para> At least some older implementations don't have <code>std::ios_base</code>, so you should use <code>std::ios::badbit</code>, <code>std::ios::failbit</code> and <code>std::ios::eofbit</code> and <code>std::ios::goodbit</code>.
+<para>That project is no longer maintained or supported, and the sources
+archived. For the desperate, the
+<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://ftp.gnu.org/old-gnu/libg++/">ftp.gnu.org</link>
+server still has the libg++ source.
 </para>
 </section>
 
-<section xml:id="backwards.first.cout_cin"><info><title>No <code>cout</code> in <filename class="headerfile">&lt;ostream.h&gt;</filename>, no <code>cin</code> in <filename class="headerfile">&lt;istream.h&gt;</filename></title></info>
-
-
-<para>
-	In earlier versions of the standard,
-	<filename class="headerfile">&lt;fstream.h&gt;</filename>,
-	<filename class="headerfile">&lt;ostream.h&gt;</filename>
-	and <filename class="headerfile">&lt;istream.h&gt;</filename>
-	used to define
-	<code>cout</code>, <code>cin</code> and so on. ISO C++ specifies that one needs to include
-	<filename class="headerfile">&lt;iostream&gt;</filename>
-	explicitly to get the required definitions.
- </para>
-<para> Some include adjustment may be required.</para>
-
-<para>This project is no longer maintained or supported, and the sources
-archived. For the desperate,
-the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/extensions.html">GCC extensions
-page</link> describes where to find the last libg++ source. The code is
-considered replaced and rewritten.
-</para>
-</section>
-</section>
-
 <section xml:id="backwards.second"><info><title>Second</title></info>
 
 
@@ -80,504 +52,14 @@ considered replaced and rewritten.
 </para>
 
 <para>
-  The STL portions of this library are based on SGI/HP STL release 3.11.
+  The STL portions of that library are based on SGI/HP STL release 3.11.
 </para>
 
 <para>
-  This project is no longer maintained or supported, and the sources
-  archived.  The code is considered replaced and rewritten.
+  That project is no longer maintained or supported, and the sources
+  archived.  The code was replaced and rewritten for libstdc++-v3.
 </para>
 
-<para>
-  Portability notes and known implementation limitations are as follows.
-</para>
-
-<section xml:id="backwards.second.std"><info><title>Namespace <code>std::</code> not supported</title></info>
-
-
-  <para>
-    Some care is required to support C++ compiler and or library
-    implementation that do not have the standard library in
-    <code>namespace std</code>.
-  </para>
-
-  <para>
-    The following sections list some possible solutions to support compilers
-    that cannot ignore <code>std::</code>-qualified names.
-  </para>
-
-  <para>
-    First, see if the compiler has a flag for this. Namespace
-    back-portability-issues are generally not a problem for g++
-    compilers that do not have libstdc++ in <code>std::</code>, as the
-    compilers use <option>-fno-honor-std</option> (ignore
-    <code>std::</code>, <code>:: = std::</code>) by default. That is,
-    the responsibility for enabling or disabling <code>std::</code> is
-    on the user; the maintainer does not have to care about it. This
-    probably applies to some other compilers as well.
-  </para>
-
-  <para>
-    Second, experiment with a variety of pre-processor tricks.
-  </para>
-
-  <para>
-    By defining <code>std</code> as a macro, fully-qualified namespace
-    calls become global. Volia.
-  </para>
-
-<programlisting>
-#ifdef WICKEDLY_OLD_COMPILER
-# define std
-#endif
-</programlisting>
-
-  <para>
-    Thanks to Juergen Heinzl who posted this solution on gnu.gcc.help.
-  </para>
-
-  <para>
-    Another pre-processor based approach is to define a macro
-    <code>NAMESPACE_STD</code>, which is defined to either
-    <quote> </quote> or <quote>std</quote> based on a compile-type
-    test. On GNU systems, this can be done with autotools by means of
-    an autoconf test (see below) for <code>HAVE_NAMESPACE_STD</code>,
-    then using that to set a value for the <code>NAMESPACE_STD</code>
-    macro.  At that point, one is able to use
-    <code>NAMESPACE_STD::string</code>, which will evaluate to
-    <code>std::string</code> or <code>::string</code> (i.e., in the
-    global namespace on systems that do not put <code>string</code> in
-    <code>std::</code>).
-  </para>
-
-<programlisting>
-dnl @synopsis AC_CXX_NAMESPACE_STD
-dnl
-dnl If the compiler supports namespace std, define
-dnl HAVE_NAMESPACE_STD.
-dnl
-dnl @category Cxx
-dnl @author Todd Veldhuizen
-dnl @author Luc Maisonobe &lt;luc@spaceroots.org&gt;
-dnl @version 2004-02-04
-dnl @license AllPermissive
-AC_DEFUN([AC_CXX_NAMESPACE_STD], [
-  AC_CACHE_CHECK(if g++ supports namespace std,
-  ac_cv_cxx_have_std_namespace,
-  [AC_LANG_SAVE
-  AC_LANG_CPLUSPLUS
-  AC_TRY_COMPILE([#include &lt;iostream&gt;
-		  std::istream&amp; is = std::cin;],,
-  ac_cv_cxx_have_std_namespace=yes, ac_cv_cxx_have_std_namespace=no)
-  AC_LANG_RESTORE
-  ])
-  if test "$ac_cv_cxx_have_std_namespace" = yes; then
-    AC_DEFINE(HAVE_NAMESPACE_STD,,[Define if g++ supports namespace std. ])
-  fi
-])
-</programlisting>
-</section>
-
-<section xml:id="backwards.second.iterators"><info><title>Illegal iterator usage</title></info>
-
-<para>
-  The following illustrate implementation-allowed illegal iterator
-  use, and then correct use.
-</para>
-
-<itemizedlist>
-  <listitem>
-    <para>
-      you cannot do <code>ostream::operator&lt;&lt;(iterator)</code>
-      to print the address of the iterator =&gt; use
-      <code>operator&lt;&lt; &amp;*iterator</code> instead
-    </para>
-  </listitem>
-  <listitem>
-    <para>
-      you cannot clear an iterator's reference (<code>iterator =
-      0</code>) =&gt; use <code>iterator = iterator_type();</code>
-    </para>
-  </listitem>
-  <listitem>
-    <para>
-      <code>if (iterator)</code> won't work any more =&gt; use
-      <code>if (iterator != iterator_type())</code>
-    </para>
-  </listitem>
-</itemizedlist>
-</section>
-
-<section xml:id="backwards.second.isspace"><info><title><code>isspace</code> from <filename class="headerfile">&lt;cctype&gt;</filename> is a macro
-  </title></info>
-
-
-  <para>
-    Glibc 2.0.x and 2.1.x define <filename class="headerfile">&lt;ctype.h&gt;</filename> functionality as macros
-    (isspace, isalpha etc.).
-  </para>
-
-  <para>
-    This implementations of libstdc++, however, keep these functions
-    as macros, and so it is not back-portable to use fully qualified
-    names. For example:
-  </para>
-
-<programlisting>
-#include &lt;cctype&gt;
-int main() { std::isspace('X'); }
-</programlisting>
-
-<para>
-  Results in something like this:
-</para>
-
-<programlisting>
-std:: (__ctype_b[(int) ( ( 'X' ) )] &amp; (unsigned short int) _ISspace ) ;
-</programlisting>
-
-<para>
-  A solution is to modify a header-file so that the compiler tells
-  <filename class="headerfile">&lt;ctype.h&gt;</filename> to define functions
-  instead of macros:
-</para>
-
-<programlisting>
-// This keeps isalnum, et al from being propagated as macros.
-#if __linux__
-# define __NO_CTYPE 1
-#endif
-</programlisting>
-
-<para>
-  Then, include <filename class="headerfile">&lt;ctype.h&gt;</filename>
-</para>
-
-<para>
-  Another problem arises if you put a <code>using namespace
-  std;</code> declaration at the top, and include
-  <filename class="headerfile">&lt;ctype.h&gt;</filename>. This will
-  result in ambiguities between the definitions in the global namespace
-  (<filename class="headerfile">&lt;ctype.h&gt;</filename>) and the
-  definitions in namespace <code>std::</code>
-  (<code>&lt;cctype&gt;</code>).
-</para>
-</section>
-
-<section xml:id="backwards.second.at"><info><title>No <code>vector::at</code>, <code>deque::at</code>, <code>string::at</code></title></info>
-
-
-<para>
-  One solution is to add an autoconf-test for this:
-</para>
-
-<programlisting>
-AC_MSG_CHECKING(for container::at)
-AC_TRY_COMPILE(
-[
-#include &lt;vector&gt;
-#include &lt;deque&gt;
-#include &lt;string&gt;
-
-using namespace std;
-],
-[
-deque&lt;int&gt; test_deque(3);
-test_deque.at(2);
-vector&lt;int&gt; test_vector(2);
-test_vector.at(1);
-string test_string(<quote>test_string</quote>);
-test_string.at(3);
-],
-[AC_MSG_RESULT(yes)
-AC_DEFINE(HAVE_CONTAINER_AT)],
-[AC_MSG_RESULT(no)])
-</programlisting>
-
-<para>
-  If you are using other (non-GNU) compilers it might be a good idea
-  to check for <code>string::at</code> separately.
-</para>
-
-</section>
-
-<section xml:id="backwards.second.eof"><info><title>No <code>std::char_traits&lt;char&gt;::eof</code></title></info>
-
-
-<para>
-  Use some kind of autoconf test, plus this:
-</para>
-
-<programlisting>
-#ifdef HAVE_CHAR_TRAITS
-#define CPP_EOF std::char_traits&lt;char&gt;::eof()
-#else
-#define CPP_EOF EOF
-#endif
-</programlisting>
-
-</section>
-
-<section xml:id="backwards.second.stringclear"><info><title>No <code>string::clear</code></title></info>
-
-
-<para>
-  There are two functions for deleting the contents of a string:
-  <code>clear</code> and <code>erase</code> (the latter returns the
-  string).
-</para>
-
-<programlisting>
-void
-clear() { _M_mutate(0, this-&gt;size(), 0); }
-</programlisting>
-
-<programlisting>
-basic_string&amp;
-erase(size_type __pos = 0, size_type __n = npos)
-{
-  return this-&gt;replace(_M_check(__pos), _M_fold(__pos, __n),
-			  _M_data(), _M_data());
-}
-</programlisting>
-
-<para>
-  Unfortunately, <code>clear</code> is not implemented in this
-  version, so you should use <code>erase</code> (which is probably
-  faster than <code>operator=(charT*)</code>).
-</para>
-</section>
-
-<section xml:id="backwards.second.ostreamform_istreamscan"><info><title>
-  Removal of <code>ostream::form</code> and <code>istream::scan</code>
-  extensions
-</title></info>
-
-
-<para>
-  These are no longer supported. Please use stringstreams instead.
-</para>
-</section>
-
-<section xml:id="backwards.second.stringstreams"><info><title>No <code>basic_stringbuf</code>, <code>basic_stringstream</code></title></info>
-
-
-<para>
-  Although the ISO standard <code>i/ostringstream</code>-classes are
-  provided, (<filename class="headerfile">&lt;sstream&gt;</filename>), for
-  compatibility with older implementations the pre-ISO
-  <code>i/ostrstream</code> (<filename class="headerfile">&lt;strstream&gt;</filename>) interface is also provided,
-  with these caveats:
-</para>
-
-<itemizedlist>
-  <listitem>
-    <para>
-      <code>strstream</code> is considered to be deprecated
-    </para>
-  </listitem>
-  <listitem>
-    <para>
-      <code>strstream</code> is limited to <code>char</code>
-    </para>
-  </listitem>
-  <listitem>
-    <para>
-      with <code>ostringstream</code> you don't have to take care of
-      terminating the string or freeing its memory
-    </para>
-  </listitem>
-  <listitem>
-    <para>
-      <code>istringstream</code> can be re-filled (clear();
-      str(input);)
-    </para>
-  </listitem>
-</itemizedlist>
-
-<para>
-  You can then use output-stringstreams like this:
-</para>
-
-<programlisting>
-#ifdef HAVE_SSTREAM
-# include &lt;sstream&gt;
-#else
-# include &lt;strstream&gt;
-#endif
-
-#ifdef HAVE_SSTREAM
-  std::ostringstream oss;
-#else
-  std::ostrstream oss;
-#endif
-
-oss &lt;&lt; "Name=" &lt;&lt; m_name &lt;&lt; ", number=" &lt;&lt; m_number &lt;&lt; std::endl;
-...
-#ifndef HAVE_SSTREAM
-  oss &lt;&lt; std::ends; // terminate the char*-string
-#endif
-
-// str() returns char* for ostrstream and a string for ostringstream
-// this also causes ostrstream to think that the buffer's memory
-// is yours
-m_label.set_text(oss.str());
-#ifndef HAVE_SSTREAM
-  // let the ostrstream take care of freeing the memory
-  oss.freeze(false);
-#endif
-</programlisting>
-
-<para>
-      Input-stringstreams can be used similarly:
-</para>
-
-<programlisting>
-std::string input;
-...
-#ifdef HAVE_SSTREAM
-std::istringstream iss(input);
-#else
-std::istrstream iss(input.c_str());
-#endif
-
-int i;
-iss &gt;&gt; i;
-</programlisting>
-
-<para> One (the only?) restriction is that an istrstream cannot be re-filled:
-</para>
-
-<programlisting>
-std::istringstream iss(numerator);
-iss &gt;&gt; m_num;
-// this is not possible with istrstream
-iss.clear();
-iss.str(denominator);
-iss &gt;&gt; m_den;
-</programlisting>
-
-<para>
-If you don't care about speed, you can put these conversions in
-      a template-function:
-</para>
-<programlisting>
-template &lt;class X&gt;
-void fromString(const string&amp; input, X&amp; any)
-{
-#ifdef HAVE_SSTREAM
-std::istringstream iss(input);
-#else
-std::istrstream iss(input.c_str());
-#endif
-X temp;
-iss &gt;&gt; temp;
-if (iss.fail())
-throw runtime_error(..)
-any = temp;
-}
-</programlisting>
-
-<para>
-  Another example of using stringstreams is in <link linkend="strings.string.shrink">this howto</link>.
-</para>
-
-<para> There is additional information in the libstdc++-v2 info files, in
-particular <quote>info iostream</quote>.
-</para>
-</section>
-
-<section xml:id="backwards.second.wchar"><info><title>Little or no wide character support</title></info>
-
-  <para>
-    Classes <classname>wstring</classname> and
-    <classname>char_traits&lt;wchar_t&gt;</classname> are
-    not supported.
-  </para>
-</section>
-
-<section xml:id="backwards.second.iostream_templates"><info><title>No templatized iostreams</title></info>
-
-  <para>
-    Classes <classname>wfilebuf</classname> and
-    <classname>wstringstream</classname> are not supported.
-  </para>
-</section>
-
-<section xml:id="backwards.second.thread_safety"><info><title>Thread safety issues</title></info>
-
-
-  <para>
-    Earlier GCC releases had a somewhat different approach to
-    threading configuration and proper compilation.  Before GCC 3.0,
-    configuration of the threading model was dictated by compiler
-    command-line options and macros (both of which were somewhat
-    thread-implementation and port-specific).  There were no
-    guarantees related to being able to link code compiled with one
-    set of options and macro setting with another set.
-  </para>
-
-  <para>
-    For GCC 3.0, configuration of the threading model used with
-    libraries and user-code is performed when GCC is configured and
-    built using the --enable-threads and --disable-threads options.
-    The ABI is stable for symbol name-mangling and limited functional
-    compatibility exists between code compiled under different
-    threading models.
-  </para>
-
-   <para>
-     The libstdc++ library has been designed so that it can be used in
-     multithreaded applications (with libstdc++-v2 this was only true
-     of the STL parts.)  The first problem is finding a
-     <emphasis>fast</emphasis> method of implementation portable to
-     all platforms.  Due to historical reasons, some of the library is
-     written against per-CPU-architecture spinlocks and other parts
-     against the gthr.h abstraction layer which is provided by gcc.  A
-     minor problem that pops up every so often is different
-     interpretations of what "thread-safe" means for a
-     library (not a general program).  We currently use the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/thread_safety.html">same
-     definition that SGI</link> uses for their STL subset.  However,
-     the exception for read-only containers only applies to the STL
-     components. This definition is widely-used and something similar
-     will be used in the next version of the C++ standard library.
-   </para>
-
-   <para>
-     Here is a small link farm to threads (no pun) in the mail
-     archives that discuss the threading problem.  Each link is to the
-     first relevant message in the thread; from there you can use
-     "Thread Next" to move down the thread.  This farm is in
-     latest-to-oldest order.
-   </para>
-
-      <itemizedlist>
-	<listitem>
-	  <para>
-	    Our threading expert Loren gives a breakdown of <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the
-	    six situations involving threads</link> for the 3.0
-	    release series.
-	  </para>
-      </listitem>
-	<listitem>
-	  <para>
-	    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html">
-	This message</link> inspired a recent updating of issues with
-	threading and the SGI STL library.  It also contains some
-	example POSIX-multithreaded STL code.
-	  </para>
-	</listitem>
-      </itemizedlist>
-
-   <para>
-     (A large selection of links to older messages has been removed;
-     many of the messages from 1999 were lost in a disk crash, and the
-     few people with access to the backup tapes have been too swamped
-     with work to restore them.  Many of the points have been
-     superseded anyhow.)
-   </para>
-</section>
-
 </section>
 
 <section xml:id="backwards.third"><info><title>Third</title></info>
@@ -588,7 +70,7 @@ libstdc++-v3.
 </para>
 
       <para>The subset commonly known as the Standard Template Library
-	 (clauses 23 through 25, mostly) is adapted from the final release
+	 (clauses 23 through 25 in C++98, mostly) is adapted from the final release
 	 of the SGI STL (version 3.3), with extensive changes.
       </para>
 
@@ -1223,40 +705,4 @@ AC_DEFUN([AC_HEADER_UNORDERED_SET], [
 
 </section>
 
-<bibliography xml:id="backwards.biblio"><info><title>Bibliography</title></info>
-
-
-  <biblioentry>
-      <title>
-	<link xmlns:xlink="http://www.w3.org/1999/xlink"
-	      xlink:href="http://www.kegel.com/gcc/gcc4.html">
-      Migrating to GCC 4.1
-	</link>
-      </title>
-
-    <author><personname><firstname>Dan</firstname><surname>Kegel</surname></personname></author>
-  </biblioentry>
-
-  <biblioentry>
-      <title>
-	<link xmlns:xlink="http://www.w3.org/1999/xlink"
-	      xlink:href="https://lists.debian.org/debian-gcc/2006/03/msg00405.html">
-      Building the Whole Debian Archive with GCC 4.1: A Summary
-	</link>
-      </title>
-    <author><personname><firstname>Martin</firstname><surname>Michlmayr</surname></personname></author>
-  </biblioentry>
-
-  <biblioentry>
-      <title>
-	<link xmlns:xlink="http://www.w3.org/1999/xlink"
-	      xlink:href="http://annwm.lbl.gov/~leggett/Atlas/gcc-3.2.html">
-      Migration guide for GCC-3.2
-	</link>
-      </title>
-
-  </biblioentry>
-
-</bibliography>
-
 </section>

Re: libstdc++-v3/doc/xml/manual/backwards_compatibility.xml

[Jonathan Wakely]

On 13/04/21 16:37 +0100, Jonathan Wakely wrote:
>On 13/04/21 16:19 +0100, Jonathan Wakely via Libstdc++ wrote:
>>Sorry for the slow reply ...
>>
>>On Mon, 1 Feb 2021 at 22:59, Gerald Pfeifer wrote:
>>>
>>>I noticed this section on "Backwards Compatibility" in the libstdc++
>>>docs that talks about
>>>
>>> - glibc 2.0.x
>>> - GCC 3.2 (August 2002)
>>> - GCC 4.1 (February 2006)
>>>
>>>and links to "Migrating to GCC 4.1" and "Migration guide for GCC-3.2"
>>>documents.
>>>
>>>Does this still make sense (and serve real users or developers) or
>>>should this be trimmed quite a bit?
>>
>>Yeah, that (and a lot more) should be trimmed from the libstdc++
>>manual. It's just time consuming to do it.
>
>It turned out to be pretty easy in this case, as the ancient text was
>so obviously useless now that it can just be ripped out.
>
>The remaining parts of the page should probably be evaluated too, but
>at least the truly prehistoric stuff is gone with this patch.
>
>Pushed to trunk.

Oops, I meant to change gcc@ to gcc-patches@ before sending, sorry for
the noise on the main list.


>commit 989e512f719a44fafca0030d7b8a1f5bf5f1baf7
>Author: Jonathan Wakely <jwakely@redhat.com>
>Date:   Tue Apr 13 16:30:16 2021
>
>    libstdc++: Remove outdated docs on libg++ and libstdc++-v2
>    
>    The libstdc++-v3 manual doesn't need to document how to use its
>    predecessors.
>    
>    libstdc++-v3/ChangeLog:
>    
>            * doc/xml/manual/backwards_compatibility.xml: Remove porting
>            notes for libg++ and libstdc++-v2, and bibliography.
>            * doc/html/*: Regenerated.
>
>diff --git a/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml b/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml
>index cce553380e1..6a4a5ccedfb 100644
>--- a/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml
>+++ b/libstdc++-v3/doc/xml/manual/backwards_compatibility.xml
>@@ -22,7 +22,7 @@ dinosaur.
> 
> <para>Some background: libg++ was designed and created when there was no
> ISO standard to provide guidance.  Classes like linked lists are now
>-provided for by <classname>list&lt;T&gt;</classname> and do not need to be
>+provided for by <classname>std::list&lt;T&gt;</classname> and do not need to be
> created by <function>genclass</function>.  (For that matter, templates exist
> now and are well-supported, whereas genclass (mostly) predates them.)
> </para>
>@@ -34,41 +34,13 @@ Committee couldn't include everything, and so a lot of those
> <quote>obvious</quote> classes didn't get included.
> </para>
> 
>-<para>Known Issues include many of the limitations of its immediate ancestor.</para>
>-
>-<para>Portability notes and known implementation limitations are as follows.</para>
>-
>-<section xml:id="backwards.first.ios_base"><info><title>No <code>ios_base</code></title></info>
>-
>-
>-<para> At least some older implementations don't have <code>std::ios_base</code>, so you should use <code>std::ios::badbit</code>, <code>std::ios::failbit</code> and <code>std::ios::eofbit</code> and <code>std::ios::goodbit</code>.
>+<para>That project is no longer maintained or supported, and the sources
>+archived. For the desperate, the
>+<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://ftp.gnu.org/old-gnu/libg++/">ftp.gnu.org</link>
>+server still has the libg++ source.
> </para>
> </section>
> 
>-<section xml:id="backwards.first.cout_cin"><info><title>No <code>cout</code> in <filename class="headerfile">&lt;ostream.h&gt;</filename>, no <code>cin</code> in <filename class="headerfile">&lt;istream.h&gt;</filename></title></info>
>-
>-
>-<para>
>-	In earlier versions of the standard,
>-	<filename class="headerfile">&lt;fstream.h&gt;</filename>,
>-	<filename class="headerfile">&lt;ostream.h&gt;</filename>
>-	and <filename class="headerfile">&lt;istream.h&gt;</filename>
>-	used to define
>-	<code>cout</code>, <code>cin</code> and so on. ISO C++ specifies that one needs to include
>-	<filename class="headerfile">&lt;iostream&gt;</filename>
>-	explicitly to get the required definitions.
>- </para>
>-<para> Some include adjustment may be required.</para>
>-
>-<para>This project is no longer maintained or supported, and the sources
>-archived. For the desperate,
>-the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/extensions.html">GCC extensions
>-page</link> describes where to find the last libg++ source. The code is
>-considered replaced and rewritten.
>-</para>
>-</section>
>-</section>
>-
> <section xml:id="backwards.second"><info><title>Second</title></info>
> 
> 
>@@ -80,504 +52,14 @@ considered replaced and rewritten.
> </para>
> 
> <para>
>-  The STL portions of this library are based on SGI/HP STL release 3.11.
>+  The STL portions of that library are based on SGI/HP STL release 3.11.
> </para>
> 
> <para>
>-  This project is no longer maintained or supported, and the sources
>-  archived.  The code is considered replaced and rewritten.
>+  That project is no longer maintained or supported, and the sources
>+  archived.  The code was replaced and rewritten for libstdc++-v3.
> </para>
> 
>-<para>
>-  Portability notes and known implementation limitations are as follows.
>-</para>
>-
>-<section xml:id="backwards.second.std"><info><title>Namespace <code>std::</code> not supported</title></info>
>-
>-
>-  <para>
>-    Some care is required to support C++ compiler and or library
>-    implementation that do not have the standard library in
>-    <code>namespace std</code>.
>-  </para>
>-
>-  <para>
>-    The following sections list some possible solutions to support compilers
>-    that cannot ignore <code>std::</code>-qualified names.
>-  </para>
>-
>-  <para>
>-    First, see if the compiler has a flag for this. Namespace
>-    back-portability-issues are generally not a problem for g++
>-    compilers that do not have libstdc++ in <code>std::</code>, as the
>-    compilers use <option>-fno-honor-std</option> (ignore
>-    <code>std::</code>, <code>:: = std::</code>) by default. That is,
>-    the responsibility for enabling or disabling <code>std::</code> is
>-    on the user; the maintainer does not have to care about it. This
>-    probably applies to some other compilers as well.
>-  </para>
>-
>-  <para>
>-    Second, experiment with a variety of pre-processor tricks.
>-  </para>
>-
>-  <para>
>-    By defining <code>std</code> as a macro, fully-qualified namespace
>-    calls become global. Volia.
>-  </para>
>-
>-<programlisting>
>-#ifdef WICKEDLY_OLD_COMPILER
>-# define std
>-#endif
>-</programlisting>
>-
>-  <para>
>-    Thanks to Juergen Heinzl who posted this solution on gnu.gcc.help.
>-  </para>
>-
>-  <para>
>-    Another pre-processor based approach is to define a macro
>-    <code>NAMESPACE_STD</code>, which is defined to either
>-    <quote> </quote> or <quote>std</quote> based on a compile-type
>-    test. On GNU systems, this can be done with autotools by means of
>-    an autoconf test (see below) for <code>HAVE_NAMESPACE_STD</code>,
>-    then using that to set a value for the <code>NAMESPACE_STD</code>
>-    macro.  At that point, one is able to use
>-    <code>NAMESPACE_STD::string</code>, which will evaluate to
>-    <code>std::string</code> or <code>::string</code> (i.e., in the
>-    global namespace on systems that do not put <code>string</code> in
>-    <code>std::</code>).
>-  </para>
>-
>-<programlisting>
>-dnl @synopsis AC_CXX_NAMESPACE_STD
>-dnl
>-dnl If the compiler supports namespace std, define
>-dnl HAVE_NAMESPACE_STD.
>-dnl
>-dnl @category Cxx
>-dnl @author Todd Veldhuizen
>-dnl @author Luc Maisonobe &lt;luc@spaceroots.org&gt;
>-dnl @version 2004-02-04
>-dnl @license AllPermissive
>-AC_DEFUN([AC_CXX_NAMESPACE_STD], [
>-  AC_CACHE_CHECK(if g++ supports namespace std,
>-  ac_cv_cxx_have_std_namespace,
>-  [AC_LANG_SAVE
>-  AC_LANG_CPLUSPLUS
>-  AC_TRY_COMPILE([#include &lt;iostream&gt;
>-		  std::istream&amp; is = std::cin;],,
>-  ac_cv_cxx_have_std_namespace=yes, ac_cv_cxx_have_std_namespace=no)
>-  AC_LANG_RESTORE
>-  ])
>-  if test "$ac_cv_cxx_have_std_namespace" = yes; then
>-    AC_DEFINE(HAVE_NAMESPACE_STD,,[Define if g++ supports namespace std. ])
>-  fi
>-])
>-</programlisting>
>-</section>
>-
>-<section xml:id="backwards.second.iterators"><info><title>Illegal iterator usage</title></info>
>-
>-<para>
>-  The following illustrate implementation-allowed illegal iterator
>-  use, and then correct use.
>-</para>
>-
>-<itemizedlist>
>-  <listitem>
>-    <para>
>-      you cannot do <code>ostream::operator&lt;&lt;(iterator)</code>
>-      to print the address of the iterator =&gt; use
>-      <code>operator&lt;&lt; &amp;*iterator</code> instead
>-    </para>
>-  </listitem>
>-  <listitem>
>-    <para>
>-      you cannot clear an iterator's reference (<code>iterator =
>-      0</code>) =&gt; use <code>iterator = iterator_type();</code>
>-    </para>
>-  </listitem>
>-  <listitem>
>-    <para>
>-      <code>if (iterator)</code> won't work any more =&gt; use
>-      <code>if (iterator != iterator_type())</code>
>-    </para>
>-  </listitem>
>-</itemizedlist>
>-</section>
>-
>-<section xml:id="backwards.second.isspace"><info><title><code>isspace</code> from <filename class="headerfile">&lt;cctype&gt;</filename> is a macro
>-  </title></info>
>-
>-
>-  <para>
>-    Glibc 2.0.x and 2.1.x define <filename class="headerfile">&lt;ctype.h&gt;</filename> functionality as macros
>-    (isspace, isalpha etc.).
>-  </para>
>-
>-  <para>
>-    This implementations of libstdc++, however, keep these functions
>-    as macros, and so it is not back-portable to use fully qualified
>-    names. For example:
>-  </para>
>-
>-<programlisting>
>-#include &lt;cctype&gt;
>-int main() { std::isspace('X'); }
>-</programlisting>
>-
>-<para>
>-  Results in something like this:
>-</para>
>-
>-<programlisting>
>-std:: (__ctype_b[(int) ( ( 'X' ) )] &amp; (unsigned short int) _ISspace ) ;
>-</programlisting>
>-
>-<para>
>-  A solution is to modify a header-file so that the compiler tells
>-  <filename class="headerfile">&lt;ctype.h&gt;</filename> to define functions
>-  instead of macros:
>-</para>
>-
>-<programlisting>
>-// This keeps isalnum, et al from being propagated as macros.
>-#if __linux__
>-# define __NO_CTYPE 1
>-#endif
>-</programlisting>
>-
>-<para>
>-  Then, include <filename class="headerfile">&lt;ctype.h&gt;</filename>
>-</para>
>-
>-<para>
>-  Another problem arises if you put a <code>using namespace
>-  std;</code> declaration at the top, and include
>-  <filename class="headerfile">&lt;ctype.h&gt;</filename>. This will
>-  result in ambiguities between the definitions in the global namespace
>-  (<filename class="headerfile">&lt;ctype.h&gt;</filename>) and the
>-  definitions in namespace <code>std::</code>
>-  (<code>&lt;cctype&gt;</code>).
>-</para>
>-</section>
>-
>-<section xml:id="backwards.second.at"><info><title>No <code>vector::at</code>, <code>deque::at</code>, <code>string::at</code></title></info>
>-
>-
>-<para>
>-  One solution is to add an autoconf-test for this:
>-</para>
>-
>-<programlisting>
>-AC_MSG_CHECKING(for container::at)
>-AC_TRY_COMPILE(
>-[
>-#include &lt;vector&gt;
>-#include &lt;deque&gt;
>-#include &lt;string&gt;
>-
>-using namespace std;
>-],
>-[
>-deque&lt;int&gt; test_deque(3);
>-test_deque.at(2);
>-vector&lt;int&gt; test_vector(2);
>-test_vector.at(1);
>-string test_string(<quote>test_string</quote>);
>-test_string.at(3);
>-],
>-[AC_MSG_RESULT(yes)
>-AC_DEFINE(HAVE_CONTAINER_AT)],
>-[AC_MSG_RESULT(no)])
>-</programlisting>
>-
>-<para>
>-  If you are using other (non-GNU) compilers it might be a good idea
>-  to check for <code>string::at</code> separately.
>-</para>
>-
>-</section>
>-
>-<section xml:id="backwards.second.eof"><info><title>No <code>std::char_traits&lt;char&gt;::eof</code></title></info>
>-
>-
>-<para>
>-  Use some kind of autoconf test, plus this:
>-</para>
>-
>-<programlisting>
>-#ifdef HAVE_CHAR_TRAITS
>-#define CPP_EOF std::char_traits&lt;char&gt;::eof()
>-#else
>-#define CPP_EOF EOF
>-#endif
>-</programlisting>
>-
>-</section>
>-
>-<section xml:id="backwards.second.stringclear"><info><title>No <code>string::clear</code></title></info>
>-
>-
>-<para>
>-  There are two functions for deleting the contents of a string:
>-  <code>clear</code> and <code>erase</code> (the latter returns the
>-  string).
>-</para>
>-
>-<programlisting>
>-void
>-clear() { _M_mutate(0, this-&gt;size(), 0); }
>-</programlisting>
>-
>-<programlisting>
>-basic_string&amp;
>-erase(size_type __pos = 0, size_type __n = npos)
>-{
>-  return this-&gt;replace(_M_check(__pos), _M_fold(__pos, __n),
>-			  _M_data(), _M_data());
>-}
>-</programlisting>
>-
>-<para>
>-  Unfortunately, <code>clear</code> is not implemented in this
>-  version, so you should use <code>erase</code> (which is probably
>-  faster than <code>operator=(charT*)</code>).
>-</para>
>-</section>
>-
>-<section xml:id="backwards.second.ostreamform_istreamscan"><info><title>
>-  Removal of <code>ostream::form</code> and <code>istream::scan</code>
>-  extensions
>-</title></info>
>-
>-
>-<para>
>-  These are no longer supported. Please use stringstreams instead.
>-</para>
>-</section>
>-
>-<section xml:id="backwards.second.stringstreams"><info><title>No <code>basic_stringbuf</code>, <code>basic_stringstream</code></title></info>
>-
>-
>-<para>
>-  Although the ISO standard <code>i/ostringstream</code>-classes are
>-  provided, (<filename class="headerfile">&lt;sstream&gt;</filename>), for
>-  compatibility with older implementations the pre-ISO
>-  <code>i/ostrstream</code> (<filename class="headerfile">&lt;strstream&gt;</filename>) interface is also provided,
>-  with these caveats:
>-</para>
>-
>-<itemizedlist>
>-  <listitem>
>-    <para>
>-      <code>strstream</code> is considered to be deprecated
>-    </para>
>-  </listitem>
>-  <listitem>
>-    <para>
>-      <code>strstream</code> is limited to <code>char</code>
>-    </para>
>-  </listitem>
>-  <listitem>
>-    <para>
>-      with <code>ostringstream</code> you don't have to take care of
>-      terminating the string or freeing its memory
>-    </para>
>-  </listitem>
>-  <listitem>
>-    <para>
>-      <code>istringstream</code> can be re-filled (clear();
>-      str(input);)
>-    </para>
>-  </listitem>
>-</itemizedlist>
>-
>-<para>
>-  You can then use output-stringstreams like this:
>-</para>
>-
>-<programlisting>
>-#ifdef HAVE_SSTREAM
>-# include &lt;sstream&gt;
>-#else
>-# include &lt;strstream&gt;
>-#endif
>-
>-#ifdef HAVE_SSTREAM
>-  std::ostringstream oss;
>-#else
>-  std::ostrstream oss;
>-#endif
>-
>-oss &lt;&lt; "Name=" &lt;&lt; m_name &lt;&lt; ", number=" &lt;&lt; m_number &lt;&lt; std::endl;
>-...
>-#ifndef HAVE_SSTREAM
>-  oss &lt;&lt; std::ends; // terminate the char*-string
>-#endif
>-
>-// str() returns char* for ostrstream and a string for ostringstream
>-// this also causes ostrstream to think that the buffer's memory
>-// is yours
>-m_label.set_text(oss.str());
>-#ifndef HAVE_SSTREAM
>-  // let the ostrstream take care of freeing the memory
>-  oss.freeze(false);
>-#endif
>-</programlisting>
>-
>-<para>
>-      Input-stringstreams can be used similarly:
>-</para>
>-
>-<programlisting>
>-std::string input;
>-...
>-#ifdef HAVE_SSTREAM
>-std::istringstream iss(input);
>-#else
>-std::istrstream iss(input.c_str());
>-#endif
>-
>-int i;
>-iss &gt;&gt; i;
>-</programlisting>
>-
>-<para> One (the only?) restriction is that an istrstream cannot be re-filled:
>-</para>
>-
>-<programlisting>
>-std::istringstream iss(numerator);
>-iss &gt;&gt; m_num;
>-// this is not possible with istrstream
>-iss.clear();
>-iss.str(denominator);
>-iss &gt;&gt; m_den;
>-</programlisting>
>-
>-<para>
>-If you don't care about speed, you can put these conversions in
>-      a template-function:
>-</para>
>-<programlisting>
>-template &lt;class X&gt;
>-void fromString(const string&amp; input, X&amp; any)
>-{
>-#ifdef HAVE_SSTREAM
>-std::istringstream iss(input);
>-#else
>-std::istrstream iss(input.c_str());
>-#endif
>-X temp;
>-iss &gt;&gt; temp;
>-if (iss.fail())
>-throw runtime_error(..)
>-any = temp;
>-}
>-</programlisting>
>-
>-<para>
>-  Another example of using stringstreams is in <link linkend="strings.string.shrink">this howto</link>.
>-</para>
>-
>-<para> There is additional information in the libstdc++-v2 info files, in
>-particular <quote>info iostream</quote>.
>-</para>
>-</section>
>-
>-<section xml:id="backwards.second.wchar"><info><title>Little or no wide character support</title></info>
>-
>-  <para>
>-    Classes <classname>wstring</classname> and
>-    <classname>char_traits&lt;wchar_t&gt;</classname> are
>-    not supported.
>-  </para>
>-</section>
>-
>-<section xml:id="backwards.second.iostream_templates"><info><title>No templatized iostreams</title></info>
>-
>-  <para>
>-    Classes <classname>wfilebuf</classname> and
>-    <classname>wstringstream</classname> are not supported.
>-  </para>
>-</section>
>-
>-<section xml:id="backwards.second.thread_safety"><info><title>Thread safety issues</title></info>
>-
>-
>-  <para>
>-    Earlier GCC releases had a somewhat different approach to
>-    threading configuration and proper compilation.  Before GCC 3.0,
>-    configuration of the threading model was dictated by compiler
>-    command-line options and macros (both of which were somewhat
>-    thread-implementation and port-specific).  There were no
>-    guarantees related to being able to link code compiled with one
>-    set of options and macro setting with another set.
>-  </para>
>-
>-  <para>
>-    For GCC 3.0, configuration of the threading model used with
>-    libraries and user-code is performed when GCC is configured and
>-    built using the --enable-threads and --disable-threads options.
>-    The ABI is stable for symbol name-mangling and limited functional
>-    compatibility exists between code compiled under different
>-    threading models.
>-  </para>
>-
>-   <para>
>-     The libstdc++ library has been designed so that it can be used in
>-     multithreaded applications (with libstdc++-v2 this was only true
>-     of the STL parts.)  The first problem is finding a
>-     <emphasis>fast</emphasis> method of implementation portable to
>-     all platforms.  Due to historical reasons, some of the library is
>-     written against per-CPU-architecture spinlocks and other parts
>-     against the gthr.h abstraction layer which is provided by gcc.  A
>-     minor problem that pops up every so often is different
>-     interpretations of what "thread-safe" means for a
>-     library (not a general program).  We currently use the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/thread_safety.html">same
>-     definition that SGI</link> uses for their STL subset.  However,
>-     the exception for read-only containers only applies to the STL
>-     components. This definition is widely-used and something similar
>-     will be used in the next version of the C++ standard library.
>-   </para>
>-
>-   <para>
>-     Here is a small link farm to threads (no pun) in the mail
>-     archives that discuss the threading problem.  Each link is to the
>-     first relevant message in the thread; from there you can use
>-     "Thread Next" to move down the thread.  This farm is in
>-     latest-to-oldest order.
>-   </para>
>-
>-      <itemizedlist>
>-	<listitem>
>-	  <para>
>-	    Our threading expert Loren gives a breakdown of <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the
>-	    six situations involving threads</link> for the 3.0
>-	    release series.
>-	  </para>
>-      </listitem>
>-	<listitem>
>-	  <para>
>-	    <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html">
>-	This message</link> inspired a recent updating of issues with
>-	threading and the SGI STL library.  It also contains some
>-	example POSIX-multithreaded STL code.
>-	  </para>
>-	</listitem>
>-      </itemizedlist>
>-
>-   <para>
>-     (A large selection of links to older messages has been removed;
>-     many of the messages from 1999 were lost in a disk crash, and the
>-     few people with access to the backup tapes have been too swamped
>-     with work to restore them.  Many of the points have been
>-     superseded anyhow.)
>-   </para>
>-</section>
>-
> </section>
> 
> <section xml:id="backwards.third"><info><title>Third</title></info>
>@@ -588,7 +70,7 @@ libstdc++-v3.
> </para>
> 
>       <para>The subset commonly known as the Standard Template Library
>-	 (clauses 23 through 25, mostly) is adapted from the final release
>+	 (clauses 23 through 25 in C++98, mostly) is adapted from the final release
> 	 of the SGI STL (version 3.3), with extensive changes.
>       </para>
> 
>@@ -1223,40 +705,4 @@ AC_DEFUN([AC_HEADER_UNORDERED_SET], [
> 
> </section>
> 
>-<bibliography xml:id="backwards.biblio"><info><title>Bibliography</title></info>
>-
>-
>-  <biblioentry>
>-      <title>
>-	<link xmlns:xlink="http://www.w3.org/1999/xlink"
>-	      xlink:href="http://www.kegel.com/gcc/gcc4.html">
>-      Migrating to GCC 4.1
>-	</link>
>-      </title>
>-
>-    <author><personname><firstname>Dan</firstname><surname>Kegel</surname></personname></author>
>-  </biblioentry>
>-
>-  <biblioentry>
>-      <title>
>-	<link xmlns:xlink="http://www.w3.org/1999/xlink"
>-	      xlink:href="https://lists.debian.org/debian-gcc/2006/03/msg00405.html">
>-      Building the Whole Debian Archive with GCC 4.1: A Summary
>-	</link>
>-      </title>
>-    <author><personname><firstname>Martin</firstname><surname>Michlmayr</surname></personname></author>
>-  </biblioentry>
>-
>-  <biblioentry>
>-      <title>
>-	<link xmlns:xlink="http://www.w3.org/1999/xlink"
>-	      xlink:href="http://annwm.lbl.gov/~leggett/Atlas/gcc-3.2.html">
>-      Migration guide for GCC-3.2
>-	</link>
>-      </title>
>-
>-  </biblioentry>
>-
>-</bibliography>
>-
> </section>