howto.html: Remove 1999 links (and explain why).

2001-10-17  Phil Edwards  <pme@gcc.gnu.org>

	* docs/html/17_intro/howto.html:  Remove 1999 links (and explain
	why).  Add link to recent message.
	* docs/html/faq/index.html (5.6):  Reformat text only; fixup <pre>
	markup.
	* docs/html/faq/index.txt:  Regenerate.

From-SVN: r46321

4 files changed, 97 insertions, 86 deletions

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index 808d1f0..32f6c21 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,3 +1,11 @@
+2001-10-17  Phil Edwards  <pme@gcc.gnu.org>
+
+	* docs/html/17_intro/howto.html:  Remove 1999 links (and explain
+	why).  Add link to recent message.
+	* docs/html/faq/index.html (5.6):  Reformat text only; fixup <pre>
+	markup.
+	* docs/html/faq/index.txt:  Regenerate.
+
 2001-10-12  Loren J. Rittle  <ljrittle@acm.org>
 
 	* docs/html/faq/index.html (Is libstdc++-v3 thread-safe?): Update
diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html
index d7ca3f3..69d9886 100644
--- a/libstdc++-v3/docs/html/17_intro/howto.html
+++ b/libstdc++-v3/docs/html/17_intro/howto.html
@@ -67,7 +67,8 @@
       means for a library (not a general program).  We currently use the
       <a href="http://www.sgi.com/tech/stl/thread_safety.html">same
       definition that SGI</a> uses for their STL subset.
-      <em>Please see the many cautions given in HOWTOs on containers.</em>
+      <em>Please see the many cautions given in
+      <a href="../23_containers/howto.html">HOWTOs on containers</a>.</em>
    </p>
    <p>Here is another attempt at explaining the dangers of using the
       STL with threading support without understanding some important
@@ -109,46 +110,21 @@
       &quot;Thread Next&quot; to move down the thread.  This farm is in
       latest-to-oldest order.
       <ul>
+        <li>Our threading expert Loren gives a breakdown of
+        <a href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the
+        six situations involving threads</a> for the 3.0 release series.
         <li><a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html">
-        inspired this most recent updating of issues with threading
+        This message</a> inspired a recent updating of issues with threading
         and the SGI STL library.  It also contains some example
-        POSIX-multithreaded STL code.</a>
-        <li> <a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00136.html">
-        an early analysis of why __USE_MALLOC should be disabled for
-        the 3.0 release of libstdc++.</a>
-      </ul>
-      <br>
-      Here are discussions that took place before the current snapshot;
-      they are still relevant and instructive.  (Some of them may not work;
-      as the drive containing some of the 1999 archives crashed, and nobody
-      has had time to recover the backups.)
-      <br>
-      <ul>
-        <li>One way of preventing memory leaks by the old default memory
-            allocator in multithreaded code is
-            <a href="http://gcc.gnu.org/ml/gcc/1999-11n/msg00431.html">discussed here</a>.
-        <li><a href="http://gcc.gnu.org/ml/libstdc++/1999-q3/msg00167.html">This thread
-            concerns strings</a>.
-        <li><a href="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00339.html">So does this
-            one</a>.  This initial message also refers to another
-            thread in the GCC mailing list...
-        <li><a href="http://gcc.gnu.org/ml/gcc/1999-06n/msg00680.html">which is here</a>,
-            and goes on for some time.  Ironically, the initial message
-            in this thread also mentions another threading thread...
-        <li><a href="http://gcc.gnu.org/ml/gcc-bugs/1999-04n/msg00777.html">beginning here</a>,
-            and talking about pthreads.  (Note that a much more recent
-            message from the first thread in this list notes that
-            <a href="http://gcc.gnu.org/ml/libstdc++/1999-q3/msg00176.html">pthreads
-            should not be used as a starting point</a> for making
-            libstdc++ threadsafe.)
-        <li><a href="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00168.html">This
-            message</a>,
-            <a href="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00159.html">this one</a>,
-            and <a href="http://gcc.gnu.org/ml/libstdc++/1999-q2/msg00156.html">this one</a>
-            are the tops of related threads (all within the same time
-            period) discussing threading and the IO library.  Much of it
-            is dealing with the C library, but C++ is included as well.
+        POSIX-multithreaded STL code.
+        <li><a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00136.html">
+        Here</a> is an early analysis of why __USE_MALLOC should be disabled
+        for the 3.0 release of libstdc++.</a>
       </ul>
+      (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 superceded anyhow.)
    </p>
    <p>This section will be updated as new and interesting issues come
       to light.
diff --git a/libstdc++-v3/docs/html/faq/index.html b/libstdc++-v3/docs/html/faq/index.html
index e0f31ce..650a5ec 100644
--- a/libstdc++-v3/docs/html/faq/index.html
+++ b/libstdc++-v3/docs/html/faq/index.html
@@ -687,49 +687,46 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
 <hr>
    <h2><a name="5_6">5.6 Is libstdc++-v3 thread-safe?</a></h2>
       <p>When the system's libc is itself thread-safe, a non-generic
-         implementation of atomicity.h exists for the architecture, and
-	 gcc itself reports a thread model other than single; libstdc++-v3
+         implementation of atomicity.h exists for the architecture, and gcc
+         itself reports a thread model other than single; libstdc++-v3
          strives to be thread-safe.  The user-code must guard against
-         concurrent method calls which may access any particular
-         library object's state.  Typically, the application
-         programmer may infer what object locks must be held based on
-         the objects referenced in a method call.  Without getting
-         into great detail, here is an example which requires
-         user-level locks:
-      </p>
+         concurrent method calls which may access any particular library
+         object's state.  Typically, the application programmer may infer
+         what object locks must be held based on the objects referenced in
+         a method call.  Without getting into great detail, here is an
+         example which requires user-level locks:
          <pre>
-       library_class_a shared_object_a;
+     library_class_a shared_object_a;
 
-       thread_main () {
-         library_class_b *object_b = new library_class_b;
-	 shared_object_a.add_b (object_b); // must hold lock for shared_object_a
-	 shared_object_a.mutate (); // must hold lock for shared_object_a
-       }
+     thread_main () {
+       library_class_b *object_b = new library_class_b;
+       shared_object_a.add_b (object_b);   // must hold lock for shared_object_a
+       shared_object_a.mutate ();          // must hold lock for shared_object_a
+     }
 
-       // Multiple copies of thread_main() are started in independent threads.
-         </pre>
-      <p>Under the assumption that object_a and object_b are never
-         exposed to another thread, here is an example that should not
-         require any user-level locks:
+     // Multiple copies of thread_main() are started in independent threads.</pre>
       </p>
+      <p>Under the assumption that object_a and object_b are never exposed to
+         another thread, here is an example that should not require any
+         user-level locks:
          <pre>
-       thread_main () {
-         library_class_a object_a;
-         library_class_b *object_b = new library_class_b;
-	 object_a.add_b (object_b);
-	 object_a.mutate ();
-       }
-         </pre>
-      <p>All library objects are safe to use in a multithreaded
-         program as long as each thread carefully locks out access by
-         any other thread while it uses any object visible to another
-         thread.  This requirement includes both read and write access
-         to objects; do not assume that two threads may read a shared
-         standard container at the same time.
-      </p>
-      <p>See chapters <a href="../17_intro/howto.html#3">17</a>,
-         <a href="../23_containers/howto.html#3">23</a> and
-	 <a href="../27_io/howto.html#9">27</a> for more information.
+     thread_main () {
+       library_class_a object_a;
+       library_class_b *object_b = new library_class_b;
+       object_a.add_b (object_b);
+       object_a.mutate ();
+     } </pre>
+      </p>
+      <p>All library objects are safe to use in a multithreaded program as
+         long as each thread carefully locks out access by any other thread
+         while it uses any object visible to another thread.  This requirement
+         includes both read and write access to objects; do not assume that
+         two threads may read a shared standard container at the same time.
+      </p>
+      <p>See chapters <a href="../17_intro/howto.html#3">17</a> (library
+         introduction), <a href="../23_containers/howto.html#3">23</a>
+         (containers), and <a href="../27_io/howto.html#9">27</a> (I/O) for
+         more information.
       </p>
 
 <hr>
diff --git a/libstdc++-v3/docs/html/faq/index.txt b/libstdc++-v3/docs/html/faq/index.txt
index fcf84c8..44c4748 100644
--- a/libstdc++-v3/docs/html/faq/index.txt
+++ b/libstdc++-v3/docs/html/faq/index.txt
@@ -548,15 +548,45 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
 
 5.6 Is libstdc++-v3 thread-safe?
 
-   Quick  answer:  no,  as  of  3.0,  most of the library is not safe for
-   multithreaded access. The string class is MT-safe.
-
-   This  is  assuming  that  your  idea of "multithreaded" is the same as
-   ours...  The  general  question  of multithreading and libstdc++-v3 is
-   addressed in the chapter-specific advice for [80]Library Introduction.
-   Threadsafe  containers  are covered in more detail in [81]the Received
-   Wisdom  section  on  containers.  Threading  and  I/O are discussed in
-   [82]the I/O chapter.
+   When   the   system's   libc  is  itself  thread-safe,  a  non-generic
+   implementation  of  atomicity.h  exists  for the architecture, and gcc
+   itself  reports a thread model other than single; libstdc++-v3 strives
+   to  be thread-safe. The user-code must guard against concurrent method
+   calls   which  may  access  any  particular  library  object's  state.
+   Typically, the application programmer may infer what object locks must
+   be  held  based  on  the  objects referenced in a method call. Without
+   getting   into  great  detail,  here  is  an  example  which  requires
+   user-level locks:
+     library_class_a shared_object_a;
+
+     thread_main () {
+       library_class_b *object_b = new library_class_b;
+       shared_object_a.add_b (object_b);   // must hold lock for shared_object_
+a
+       shared_object_a.mutate ();          // must hold lock for shared_object_
+a
+     }
+
+     // Multiple copies of thread_main() are started in independent threads.
+
+   Under  the  assumption that object_a and object_b are never exposed to
+   another  thread,  here  is  an  example  that  should  not require any
+   user-level locks:
+     thread_main () {
+       library_class_a object_a;
+       library_class_b *object_b = new library_class_b;
+       object_a.add_b (object_b);
+       object_a.mutate ();
+     }
+
+   All library objects are safe to use in a multithreaded program as long
+   as each thread carefully locks out access by any other thread while it
+   uses  any  object visible to another thread. This requirement includes
+   both  read and write access to objects; do not assume that two threads
+   may read a shared standard container at the same time.
+
+   See  chapters  [80]17 (library introduction), [81]23 (containers), and
+   [82]27 (I/O) for more information.
      _________________________________________________________________
 
 5.7 How do I get a copy of the ISO C++ Standard?
@@ -660,8 +690,8 @@ References
   78. http://www.sgi.com/Technology/STL/
   79. ../ext/howto.html
   80. ../17_intro/howto.html#3
-  81. ../23_containers/howto.html
-  82. ../27_io/howto.html
+  81. ../23_containers/howto.html#3
+  82. ../27_io/howto.html#9
   83. http://www.ansi.org/
   84. http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%2D1998
   85. http://www.iso.ch/