style.css: Update.

2002-11-21  Phil Edwards  <pme@gcc.gnu.org>

	* docs/doxygen/style.css:  Update.
	* docs/doxygen/user.cfg.in:  Update.
	* docs/html/documentation.html:  Regenerate.
	* docs/html/17_intro/howto.html:  Tweak I/O sentry entry.
	* docs/html/27_io/howto.html:  New section on headers.
	* docs/html/faq/index.html:  Add i386 threading entry.
	* docs/html/faq/index.txt:  Regenerate.

	* docs/html/ext/lwg-active.html, docs/html/ext/lwg-defects.html:
	Import R23.

From-SVN: r59326

libstdc++-v3/ChangeLog

 2002-11-21  Phil Edwards  <pme@gcc.gnu.org>
 
+	* docs/doxygen/style.css:  Update.
+	* docs/doxygen/user.cfg.in:  Update.
+	* docs/html/documentation.html:  Regenerate.
+	* docs/html/17_intro/howto.html:  Tweak I/O sentry entry.
+	* docs/html/27_io/howto.html:  New section on headers.
+	* docs/html/faq/index.html:  Add i386 threading entry.
+	* docs/html/faq/index.txt:  Regenerate.
+
+	* docs/html/ext/lwg-active.html, docs/html/ext/lwg-defects.html:
+	Import R23.
+
+2002-11-21  Phil Edwards  <pme@gcc.gnu.org>
+
 	* docs/doxygen/TODO:  Note change in clause 27 docs.
 	* include/bits/basic_ios.h, include/bits/fpos.h,
 	include/bits/ios_base.h, include/bits/stl_deque.h,

libstdc++-v3/docs/doxygen/style.css

 H1 { text-align: center; }
+CAPTION { font-weight: bold }
 A.qindex {}
 A.qindexRef {}
 A.el { text-decoration: none; font-weight: bold }
@@ -10,15 +11,39 @@ DL.el { margin-left: -1cm }
 DIV.fragment { width: 100%; border: none; background-color: #eeeeee }
 DIV.ah { background-color: black; font-weight: bold; color: #ffffff; margin-bottom: 3px; margin-top: 3px }
 TD.md { background-color: #f2f2ff; font-weight: bold; }
-TD.mdname1 { background-color: #f2f2ff; font-weight: bold; font-style: italic; }
-TD.mdname { background-color: #f2f2ff; font-weight: bold; font-style: italic; width: 600px; }
+TD.mdname1 { background-color: #f2f2ff; font-weight: bold; color: #602020; }
+TD.mdname { background-color: #f2f2ff; font-weight: bold; color: #602020; width: 600px; }
 DIV.groupHeader { margin-left: 16px; margin-top: 12px; margin-bottom: 6px; font-weight: bold }
 DIV.groupText { margin-left: 16px; font-style: italic; font-size: smaller }
-FONT.keyword       { color: #008000 }
-FONT.keywordtype   { color: #604020 }
-FONT.keywordflow   { color: #e08000 }
-FONT.comment       { color: #800000 }
-FONT.preprocessor  { color: #806020 }
-FONT.stringliteral { color: #002080 }
-FONT.charliteral   { color: #008080 }
-.smallertext { font-size: smaller }
+BODY { background: white }
+TD.indexkey { 
+   background-color: #eeeeff; 
+   font-weight: bold; 
+   padding-right  : 10px; 
+   padding-top    : 2px; 
+   padding-left   : 10px; 
+   padding-bottom : 2px; 
+   margin-left    : 0px; 
+   margin-right   : 0px; 
+   margin-top     : 2px; 
+   margin-bottom  : 2px  
+}
+TD.indexvalue { 
+   background-color: #eeeeff; 
+   font-style: italic; 
+   padding-right  : 10px; 
+   padding-top    : 2px; 
+   padding-left   : 10px; 
+   padding-bottom : 2px; 
+   margin-left    : 0px; 
+   margin-right   : 0px; 
+   margin-top     : 2px; 
+   margin-bottom  : 2px  
+}
+span.keyword       { color: #008000 }
+span.keywordtype   { color: #604020 }
+span.keywordflow   { color: #e08000 }
+span.comment       { color: #800000 }
+span.preprocessor  { color: #806020 }
+span.stringliteral { color: #002080 }
+span.charliteral   { color: #008080 }

libstdc++-v3/docs/html/17_intro/howto.html

@@ -261,8 +261,9 @@
       on the --enable-libio choice:  for stdio, if the written data is
       already in the stdio buffer, the data may be completely safe!
    </p>
-   <p><strong>I/O sentry ctor/dtor</strong> They can perform additional work
-      than the minimum required.  I don't think we're currently taking
+   <p><strong>[27.6.1.1.2]</strong>,<br />
+      <strong>[27.6.2.3]</strong> The I/O sentry ctor and dtor can perform
+      additional work than the minimum required.  We are not currently taking
       advantage of this yet.
    </p>
    <p><strong>[27.7.1.3]/16</strong>,<br />

libstdc++-v3/docs/html/27_io/howto.html

@@ -34,6 +34,7 @@
    <li><a href="#7">More on binary I/O</a></li>
    <li><a href="#8">Pathetic performance?  Ditch C.</a></li>
    <li><a href="#9">Threads and I/O</a></li>
+   <li><a href="#10">Which header?</a></li>
 </ul>
 
 <hr />
@@ -558,6 +559,138 @@
       &quot;interesting&quot; problems.
    </p>
 
+<hr />
+<h2><a name="10">Which header?</a></h2>
+   <p>To minimize the time you have to wait on the compiler, it's good to
+      only include the headers you really need.  Many people simply include
+      &lt;iostream&gt; when they don't need to -- and that can <em>penalize
+      your runtime as well.</em>  Here are some tips on which header to use
+      for which situations, starting with the simplest.
+   </p>
+   <p><strong>&lt;iosfwd&gt;</strong> should be included whenever you simply
+      need the <em>name</em> of an I/O-related class, such as
+      &quot;ofstream&quot; or &quot;basic_streambuf&quot;.  Like the name
+      implies, these are forward declarations.  (A word to all you fellow
+      old school programmers:  trying to forward declare classes like
+      &quot;class istream;&quot; won't work.  Look in the iosfwd header if
+      you'd like to know why.)  For example,
+   </p>
+   <pre>
+    #include &lt;iosfwd&gt;
+
+    class MyClass
+    {
+        ....
+        std::ifstream   input_file;
+    };
+
+    extern std::ostream&amp; operator&lt;&lt; (std::ostream&amp;, MyClass&amp;);
+   </pre>
+   <p><strong>&lt;ios&gt;</strong> declares the base classes for the entire
+      I/O stream hierarchy, std::ios_base and std::basic_ios&lt;charT&gt;, the
+      counting types std::streamoff and std::streamsize, the file
+      positioning type std::fpos, and the various manipulators like
+      std::hex, std::fixed, std::noshowbase, and so forth.
+   </p>
+   <p>The ios_base class is what holds the format flags, the state flags,
+      and the functions which change them (setf(), width(), precision(),
+      etc).  You can also store extra data and register callback functions
+      through ios_base, but that has been historically underused.  Anything
+      which doesn't depend on the type of characters stored is consolidated
+      here.
+   </p>
+   <p>The template class basic_ios is the highest template class in the
+      hierarchy; it is the first one depending on the character type, and
+      holds all general state associated with that type:  the pointer to the
+      polymorphic stream buffer, the facet information, etc.
+   </p>
+   <p><strong>&lt;streambuf&gt;</strong> declares the template class
+      basic_streambuf, and two standard instantiations, streambuf and
+      wstreambuf.  If you need to work with the vastly useful and capable
+      stream buffer classes, e.g., to create a new form of storage
+      transport, this header is the one to include.
+   </p>
+   <p><strong>&lt;istream&gt;</strong>/<strong>&lt;ostream&gt;</strong> are
+      the headers to include when you are using the &gt;&gt;/&lt;&lt;
+      interface, or any of the other abstract stream formatting functions.
+      For example,
+   </p>
+   <pre>
+    #include &lt;istream&gt;
+
+    std::ostream&amp; operator&lt;&lt; (std::ostream&amp; os, MyClass&amp; c)
+    {
+       return os &lt;&lt; c.data1() &lt;&lt; c.data2();
+    }
+   </pre>
+   <p>The std::istream and std::ostream classes are the abstract parents of
+      the various concrete implementations.  If you are only using the
+      interfaces, then you only need to use the appropriate interface header.
+   </p>
+   <p><strong>&lt;iomanip&gt;</strong> provides &quot;extractors and inserters
+      that alter information maintained by class ios_base and its dervied
+      classes,&quot; such as std::setprecision and std::setw.  If you need
+      to write expressions like <code>os &lt;&lt; setw(3);</code> or
+      <code>is &gt;&gt; setbase(8);</code>, you must include &lt;iomanip&gt;.
+   </p>
+   <p><strong>&lt;sstream&gt;</strong>/<strong>&lt;fstream&gt;</strong>
+      declare the six stringstream and fstream classes.  As they are the
+      standard concrete descendants of istream and ostream, you will already
+      know about them.
+   </p>
+   <p>Finally, <strong>&lt;iostream&gt;</strong> provides the eight standard
+      global objects (cin, cout, etc).  To do this correctly, this header
+      also provides the contents of the &lt;istream&gt; and &lt;ostream&gt;
+      headers, but nothing else.  The contents of this header look like
+   </p>
+   <pre>
+    #include &lt;ostream&gt;
+    #include &lt;istream&gt;
+
+    namespace std
+    {
+        extern istream cin;
+        extern ostream cout;
+        ....
+
+        // this is explained below
+        <strong>static ios_base::Init __foo;</strong>    // not its real name
+    }
+   </pre>
+   <p>Now, the runtime penalty mentioned previously:  the global objects
+      must be initialized before any of your own code uses them; this is
+      guaranteed by the standard.  Like any other global object, they must
+      be initialized once and only once.  This is typically done with a
+      construct like the one above, and the nested class ios_base::Init is 
+      specified in the standard for just this reason.
+   </p>
+   <p>How does it work?  Because the header is included before any of your
+      code, the <strong>__foo</strong> object is constructed before any of
+      your objects.  (Global objects are built in the order in which they
+      are declared, and destroyed in reverse order.)  The first time the
+      constructor runs, the eight stream objects are set up.
+   </p>
+   <p>The <code>static</code> keyword means that each object file compiled
+      from a source file containing &lt;iostream&gt; will have its own
+      private copy of <strong>__foo</strong>.  There is no specified order
+      of construction across object files (it's one of those pesky NP
+      problems that make life so interesting), so one copy in each object
+      file means that the stream objects are guaranteed to be set up before
+      any of your code which uses them could run, thereby meeting the
+      requirements of the standard.
+   </p>
+   <p>The penalty, of course, is that after the first copy of
+      <strong>__foo</strong> is constructed, all the others are just wasted
+      processor time.  The time spent is merely for an increment-and-test
+      inside a function call, but over several dozen or hundreds of object
+      files, that time can add up.  (It's not in a tight loop, either.)
+   </p>
+   <p>The lesson?  Only include &lt;iostream&gt; when you need to use one of
+      the standard objects in that source file; you'll pay less startup
+      time.  Only include the header files you need to in general; your
+      compile times will go down when there's less parsing work to do.
+   </p>
+
 
 <!-- ####################################################### -->
 

libstdc++-v3/docs/html/documentation.html

@@ -66,7 +66,7 @@
 <ul>
    <li><a href="libstdc++-html-USERS-3.1/index.html">for the 3.1 release</a>
    </li>
-   <li><a href="libstdc++-html-USERS-3.2/index.html">for the 3.2 release</a>
+   <li><a href="libstdc++-html-USERS-3.2/index.html">for the 3.2.x release</a>
    </li>
    <li><a href="latest-doxygen/index.html">&quot;the latest collection&quot;</a>
        (for the snapshot or later; see the date on the first page)
@@ -208,6 +208,7 @@
      <li><a href="27_io/howto.html#7">More on binary I/O</a></li>
      <li><a href="27_io/howto.html#8">Pathetic performance?  Ditch C.</a></li>
      <li><a href="27_io/howto.html#9">Threads and I/O</a></li>
+     <li><a href="27_io/howto.html#10">Which header?</a></li>
    </ul>
    </li>
 

libstdc++-v3/docs/html/faq/index.html

@@ -70,7 +70,8 @@
          <li><a href="#3_5"><code>_XOPEN_SOURCE</code> /
                             <code>_GNU_SOURCE</code> / etc is always defined</a>
          </li>
-         <li><a href="#3_6">OS X ctype.h is broken!  How can I hack it?</a> </li>
+         <li><a href="#3_6">OS X ctype.h is broken!  How can I hack it?</a></li>
+         <li><a href="#3_7">Threading is broken on i386</a></li>
       </ol>
    </li>
 
@@ -498,6 +499,18 @@ which is no longer available, thanks deja...-->
       </p>
 
 <hr />
+   <h2><a name="3_7">Threading is broken on i386</a></h2>
+      <p>Support for atomic integer operations is/was broken on i386
+         platforms.  The assembly code accidentally used opcodes that are
+         only available on the i486 and later.  So if you configured GCC
+         to target, for example, i386-linux, but actually used the programs
+	 on an i686, then you would encounter no problems.  Only when
+	 actually running the code on a i386 will the problem appear.  
+      </p>
+      <p>This is fixed in 3.2.2.
+      </p>
+
+<hr />
 <h1><a name="4_0">4.0 Known Bugs and Non-Bugs</a></h1>
    <em>Note that this section can get rapdily outdated -- such is the
    nature of an open-source project.  For the latest information, join