documentation.html: Validate.

2007-11-20  Benjamin Kosnik  <bkoz@redhat.com>

	* docs/html/documentation.html: Validate. Add links to index,
	correct broken links.
	* docs/html/17_intro/C++STYLE: Add bits.
	* docs/html/17_intro/configury.html: Correct, update.
	* docs/html/17_intro/api.html: Correct HTML.

	* include/bits/stl_algobase.h: Adjust comment.

From-SVN: r130331

6 files changed, 107 insertions, 56 deletions

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index 452223a..91914689 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,3 +1,13 @@
+2007-11-20  Benjamin Kosnik  <bkoz@redhat.com>
+
+	* docs/html/documentation.html: Validate. Add links to index,
+	correct broken links.
+	* docs/html/17_intro/C++STYLE: Add bits.
+	* docs/html/17_intro/configury.html: Correct, update.
+	* docs/html/17_intro/api.html: Correct HTML.
+
+	* include/bits/stl_algobase.h: Adjust comment.
+	
 2007-11-20  Richard Sandiford  <rsandifo@nildram.co.uk>
 
 	* testsuite/ext/throw_allocator/variadic_construct.cc: Add
diff --git a/libstdc++-v3/docs/html/17_intro/C++STYLE b/libstdc++-v3/docs/html/17_intro/C++STYLE
index 87f53d0..45fad27 100644
--- a/libstdc++-v3/docs/html/17_intro/C++STYLE
+++ b/libstdc++-v3/docs/html/17_intro/C++STYLE
@@ -1,12 +1,21 @@
 
-C++ Standard Library Style Guidelines  DRAFT 2001-01-15
+C++ Standard Library Coding Style Guidelines  
 -------------------------------------
 
 This library is written to appropriate C++ coding standards.  As such,
 it is intended to precede the recommendations of the GNU Coding
-Standard, which can be referenced here:
+Standard, which can be referenced in full here:
 
-http://www.gnu.org/prep/standards_toc.html
+http://www.gnu.org/prep/standards/standards.html#Formatting
+
+The rest of this is also interesting reading, but skip the "Design
+Advice" part.
+
+The GCC coding conventions are here, are are also useful:
+http://gcc.gnu.org/codingconventions.html
+
+In addition, because it doesn't seem to be stated explicitly anywhere
+else, there is an 80 column source limit.
 
 ChangeLog entries for member functions should use the
 classname::member function name syntax as follows:
@@ -220,6 +229,9 @@ Notable areas of divergence from what may be previous local practice
     give useful error messages, and programmers can intelligently
     speculate what went wrong without even using a debugger.
 
+17. The doxygen style guide to comments is a separate document,
+    see index.
+
 The library currently has a mixture of GNU-C and modern C++ coding
 styles.  The GNU C usages will be combed out gradually.
 
@@ -264,7 +276,6 @@ namespace std
   class gribble
   {
   public:
-    // ctor, op=, dtor
     gribble() throw();
 
     gribble(const gribble&);
@@ -278,11 +289,11 @@ namespace std
     virtual 
     ~gribble() throw ();
 
-    // argument
+    // Start with a capitol letter, end with a period.
     inline void  
     public_member(const char* __arg) const;
 
-    // in-class function definitions should be restricted to one-liners.
+    // In-class function definitions should be restricted to one-liners.
     int 
     one_line() { return 0 }
 
@@ -293,7 +304,7 @@ namespace std
     inline int 
     three_lines();  // inline, but defined below.
 
-    // note indentation
+    // Note indentation.
     template<typename _Formal_argument>
       void 
       public_template() const throw();
@@ -320,7 +331,7 @@ namespace std
     _S_initialize_library();
   };
 
-// More-or-less-standard language features described by lack, not presence:
+// More-or-less-standard language features described by lack, not presence.
 # ifndef _G_NO_LONGLONG
   extern long long _G_global_with_a_good_long_name;  // avoid globals!
 # endif
@@ -384,3 +395,5 @@ namespace std
   }
 } // namespace std
 
+
+
diff --git a/libstdc++-v3/docs/html/17_intro/api.html b/libstdc++-v3/docs/html/17_intro/api.html
index 50c8604..bfe7b20 100644
--- a/libstdc++-v3/docs/html/17_intro/api.html
+++ b/libstdc++-v3/docs/html/17_intro/api.html
@@ -52,7 +52,7 @@ details were not pried away from the estate.
 <p> 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>.
 </p>
 
-<h5>No <code>cout</code> in <code>ostream.h</code>, no <code>cin</code> in <code>istream.h</code</h5>
+<h5>No <code>cout</code> in <code>ostream.h</code>, no <code>cin</code> in <code>istream.h</code></h5>
 
 <p>
 	In earlier versions of the standard,
diff --git a/libstdc++-v3/docs/html/17_intro/configury.html b/libstdc++-v3/docs/html/17_intro/configury.html
index 1c9acf2..a35ccf2 100644
--- a/libstdc++-v3/docs/html/17_intro/configury.html
+++ b/libstdc++-v3/docs/html/17_intro/configury.html
@@ -34,30 +34,46 @@ No problem is insoluble in all conceivable circumstances.<br />
 Last Question</a>, by Isaac Asimov
 </blockquote>
 <ul>
- <li><a href="#deps">what comes from where</a></li>
- <li><a href="#breakout">storing information in non-AC files, like
+ <li><a href="#prereq">Prerequisites for configure and make hacking</a></li>
+ <li><a href="#deps">Overview: what comes from where</a></li>
+ <li><a href="#breakout">Storing information in non-AC files, like
                          configure.host</a></li>
- <li><a href="#general">general config notes</a></li>
- <li><a href="#aclayout">acinclude.m4 layout</a></li>
- <li><a href="#enable"><code>--enable</code> howto</a></li>
+ <li><a href="#general">Coding and commenting conventions</a></li>
+ <li><a href="#aclayout">The acinclude.m4 layout</a></li>
+ <li><a href="#enable"><code>GLIBCXX_ENABLE, the --enable</code> howto</a></li>
 </ul>
 
 <hr />
-<h3><a name="deps">what comes from where</a></h3>
+<h3><a name="prereq">Prerequisites for configure and make hacking</a></h3>
+
+<p> As
+noted <a href="http://gcc.gnu.org/install/prerequisites.html">previously</a>,
+certain other tools are necessary for hacking on files that control
+configure (<code>configure.ac</code>, <code>acinclude.m4</code>) and
+make (<code>Makefile.am</code>). These additional tools
+(<code>automake</code>, and <code>autoconf</code>) are further
+described in detail in their respective manuals. All the libraries in GCC try to stay in sync with each other in terms of versions of the auto-tools used, so please try to play nicely with the neighbors.
+</p>
+
+
+<hr />
+<h3><a name="deps">Overview: what comes from where</a></h3>
 <p class="centered"><img src="confdeps.png"
   alt="Dependency graph in PNG graphics format.  (Get a better browser!)" /></p>
 
-<p>Regenerate using a command sequence like
-   <code>"aclocal-1.7 &amp;&amp; autoconf-2.59 &amp;&amp; autoheader-2.59
-   &amp;&amp; automake-1.7"</code> as needed.  And/or configure with
-   --enable-maintainer-mode.  The version numbers will vary depending on
+<p>Regenerate all generated files by using the command sequence
+ <code>"autoreconf"</code> at the top level of the libstdc++ source
+ directory. The following will also work, but is much more complex:
+   <code>"aclocal-1.7 &amp;&amp; autoconf-2.59 &amp;&amp;
+   autoheader-2.59 &amp;&amp; automake-1.7"</code> The version numbers
+   may be absent entirely or otherwise vary depending on
    <a href="http://gcc.gnu.org/install/prerequisites.html">the current
    requirements</a> and your vendor's choice of installation names.
 </p>
 
 
 <hr />
-<h3><a name="breakout">storing information in non-AC files, like
+<h3><a name="breakout">Storing information in non-AC files, like
                        configure.host</a></h3>
 <p>Until that glorious day when we can use AC_TRY_LINK with a cross-compiler,
    we have to hardcode the results of what the tests would have shown if
@@ -82,7 +98,7 @@ Last Question</a>, by Isaac Asimov
 
 
 <hr />
-<h3><a name="general">general config notes</a></h3>
+<h3><a name="general">Coding and commenting conventions</a></h3>
 <p>Lots of stuff got thrown out because the new autotools kindly generate
    the same (or better) shell code for us.
 </p>
@@ -108,7 +124,7 @@ Last Question</a>, by Isaac Asimov
 </p>
 
 <hr />
-<h3><a name="aclayout">acinclude.m4 layout</a></h3>
+<h3><a name="aclayout">The acinclude.m4 layout</a></h3>
 <p>The nice thing about acinclude.m4/aclocal.m4 is that macros aren't actually
    performed/called/expanded/whatever here, just loaded.  So we can arrange
    the contents however we like.  As of this writing, acinclude.m4 is arranged
@@ -186,7 +202,7 @@ Last Question</a>, by Isaac Asimov
 
 
 <hr />
-<h3><a name="enable"><code>--enable</code> howto</a></h3>
+<h3><a name="enable">GLIBCXX_ENABLE, the <code>--enable</code> howto</a></h3>
 <p>All the GLIBCXX_ENABLE_FOO macros use a common helper, GLIBCXX_ENABLE.
    (You don't have to use it, but it's easy.)  The helper does two things
    for us:
diff --git a/libstdc++-v3/docs/html/documentation.html b/libstdc++-v3/docs/html/documentation.html
index f14d1b6..92ce87b 100644
--- a/libstdc++-v3/docs/html/documentation.html
+++ b/libstdc++-v3/docs/html/documentation.html
@@ -57,51 +57,53 @@ href="http://gcc.gnu.org/svn.html">web</a>.
    		</ul>
    	</li>
          <li><a href="17_intro/license.html">License</a></li>
-         <li><a href="http://gcc.gnu.org/bugzilla/buglist.cgi?cmdtype=runnamed&namedcmd=libstdc%2B%2B">Known Bugs</a></li>
+         <li><a href="http://gcc.gnu.org/bugzilla/buglist.cgi?cmdtype=runnamed&amp;namedcmd=libstdc%2B%2B">Known Bugs</a></li>
 
 </ul>
     </li>
 
 
 
-    <li> Configuring, Building, Testing, Installing
+    <li> Configuring, Building, Testing, Installing 
 <ul>
    <li><a href="install.html">Getting started: configure, build, install</a>
    </li>
    <li><a href="configopts.html">Configure options</a></li>
    <li><a href="test.html">Testing details</a></li>
-   </li>
 </ul>
-    </li>
+  </li>
 
-    <li> Using the Library
+    <li> Using the Library 
       <ul>
-         <li>Header Files</li>
+         <li>Header Files
          <ul>
          <li><a href="17_intro/howto.html#2.1">Available headers</a></li>
          <li><a href="17_intro/howto.html#2.2">Headers and <code>namespace std</code></a></li>
          <li>Pre-compiled headers</li>
          </ul>
+	 </li>
 
-         <li>Namespaces</li>
+         <li>Namespaces
          <ul>
          <li><a href="17_intro/howto.html#2.5">Namespace <code>std::</code></a></li>
          <li><a href="17_intro/howto.html#2.6">Using namespace composition</a></li>
          </ul>
+	 </li>
          <li><a href="17_intro/howto.html#6">Macros</a></li>
 
- 	<li>Concurrency</li>
+ 	<li>Concurrency
          <ul>
          <li>Atomic Operations</li>
          <li><a href="17_intro/howto.html#3">Thread safety overview</a></li>
 
-	  <li><a href="faq/index.html#5_6">Is it thread safe?</li>
+	  <li><a href="faq/index.html#5_6">Is it thread safe?</a></li>
 	  <li><a href="23_containers/howto.html#3">Containers</a></li>
 	  <li><a href="27_io/howto.html#9">IO</a></li>
          </ul>
+	 </li>
          <li>Exception safety</li>
 
-         <li><a href="debug.html">Debugging support</a>
+         <li><a href="debug.html">Debugging support</a></li>
       </ul>
     </li>
 
@@ -130,15 +132,18 @@ href="http://gcc.gnu.org/svn.html">web</a>.
    <ul>
      <li><a href="20_util/howto.html#3">Functors</a></li>
      <li><a href="20_util/howto.html#4">Pairs</a></li>
-     <li>Memory</li>
-    <ul>
-    <li><a href="20_util/allocator.html">allocator</a></li>
-    <li>auto_ptr</li>
-    <ul>
+
+     <li>Memory
+     <ul>
+     <li><a href="20_util/allocator.html">allocator</a></li>
+     <li>auto_ptr
+     <ul>
      <li><a href="20_util/howto.html#1"><code>auto_ptr</code> is not omnipotent</a></li>
      <li><a href="20_util/howto.html#2"><code>auto_ptr</code> inside container classes</a></li>
     </ul>
+    </li>
    </ul>
+   </li>
    </ul>
    </li>
 
@@ -215,62 +220,70 @@ href="http://gcc.gnu.org/svn.html">web</a>.
    <li>Extensions
    <ul>
      <li><a href="ext/howto.html#4">Compile-time checks</a></li>
-     <li><a href="debug_mode.html">Debug mode</a></li>
-     <li><a href="parallel_mode.html">Parallel mode</a></li>
-     <li> Allocators</li>
+     <li><a href="ext/debug_mode.html">Debug mode</a></li>
+     <li><a href="ext/parallel_mode.html">Parallel mode</a></li>
+     <li> Allocators
      <ul>
      <li><a href="ext/mt_allocator.html"><code>__mt_alloc</code> </a></li>
      <li><a href="ext/ballocator_doc.html">Bitmap Allocator</a></li>
      </ul>
+     </li>
 
-     <li> Containers </li>
+     <li> Containers
        <ul> 
        <li><a href="ext/pb_ds/index.html">Policy Based Data Structures</a></li>
        <li><a href="ext/howto.html#1">Ropes and trees and hashes, oh my!</a></li>
        </ul>
+     </li>
 
-     <li> Algorithms</li>
+     <li> Algorithms
 <ul>
      <li><a href="ext/sgiexts.html">HP/SGI STL Extensions</a></li>
 </ul>
+</li>
 
-     <li> Input/Output</li>
+     <li> Input/Output
 <ul>
      <li><a href="27_io/howto.html#11">Derived filebuf classes</a></li>
 </ul>
+</li>
      <li><a href="ext/../18_support/howto.html#6">Demangling</a></li>
    </ul>
    </li>
 
    <li>Appendix
    <ul>
-     <li>A. <a name="5">Contributing and Maintenance</a></li>
+
+     <li>A. <a name="5">Contributing and Maintenance</a>
 <ul>
    <li><a href="17_intro/contribute.html">Contributor checklist</a></li>
    <li><a href="http://gcc.gnu.org/svnwrite.html">Getting write access
        (look for &quot;Write after approval&quot;)</a></li>
-   <li><a href="17_intro/BADNAMES">BADNAMES</a>
+   <li><a href="17_intro/BADNAMES">Identifier blacklist</a>
        - names to avoid because of potential collisions</li>
    <li><a href="17_intro/C++STYLE">Coding style, by example</a></li>
-   <li> Doxygen markup style guide. In the source docs/doxygen directory, see guide.html. Here's the a link to the current <a href="http://gcc.gnu.org/viewcvs/*checkout*/trunk/libstdc%2B%2B-v3/docs/doxygen/guide.html?content-type=text%2Fplain">page</a>.
-</li>
-   <li><a href="17_intro/DESIGN">DESIGN</a>
-       - overview of the implementation plan</li>
+
+   <li> Comment coding style, a doxygen markup style guide. In the source docs/doxygen directory, see <a href="http://gcc.gnu.org/viewcvs/*checkout*/trunk/libstdc%2B%2B-v3/docs/doxygen/guide.html">guide.html</a>.</li>
+   <li><a href="17_intro/DESIGN">Design Notes</a>
+       - notes on the implementation plan</li>
+   <li><a href="17_intro/configury.html">Editing configure and make files</a></li>
   <li>Header policy, namespace map, API conventions</li>
 </ul>
+</li>
 
-     <li>B. Porting</li>
+     <li>B. Porting
 
 <ul>
      <li><a href="17_intro/porting.html">Porting to new hardware or operating systems.</a></li>
      <li><a href="17_intro/abi.html">ABI Policy and Guidelines</a></li>
      <li><a href="17_intro/api.html">API Evolution and Deprecation History</a></li>
 </ul>
+</li>
+
+     <li>C. <a href="http://www.gnu.org/software/libc/manual/html_node/Free-Manuals.html#Free-Manuals">Free Software Needs Free Documentation </a></li>
 
-     <li>C. <a href="http://www.gnu.org/software/libc/manual/html_node/Free-Manuals.html#Free-Manuals">Free Software Needs Free Documentation </a>
    </ul>
    </li>
-
   </ul>
 <!-- endlist -->
 
@@ -314,7 +327,7 @@ href="http://gcc.gnu.org/svn.html">web</a>.
 
 <hr />
 <br />
-<h2><a name="7"><a href="faq/index.html">Frequently Asked Questions</a></a></h2
+<h2><a name="7" href="faq/index.html">Frequently Asked Questions</a></h2
 
 <hr />
 <br />
diff --git a/libstdc++-v3/include/bits/stl_algobase.h b/libstdc++-v3/include/bits/stl_algobase.h
index f9f3be1..32dfacd 100644
--- a/libstdc++-v3/include/bits/stl_algobase.h
+++ b/libstdc++-v3/include/bits/stl_algobase.h
@@ -1,4 +1,4 @@
-// Bits and pieces used in algorithms -*- C++ -*-
+// Core algorithmic facilities -*- C++ -*-
 
 // Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
 // Free Software Foundation, Inc.
@@ -1084,7 +1084,6 @@ _GLIBCXX_END_NESTED_NAMESPACE
 // of getting the base algorithms. So, make sure that parallel bits
 // come in too if requested. 
 #ifdef _GLIBCXX_PARALLEL
-//# include <parallel/algorithm>
 # include <parallel/algobase.h>
 #endif