Re: [v3] unified TOC for docs, phase 1

["Jonathan Wakely" <jwakely dot gcc at gmail dot com>]

On 13/11/2007, Benjamin Kosnik <bkoz@redhat.com> wrote:
>
> Here's the first pass at cleaning up the libstdc++ docs. I have a
> master plan for this, which I will post in another thread.

Sweet!  As you know, I've tried to make small improvements to the docs
over the years, but never on a grand scale like this.

I was planning on submitting the attached patch but since you're
obviously working with the docs now, it might conflict or fail to
apply soon, so I'll just post it here.  It fixes some 3.x-era
anachronisms, and some more blatant lies (the example showing how to
include the extension headers is wrong, since it handles 4.0 the same
as 3.0, the minimum binutils needed to build is waaaaay out of date
etc)

Would you like me to try and apply bits of this, or would you rather
take bits and merge them with your re-worked tree?

Jon

Index: docs/html/27_io/howto.html
===================================================================
--- docs/html/27_io/howto.html	(revision 130155)
+++ docs/html/27_io/howto.html	(working copy)
@@ -756,7 +756,7 @@
          descriptor, and provides the <code>fd()</code> function.
      </li>
    </ul>
-   <p>If you want to access a <code>filebuf</code>s file descriptor to
+   <p>If you want to access a <code>filebuf</code>'s file descriptor to
       implement file locking (e.g. using the <code>fcntl()</code> system
       call) then you might be interested in Henry Suter's
       <a href="http://suter.home.cern.ch/suter/RWLock.html";>RWLock</a>
Index: docs/html/debug.html
===================================================================
--- docs/html/debug.html	(revision 130155)
+++ docs/html/debug.html	(working copy)
@@ -306,7 +306,7 @@
 <p>The following library components provide extra debugging
   capabilities in debug mode:</p>
 <ul>
-  <li><code>std::basic_string</code> (no safe iterators)</li>
+  <li><code>std::basic_string</code> (no safe iterators and see note below)</li>
   <li><code>std::bitset</code></li>
   <li><code>std::deque</code></li>
   <li><code>std::list</code></li>
@@ -321,6 +321,22 @@
   <li><code>std::unordered_multiset</code></li>
 </ul>
 
+<p>N.B. although there are precondition checks for some string operations,
+e.g.  <code>operator[]</code>,
+they will not always be run when using the <code>char</code> and
+<code>wchar_t</code> specialisations (<code>std::string</code> and
+<code>std::wstring</code>).  This is because libstdc++ uses GCC's
+<code>extern template</code> extension to provide explicit instantiations
+of <code>std::string</code> and <code>std::wstring</code>, and those
+explicit instantiations don't include the debug-mode checks.  If the
+containing functions are inlined then the checks will run, so compiling
+with <code>-O1</code> might be enough to enable them.  Alternatively
+<code>-D_GLIBCXX_EXTERN_TEMPLATE=0</code> will suppress the declarations
+of the explicit instantiations and cause the functions to be instantiated
+with the debug-mode checks included, but this is unsupported and not
+guaranteed to work.  For full debug-mode support you can use the
+<code>__gnu_debug::basic_string</code> debugging container directly,
+which always works correctly.
 
 <h3 class="left"><a name="mem">Tips for memory leak hunting</a></h3>
 
@@ -339,9 +355,9 @@
    thing of great importance to keep in mind when debugging C++ code
    that uses <code>new</code> and <code>delete</code>:
    there are different kinds of allocation schemes that can be used by
-   <code> std::allocator </code>. For implementation details, see this
-   <a href="ext/howto.html#3"> document</a> and look specifically for
-   <code>GLIBCXX_FORCE_NEW</code>. 
+   <code> std::allocator </code>. For implementation details, see the
+   <a href="ext/mt_allocator.html">mt allocator</a> documentation and
+   look specifically for <code>GLIBCXX_FORCE_NEW</code>. 
 </p>
 
 <p>In a nutshell, the default allocator used by <code>
Index: docs/html/21_strings/howto.html
===================================================================
--- docs/html/21_strings/howto.html	(revision 130155)
+++ docs/html/21_strings/howto.html	(working copy)
@@ -380,7 +380,7 @@
    </p>
    <p>That's the theory.  Remember however that basic_string has additional
       type parameters, which take default arguments based on the character
-      type (called CharT here):
+      type (called <code>CharT</code> here):
    </p>
    <pre>
       template &lt;typename CharT,
@@ -405,10 +405,7 @@
    <p>and functions such as char_traits&lt;CharT&gt;::foo() are not
       actually defined anywhere for the general case.  The C++ standard
       permits this, because writing such a definition to fit all possible
-      CharT's cannot be done.  (For a time, in earlier versions of GCC,
-      there was a mostly-correct implementation that let programmers be
-      lazy.  :-)  But it broke under many situations, so it was removed.
-      You are no longer allowed to be lazy and non-portable.)
+      CharT's cannot be done.
    </p>
    <p>The C++ standard also requires that char_traits be specialized for
       instantiations of <code>char</code> and <code>wchar_t</code>, and it
@@ -417,16 +414,22 @@
    </p>
    <p>If you want to use character types other than char and wchar_t,
       such as <code>unsigned char</code> and <code>int</code>, you will
-      need to write specializations for them at the present time.  If you
-      want to use your own special character class, then you have
+      need suitable specializations for them.  For a time, in earlier
+      versions of GCC, there was a mostly-correct implementation that
+      let programmers be lazy but it broke under many situations, so it
+      was removed.  GCC 3.4 introduced a new implementation that mostly
+      works and can be specialized even for <code>int</code> and other
+      built-in types.
+   </p>
+   <p>If you want to use your own special character class, then you have
       <a href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00163.html";>a lot
       of work to do</a>, especially if you with to use i18n features
       (facets require traits information but don't have a traits argument).
    </p>
-   <p>One example of how to specialize char_traits is given <a
-      href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00260.html";>in
-      this message</a>, which was then put into the file <code>
-      include/ext/pod_char_traits.h</code> at a later date.  We agree
+   <p>Another example of how to specialize char_traits was given <a
+      href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00260.html";>on the
+      mailing list</a> and at a later date was put into the file <code>
+      include/ext/pod_char_traits.h</code>.  We agree
       that the way it's used with basic_string (scroll down to main())
       doesn't look nice, but that's because <a
       href="http://gcc.gnu.org/ml/libstdc++/2002-08/msg00236.html";>the
@@ -435,11 +438,6 @@
       be conforming C++</a>, due to the rule that CharT must be a POD.
       (See how tricky this is?)
    </p>
-   <p>Other approaches were suggested in that same thread, such as providing
-      more specializations and/or some helper types in the library to assist
-      users writing such code.  So far nobody has had the time...
-      <a href="../17_intro/contribute.html">do you?</a>
-   </p>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
    </p>
Index: docs/html/ext/howto.html
===================================================================
--- docs/html/ext/howto.html	(revision 130155)
+++ docs/html/ext/howto.html	(working copy)
@@ -114,8 +114,7 @@
    <p>(Side note:  for those of you wondering, <strong>&quot;Why wasn't a hash
       table included in the Standard in the first #!$@ place?&quot;</strong>
       I'll give a quick answer:  it was proposed, but too late and in too
-      unorganized a fashion.  Some sort of hashing will undoubtedly be
-      included in a future Standard.)
+      unorganized a fashion.)
    </p>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
@@ -137,6 +136,8 @@
      <li>Extensions allowing <code>filebuf</code>s to be constructed from
          stdio types are described in the
          <a href="../27_io/howto.html#11">chapter 27 notes</a>.</li>
+     <li>The C++ Standard Library Technical Report adds many new features
+         to the library, see <a href="../faq/index.html#5_5">FAQ 5.5</a>.</li>
    </ul>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
@@ -423,8 +424,8 @@
     <dt><a href="lwg-defects.html#241">241</a>:
         <em>Does unique_copy() require CopyConstructible and Assignable?</em>
     </dt>
-    <dd>Add an helper for forward_iterator/output_iterator, fix the existing
-        one for input_iterator/output_iterator not to rely on Assignability.
+    <dd>Add a helper for forward_iterator/output_iterator, fix the existing
+        one for input_iterator/output_iterator to not rely on Assignability.
     </dd>
 
     <dt><a href="lwg-defects.html#243">243</a>:
Index: docs/html/22_locale/codecvt.html
===================================================================
--- docs/html/22_locale/codecvt.html	(revision 130155)
+++ docs/html/22_locale/codecvt.html	(working copy)
@@ -203,7 +203,7 @@
 </li>
 
 <li>
- Some encodings are require explicit endian-ness. As such, some kind
+ Some encodings require explicit endian-ness. As such, some kind
   of endian marker or other byte-order marker will be necessary. See
   &quot;Footnotes for C/C++ developers&quot; in Haible for more information on
   UCS-2/Unicode endian issues. (Summary: big endian seems most likely,
Index: docs/html/17_intro/howto.html
===================================================================
--- docs/html/17_intro/howto.html	(revision 130155)
+++ docs/html/17_intro/howto.html	(working copy)
@@ -210,7 +210,7 @@
       library.  This information is GCC-specific since the C++
       standard does not address matters of multithreaded applications.
       Unless explicitly prefaced, all information in this section is
-      current as of the GCC 3.0 release and all later point releases.
+      relevant to the GCC 3.0 release and all later releases.
    </p>
    <p>Earlier GCC releases had a somewhat different approach to
       threading configuration and proper compilation.  Before GCC 3.0,
@@ -257,13 +257,13 @@
       AFAIK, none of this is properly documented anywhere other than
       in ``gcc -dumpspecs'' (look at lib and cpp entries).
    </p>
-   <p>See <a href="../faq/index.html#3">FAQ</a> (general overview), <a
+   <p>See <a href="../faq/index.html#5_6">FAQ</a> (general overview), <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>
-   <p>The libstdc++ library (unlike libstdc++-v2, all of it, not
-      just the STL) has been designed so that multithreaded
-      applications using it may be written.  The first problem is
+   <p>The libstdc++ library has been designed so that multithreaded
+      applications using it may be written (with libstdc++-v2 this was
+      only true of the STL parts.)  The first problem is
       finding a <em>fast</em> 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
@@ -274,7 +274,8 @@
       href="http://www.sgi.com/tech/stl/thread_safety.html";>same
       definition that SGI</a> uses for their STL subset.  However, the
       exception for read-only containers only applies to the STL
-      components.
+      components. This definition is widely-used and something similar
+      will be used in the next version of the C++ standard library.
    </p>
    <p>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
Index: docs/html/faq/index.html
===================================================================
--- docs/html/faq/index.html	(revision 130155)
+++ docs/html/faq/index.html	(working copy)
@@ -100,6 +100,7 @@
            <li><a href="#4_4_dlsym">program crashes when using library code
                                in a dynamically-loaded library</a> </li>
            <li><a href="#4_4_leak">"memory leaks" in containers</a> </li>
+           <li><a href="#4_4_list_size">list::size() is O(n)!</a> </li>
          </ul>
          </li>
          <li><a href="#4_5">Aw, that's easy to fix!</a> </li>
@@ -278,22 +279,25 @@
          an installation document), but the tools required are few:
       </p>
          <ul>
-            <li> A 3.x release of GCC.  Note that building GCC is much
-                 easier and more automated than building the GCC 2.[78]
-                 series was.  If you are using GCC 2.95, you can still
-                 build earlier snapshots of libstdc++.
+            <li> A 3.x or later release of GCC.  Either install a suitable
+                 package for your system, or compile GCC from the sources.
+                 Note that building GCC
+                 is much easier and more automated than building the GCC
+                 2.[78] series was.  If you are using GCC 2.95, you can
+                 still build earlier snapshots of libstdc++ but you
+                 should consult the documentation that comes with the
+                 sources, the instructions are no longer included here.
             </li>
-            <li> GNU Make is required for GCC 3.4 and later.
+            <li> GNU Make is required to build GCC 3.4 and later.
             </li>
             <li> The GNU Autotools are needed if you are messing with
                  the configury or makefiles.
             </li>
          </ul>
-      <p>The file <a href="../documentation.html">documentation.html</a>
-         provides a good overview of the steps necessary to build, install,
+      <p>The file <a href="../documentation.html#2">documentation.html</a>
+         links to documentation of the steps necessary to build, install,
          and use the library.  Instructions for configuring the library
-         with new flags such as --enable-threads are there also, as well as
-         patches and instructions for working with GCC 2.95.
+         with flags such as --enable-threads are there also.
       </p>
       <p>The top-level install.html file contains
          the exact build and installation instructions.  You may wish to
@@ -794,6 +798,10 @@
          first.
       </p>
 
+      <p><a name="4_4_list_size"><strong>list::size() is O(n)!</strong></a>
+         See the <a href='../23_containers/howto.html#6'>Containers</a>
+         chapter.
+      </p>
 <hr />
    <h2><a name="4_5">4.5 Aw, that's easy to fix!</a></h2>
       <p>If you have found a bug in the library and you think you have
@@ -851,10 +859,14 @@
          resolution specifies.  Those additions are listed in
          <a href="../ext/howto.html#5">the extensions page</a>.
       </p></li>
-      <li><p>Performance tuning.  Lots of performance tuning.  This too is
-         already underway for post-3.0 releases, starting with memory
-         expansion in container classes and buffer usage in synchronized
-         stream objects.
+      <li><p>Performance tuning.  Lots of performance tuning was done for the
+         3.x releases, including memory expansion in container classes and
+         buffer usage in synchronized stream objects.
+         <!-- TODO Paolo, please mention performance work -->
+         <!-- TODO also MT alloc stuff -->
+         Current performance-related work includes simulated "move semantics"
+         for containers and (optional) non-reference-counted strings (which
+         can give performance benefits for multithreaded programs.)
       </p></li>
       <li><p>An ABI for libstdc++ is being developed, so that
          multiple binary-incompatible copies of the library can be replaced
@@ -933,7 +945,7 @@
         namespace extension { using ::hash_map; }; // inherit globals
       #else
         #include &lt;backward/hash_map&gt;
-        #if __GNUC_MINOR__ == 0
+        #if __GNUC__ == 3 &amp;&amp; __GNUC_MINOR__ == 0
           namespace extension = std;               // GCC 3.0
         #else
           namespace extension = ::__gnu_cxx;       // GCC 3.1 and later
@@ -1110,6 +1122,9 @@
       <p>Who is your country's member body?  Visit the
          <a href="http://www.iso.ch/";>ISO homepage</a> and find out!
       </p>
+      <p>The 2003 version of the standard (the 1998 version plus TC1) is
+         available in print, ISBN 0-470-84674-7.
+      </p>
 
 <hr />
    <h2><a name="5_8">5.8 What's an ABI and why is it so messy?</a></h2>
Index: docs/html/23_containers/howto.html
===================================================================
--- docs/html/23_containers/howto.html	(revision 130155)
+++ docs/html/23_containers/howto.html	(working copy)
@@ -284,11 +284,13 @@
    <pre>
       a.insert(p,t);</pre>
    <p>where 'p' is an iterator into the container 'a', and 't' is the item
-      to insert.  The standard says that &quot;iterator p is a hint
-      pointing to where the insert should start to search,&quot; but
-      specifies nothing more.  (LWG Issue #233, currently in review,
-      addresses this topic, but I will ignore it here because it is not yet
-      finalized.)
+      to insert.  The standard says that &quot;<code>t</code> is inserted
+      as close as possible to the position just prior to
+      <code>p</code>.&quot; (Library DR #233 addresses this topic, referring to
+      <a href='http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1780.html'>N1780</a>.
+      Since version 4.2 GCC implements the resolution to DR 233, so that
+      insertions happen as close as possible to the hint. For earlier releases
+      the hint was only used as described below.
    </p>
    <p>Here we'll describe how the hinting works in the libstdc++
       implementation, and what you need to do in order to take advantage of
@@ -342,21 +344,17 @@
       <code>map</code> and <code>set</code> classes.  You should not use a hint
       argument in those releases.)
    </p>
-   <p>This behavior goes well with other container's <code>insert()</code>
+   <p>This behavior goes well with other containers' <code>insert()</code>
       functions which take an iterator:  if used, the new item will be
       inserted before the iterator passed as an argument, same as the other
-      containers.  The exception
-      (in a sense) is with a hint of <code>end()</code>:  the new item will
-      actually be inserted after <code>end()</code>, but it also becomes the
-      new <code>end()</code>.
+      containers. 
    </p>
    <p><strong>Note </strong> also that the hint in this implementation is a
-      one-shot.  The insertion-with-hint routines check the immediately
+      one-shot.  The older insertion-with-hint routines check the immediately
       surrounding entries to ensure that the new item would in fact belong
       there.  If the hint does not point to the correct place, then no
       further local searching is done; the search begins from scratch in
-      logarithmic time.  (Further local searching would only increase the
-      time required when the hint is too far off.)
+      logarithmic time.
    </p>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
Index: docs/html/install.html
===================================================================
--- docs/html/install.html	(revision 130155)
+++ docs/html/install.html	(working copy)
@@ -56,17 +56,15 @@
       also lists the tools you will need if you wish to modify the source.
    </p>
 
-   <p>As of June 19, 2000, libstdc++ attempts to use tricky and
-      space-saving features of the GNU toolchain, enabled with
-      <code>-ffunction-sections -fdata-sections -Wl,--gc-sections</code>.
-      To obtain maximum benefit from this, binutils after this date should
-      also be used (bugs were fixed with C++ exception handling related
-      to this change in libstdc++).  The version of these tools should
-      be <code>2.10.90</code>, or later, and you can get snapshots (as
-      well as releases) of binutils
-      <a href="ftp://sources.redhat.com/pub/binutils";>here</a>. The
-      configure process will automatically detect and use these features
-      if the underlying support is present.
+   <p>As of GCC 4.0.1 the minimum version of binutils required to build
+      libstdc++ is <code>2.15.90.0.1.1</code>. You can get snapshots
+      (as well as releases) of binutils from
+      <a href="ftp://sources.redhat.com/pub/binutils";>ftp://sources.redhat.com/pub/binutils</a>.
+      Older releases of libstdc++ do not require such a recent version,
+      but to take full advantage of useful space-saving features and
+      bug-fixes you should use a recent binutils if possible.
+      The configure process will automatically detect and use these
+      features if the underlying support is present.
    </p>
 
    <p>Finally, a few system-specific requirements: </p>