[libstdc++] Additional documentation

[Phil Edwards <phil at jaj dot com>]

Some HTML cleanups, updates to the verbose-terminate notes, and the comment
I promised in the default terminate() implementation.



2002-12-26  Phil Edwards  <pme@gcc.gnu.org>

	* libsupc++/eh_term_handler.cc:  Add comment about embedded systems.
	* docs/html/debug.html:  Cosmetic and HTML changes.  Point to
	verb-term notes.
	* docs/html/documentation.html:  Link to the FAQ.
	* docs/html/17_intro/howto.html:  Mention use of isatty(3).
	* docs/html/19_diagnostics/howto.html:  Update verb-term description.


Index: libsupc++/eh_term_handler.cc
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/libsupc++/eh_term_handler.cc,v
retrieving revision 1.1
diff -u -3 -p -r1.1 eh_term_handler.cc
--- libsupc++/eh_term_handler.cc	26 Dec 2002 06:10:35 -0000	1.1
+++ libsupc++/eh_term_handler.cc	26 Dec 2002 21:12:12 -0000
@@ -29,6 +29,12 @@
 
 #include "unwind-cxx.h"
 
+/* We default to the talkative, informative handler.  This pulls in the
+   demangler, the dyn-string utilities, and elements of the I/O library.
+   For a low-memory environment, you can return to the earlier "silent death"
+   handler by including <cstdlib>, initializg to "std::abort", and rebuilding
+   the library.  */
+
 /* The current installed user handler.  */
 std::terminate_handler __cxxabiv1::__terminate_handler =
                                        __gnu_cxx::__verbose_terminate_handler;
Index: docs/html/debug.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/debug.html,v
retrieving revision 1.1
diff -u -3 -p -r1.1 debug.html
--- docs/html/debug.html	19 Dec 2002 08:18:14 -0000	1.1
+++ docs/html/debug.html	26 Dec 2002 21:12:12 -0000
@@ -28,16 +28,14 @@
 
 <!-- ####################################################### -->
 <hr />
-<p>
-   There are numerous things that can be done to improve the ease with
+<p>There are numerous things that can be done to improve the ease with
    which C++ binaries are debugged when using the GNU C++
    tool chain. Here are some things to keep in mind when debugging C++
    code with GNU tools.
 </p>
 
 <h3 class="left"><a name="g++">Compiler flags determine debug info</a></h3>
-<p>
-   The default optimizations and debug flags for a libstdc++ build are
+<p>The default optimizations and debug flags for a libstdc++ build are
    <code>-g -O2</code>. However, both debug and optimization flags can
    be varied to change debugging characteristics. For instance,
    turning off all optimization via the <code>-g -O0</code> flag will
@@ -53,53 +51,45 @@
    in the gcc sources.
 </p>
 
-<p>
-   Many other options are available: please see
+<p>Many other options are available: please see
 <a href=http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options> "Options for Debugging Your Program" </a>
    in Using the GNU Compiler Collection (GCC) for a complete list.
 </p>
 
 
 <h3 class="left"><a name="lib">Using special flags to make a debug binary</a></h3>
-<p>
-   There are two ways to build libstdc++ with debug flags. The first
+<p>There are two ways to build libstdc++ with debug flags. The first
    is to run make from the toplevel in a freshly-configured tree with
    specialized debug <code>CXXFLAGS</code>, as in <dd> <code> make
    CXXFLAGS='-g3 -O0' all </code></dd>
 </p>
 
-<p>
-   This quick and dirty approach is often sufficient for quick
+<p>This quick and dirty approach is often sufficient for quick
    debugging tasks, but the lack of state can be confusing in the long
    term.
 </p>
 
-<p>
-   A second approach is to use the configuration flags 
+<p>A second approach is to use the configuration flags 
 </p>
 
-   <dd><code>--enable-debug  </code></dd>
+   <dd><code>--enable-debug</code></dd>
 
-<p>
-   and perhaps 
-</p>
+<p>and perhaps</p>
 
-   <dd><code>--enable-debug-flags  </code></dd>
+   <dd><code>--enable-debug-flags='...'</code></dd>
 
-<p>
-   to create a separate debug build. Both the normal build and the
+<p>to create a separate debug build. Both the normal build and the
    debug build will persist, without having to specify
    <code>CXXFLAGS</code>, and the debug library will be installed in a
    separate directory tree, in <code>(prefix)/lib/debug</code>. For
    more information, look at the configuration options document 
-<a href=http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html> here</a>
+<a href=http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html>here</a>
 </p>
 
 
 <h3 class="left"><a name="mem">Tips for memory leak hunting</a></h3>
 
-<p>
-   There are various third party memory tracing and debug utilities
+<p>There are various third party memory tracing and debug utilities
    that can be used to provide detailed memory allocation information
    about C++ code. An exhaustive list of tools is not going to be
    attempted, but include <code>mtrace</code>, <code>valgrind</code>,
@@ -108,8 +98,7 @@
    forget right now.
 </p>
 
-<p>
-   Regardless of the memory debugging tool being used, there is one
+<p>Regardless of the memory debugging tool being used, there is one
    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
@@ -118,14 +107,13 @@
    document </a> and look specifically for <code>GLIBCPP_FORCE_NEW</code>. 
 </p>
 
-<p>
-   In a nutshell, the default allocator used by <code>
+<p>In a nutshell, the default allocator used by <code>
    std::allocator</code> is a high-performance pool allocator, and can
    give the mistaken impression that memory is being leaked, when in
    reality the memory is reclaimed after program termination.
 </p>
 
-<p> For valgrind, there are some specific items to keep in mind. First
+<p>For valgrind, there are some specific items to keep in mind. First
    of all, use a version of valgrind that will work with current GNU
    C++ tools: the first that can do this is valgrind 1.0.4, but later
    versions should work at least as well. Second of all, use a
@@ -134,15 +122,14 @@
    cluttering debug information. 
 </p>
 
-<p>
-   Fourth, it may be necessary to force deallocation in other
+<p>Fourth, it may be necessary to force deallocation in other
    libraries as well, namely the "C" library. On linux, this can be
    accomplished with the appropriate use of the
    <code>__cxa_atexit</code> or <code>atexit</code> functions.
 </p>
 
 <pre>
-   #include <cstdlib>
+   #include &lt;cstdlib&gt;
 
    extern "C" void __libc_freeres(void);
 
@@ -151,15 +138,13 @@
    int main()
    {
      atexit(__libc_freeres);
-     do_test();
+     do_something();
      return 0;
    }
 </pre>
 
 
-<p>
-   or, using <code>__cxa_atexit</code>:
-</p>
+<p>or, using <code>__cxa_atexit</code>:</p>
 
 <pre>
    extern "C" void __libc_freeres(void);
@@ -171,14 +156,13 @@
    {
       extern void* __dso_handle __attribute__ ((__weak__));
       __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, 
-	           &__dso_handle ? __dso_handle : NULL);
+                   &amp;__dso_handle ? __dso_handle : NULL);
       do_test();
       return 0;
    }
 </pre>
 
-<p>
-   Suggested valgrind flags, given the suggestions above about setting
+<p>Suggested valgrind flags, given the suggestions above about setting
    up the runtime environment, library, and test file, might be:
  
    <dd><code>valgrind -v --num-callers=20 --leak-check=yes
@@ -187,14 +171,13 @@
 
 
 <h3 class="left"><a name="gdb">Some gdb strategies</a></h3>
-<p>
-   Many options are available for gdb itself: please see <a
-href=http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC109>
-"GDB features for C++" </a> in the gdb documentation. Also
-recommended: the other parts of this manual.
+<p>Many options are available for gdb itself: please see <a
+   href=http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC109>
+   "GDB features for C++" </a> in the gdb documentation. Also
+   recommended: the other parts of this manual.
 </p>
-<p> 
-   These settings can either be switched on in at the gdb command
+
+<p>These settings can either be switched on in at the gdb command
    line, or put into a .gdbint file to establish default debugging
    characteristics, like so:
 </p>
@@ -207,6 +190,13 @@ recommended: the other parts of this man
    set print demangle on
    set demangle-style gnu-v3
 </pre>
+
+
+<h3 class="left"><a name="verbterm">Tracking uncaught exceptions</a></h3>
+<p>The <a href="19_diagnostics/howto.html#4">verbose termination handler</a>
+   gives information about uncaught exceptions which are killing the
+   program.  It is described in the linked-to page.
+</p>
 
 
 <p>Return <a href="#top">to the top of the page</a> or
Index: docs/html/documentation.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/documentation.html,v
retrieving revision 1.26
diff -u -3 -p -r1.26 documentation.html
--- docs/html/documentation.html	19 Dec 2002 08:18:14 -0000	1.26
+++ docs/html/documentation.html	26 Dec 2002 21:12:12 -0000
@@ -39,6 +39,8 @@
          - latest version info, recent changes and news</li>
          <li><a href="17_intro/TODO">TODO</a>
          - tasks yet undone</li>
+         <li><a href="faq/index.html">FAQ (HTML)</a>, 
+             <a href="faq/index.txt">FAQ (text)</a></li>
       </ul>
 
 <hr />
Index: docs/html/17_intro/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/howto.html,v
retrieving revision 1.27
diff -u -3 -p -r1.27 howto.html
--- docs/html/17_intro/howto.html	21 Nov 2002 07:15:57 -0000	1.27
+++ docs/html/17_intro/howto.html	26 Dec 2002 21:12:12 -0000
@@ -189,6 +189,9 @@
    <p>For each entry, we give the section number of the standard, when
       applicable.  This list is probably incomplet and inkorrekt.
    </p>
+   <p><strong>[1.9]/11 #3</strong> If <code>isatty(3)</code> is true, then
+      interactive stream support is implied.
+   </p>
    <p><strong>[17.4.4.5]</strong> Non-reentrant functions are probably best
       discussed in the various sections on multithreading (see above).
    </p>
Index: docs/html/19_diagnostics/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/19_diagnostics/howto.html,v
retrieving revision 1.18
diff -u -3 -p -r1.18 howto.html
--- docs/html/19_diagnostics/howto.html	7 Oct 2002 18:11:18 -0000	1.18
+++ docs/html/19_diagnostics/howto.html	26 Dec 2002 21:12:12 -0000
@@ -169,6 +169,13 @@
    %</pre>
    <p>The 'Aborted' line comes from the call to abort(), of course.
    </p>
+   <p><strong>UPDATE:</strong> Starting with GCC 3.4, this is the default
+      termination handler; nothing need be done to use it.  To go back to
+      the previous &quot;silent death&quot; method, simply include
+      <code>&lt;exception&gt;<code> and <code>&lt;cstdlib&gt;<code>, and call
+   </p>
+   <pre>
+       std::set_terminate (std::abort);</pre>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
    </p>