[rfa/doc] correct info about best C++ compilers/debug formats

[David Carlton <carlton@math.stanford.edu>]

As noted in PR symtab/874, the information in the manual about the
best debug formats for C++ is not only incorrect but actively
harmful.  Here's an attempt at a patch.  So:

* Eli: Is the TeXinfo okay?  What about the choice of cindex entries?
  When I actually looked at the index, I found that it generated three
  consecutive entries "C++ and ..." that all pointed at the same
  place; I'm tempted to get rid of the C++ and GCC entry, since that's
  really a special case of C++ and compilers.

* Daniel (and Michael): Is the content okay?  I decided to take a
  conservative approach, not promising support for compilers/debug
  formats that we don't intend to work on.

* Daniel, Michael: Once this goes in, should we get rid of the DWARF 1
  xfails in gdb.c++ and simply not run the C++ testsuite under DWARF
  1?

I'd like to apply this to 5.3 as well as mainline, on the slim chance
that 5.3.1 might happen, because the information in the doc now really
is bad.

David Carlton
carlton@math.stanford.edu

2003-02-03  David Carlton  <carlton@math.stanford.edu>

	* gdb.texinfo (C plus plus expressions): Correct info about
	compiler/debug formats for C++ debugging.  PR symtab/874.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.145
diff -u -p -r1.145 gdb.texinfo
--- gdb.texinfo	1 Feb 2003 20:51:06 -0000	1.145
+++ gdb.texinfo	3 Feb 2003 18:08:27 -0000
@@ -8062,28 +8062,22 @@ and @samp{@{&"hi", &"there", &"fred"@}} 
 @cindex expressions in C@t{++}
 @value{GDBN} expression handling can interpret most C@t{++} expressions.
 
-@cindex C@t{++} support, not in @sc{coff}
-@cindex @sc{coff} versus C@t{++}
-@cindex C@t{++} and object formats
-@cindex object formats and C@t{++}
-@cindex a.out and C@t{++}
-@cindex @sc{ecoff} and C@t{++}
-@cindex @sc{xcoff} and C@t{++}
+@cindex C@t{++} and debug formats
+@cindex debug formats and C@t{++}
 @cindex @sc{elf}/stabs and C@t{++}
 @cindex @sc{elf}/@sc{dwarf} and C@t{++}
-@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check
-@c periodically whether this has happened...
+@cindex C@t{++} compilers
+@cindex C@t{++} and @value{NGCC}
+@cindex @value{NGCC} and C@t{++}
 @quotation
 @emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the
-proper compiler.  Typically, C@t{++} debugging depends on the use of
-additional debugging information in the symbol table, and thus requires
-special support.  In particular, if your compiler generates a.out, MIPS
-@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the
-symbol table, these facilities are all available.  (With @sc{gnu} CC,
-you can use the @samp{-gstabs} option to request stabs debugging
-extensions explicitly.)  Where the object code format is standard
-@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C@t{++}
-support in @value{GDBN} does @emph{not} work.
+proper compiler and the proper debug format.  Currently, @value{GDBN}
+works best when debugging C@t{++} code that is compiled with
+@value{NGCC} 2.95.3 or with @value{NGCC} 3.1 or newer, using the options
+@option{-gdwarf-2} or @option{-gstabs+}.  DWARF 2 is preferred over
+stabs; newer versions of @value{NGCC} use DWARF 2 as the default
+whenever possible.  Other compilers and/or debug formats are likely to
+work badly or not at all when using @value{GDBN} to debugg C@t{++} code.
 @end quotation
 
 @enumerate