[libstdc++] Minor doc tweaks

[Phil Edwards <pedwards at disaster dot jaj dot com>]

It doesn't look like the threading-related messages from 1999 will be
recovered anytime soon, so no sense keeping the misleading links.  I moved
the <pre> blocks from Loren's recent FAQ entries inside the <p> blocks
to make browsers slightly happier, and re-line-wrapped in the process;
no changes in /content/ there.  The links to other chapters at the bottom
got some titles added to their numbers.


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.


Index: docs/html/17_intro/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/howto.html,v
retrieving revision 1.14
diff -u -3 -p -r1.14 howto.html
--- howto.html	2001/10/11 18:41:42	1.14
+++ howto.html	2001/10/17 18:12:12
@@ -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>
+        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>
-      <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.
-      </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.
Index: docs/html/faq/index.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/faq/index.html,v
retrieving revision 1.22
diff -u -3 -p -r1.22 index.html
--- index.html	2001/10/13 00:06:21	1.22
+++ index.html	2001/10/17 18:12:12
@@ -687,49 +687,46 @@ http://clisp.cons.org/~haible/gccinclude
 <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.
+     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>,
-         <a href="../23_containers/howto.html#3">23</a> and
-	 <a href="../27_io/howto.html#9">27</a> for more information.
+      <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>