* gdb.texinfo (New Features): mention threads.

	(Summary, C): fix xrefs in newly contributed text.
	(Threads): index entries, clarifications, example
	(passim): minor typos fixed, phrasing improvements

	* remote.texi (Bootstrapping): rephrase text on ^C and add index
	entries; (Server): explain use of gdbserver w/real-time systems,
	add example of conflicting TCP port; (MIPS Remote) break up
	running text into table, highlighting commands, and add example.

3 files changed, 158 insertions, 80 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index bf181a3..aa3f517 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,19 @@
+Sun Nov 28 18:06:25 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* gdb.texinfo (New Features): mention threads.
+	(Summary, C): fix xrefs in newly contributed text.
+	(Threads): index entries, clarifications, example
+	(passim): minor typos fixed, phrasing improvements
+
+	* remote.texi (Bootstrapping): rephrase text on ^C and add index
+	entries; (Server): explain use of gdbserver w/real-time systems,
+	add example of conflicting TCP port; (MIPS Remote) break up
+	running text into table, highlighting commands, and add example.
+	
+Wed Nov 24 14:15:56 1993  Roland H. Pesch  (pesch@fowanton.cygnus.com)
+
+	* refcard.tex: avoid bad linebreaks even when REFEDITS=psrc.sed
+
 Fri Nov 12 16:10:58 1993  Jim Kingdon  (kingdon@lioth.cygnus.com)
 
 	* stabs.texinfo (Nested Symbols): New node.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 49bd76a..7eb6c5b 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -209,19 +209,16 @@ effects of one bug and go on to learn about another.
 
 @ifclear CONLY
 You can use @value{GDBN} to debug programs written in C or C++.  For
-more information, @xref{C}.
+more information, see @ref{C,,C and C++}.
 
 @ifset MOD2
-@c I use "MOD2" as a "miscellaneous languages" flag here.  According to
-@c a comment in all-cfg.texi, there should be separate flags for chill
-@c and Pascal, but that seems kind of silly since we only mention them
-@c in passing--IMHO the manual should be configurable as little as we
-@c can get away with -kingdon.
+@c "MOD2" used as a "miscellaneous languages" flag here.
+@c This is acceptable while there is no real doc for Chill and Pascal.
 Support for Modula-2 and Chill is partial.  For information on Modula-2,
-@xref{Modula-2}; there is no further documentation on Chill yet.
+see @ref{Modula-2,,Modula-2}; there is no further documentation on Chill yet.
 
-Pascal programs which use sets, subranges, file variables, or nested
-functions will not currently work.  @value{GDBN} does not support
+Debugging pascal programs which use sets, subranges, file variables, or nested
+functions does not currently work.  @value{GDBN} does not support
 entering expressions, printing values, etc. using Pascal syntax.
 @end ifset
 @ifset FORTRAN
@@ -418,6 +415,9 @@ of your program, and the latter refer to the state of GDB itself.
 GDB 4 can debug programs and core files that use SunOS, SVR4, or IBM RS/6000
 shared libraries.
 
+@item Threads
+On some systems, GDB 4 has facilities to debug multi-thread programs.
+
 @item Reference Card
 GDB 4 has a reference card.  @xref{Formatting Documentation,,Formatting
 the Documentation}, for instructions about how to print it.
@@ -1828,7 +1828,7 @@ address space (that is, they can all examine and modify the same
 variables).  On the other hand, each thread has its own registers and
 execution stack, and perhaps private memory.
 
-@value{GDBN} provides several facilities for debugging multi-thread
+@value{GDBN} provides these facilities for debugging multi-thread
 programs:
 
 @itemize @bullet
@@ -1870,10 +1870,10 @@ program information from the perspective of the current thread.
 @c included GDB's numeric thread handle, so you could just go to that
 @c thread without first checking `info threads'.
 Whenever @value{GDBN} detects a new thread in your program, it displays
-the system's identification for it with a message in the form @samp{[New
-@var{systag}]}.  @var{systag} is a thread identifier whose form varies
-depending on the particular system.  For example, on LynxOS, you might
-see
+the target system's identification for the thread with a message in the
+form @samp{[New @var{systag}]}.  @var{systag} is a thread identifier
+whose form varies depending on the particular system.  For example, on
+LynxOS, you might see
 
 @example
 [New process 35 thread 27]
@@ -1904,9 +1904,9 @@ Display a summary of all threads currently in your
 program.  @value{GDBN} displays for each thread (in this order):
 
 @enumerate
-@item the @value{GDBN} thread number
+@item the thread number assigned by @value{GDBN}
 
-@item the system's @var{systag} thread identifier
+@item the target system's thread identifier (@var{systag})
 
 @item the current stack frame summary for that thread
 @end enumerate
@@ -1929,6 +1929,7 @@ For example,
 
 @table @code
 @item thread @var{threadno}
+@kindex thread @var{threadno}
 Make thread number @var{threadno} the current thread.  The command
 argument @var{threadno} is the internal @value{GDBN} thread number, as
 shown in the first field of the @samp{info threads} display.
@@ -1960,6 +1961,9 @@ thread.
 @xref{Thread Stops,,Stopping and starting multi-thread programs}, for
 more information about how @value{GDBN} behaves when you stop and start
 programs with multiple threads.
+
+@xref{Set Watchpoints,,Setting watchpoints}, for information about
+watchpoints in programs with multiple threads.
 @end ifclear
 
 @node Stopping
@@ -3045,23 +3049,28 @@ programs with multiple threads}), you can choose whether to set
 breakpoints on all threads, or on a particular thread.
 
 @table @code
-@cindex br
+@cindex breakpoints and threads
+@cindex thread breakpoints
 @kindex break @dots{} thread @var{threadno}
 @item break @var{linespec} thread @var{threadno}
 @itemx break @var{linespec} thread @var{threadno} if @dots{}
 Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
 to specify that you only want @value{GDBN} to stop the program when a
-particular thread reaches this breakpoint.  @var{threadno} is one of
-GDB's numeric thread identifiers, shown in the first column of
-the @samp{info threads} display.
-
-You can use the @code{thread} qualifier on conditional breakpoints as
-well; in this case, place @samp{thread @var{threadno}} before the
-breakpoint condition.
+particular thread reaches this breakpoint.  @var{threadno} is one of the
+numeric thread identifiers assigned by @value{GDBN}, shown in the first
+column of the @samp{info threads} display.
 
 If you do not specify @samp{thread @var{threadno}} when you set a
 breakpoint, the breakpoint applies to @emph{all} threads of your
 program.
+
+You can use the @code{thread} qualifier on conditional breakpoints as
+well; in this case, place @samp{thread @var{threadno}} before the
+breakpoint condition, like this:
+
+@smallexample
+(gdb) break frik.c:13 thread 28 if bartab > lim
+@end smallexample
 @end table
 
 @cindex stopped threads
@@ -3079,11 +3088,12 @@ executing.  @emph{This is true even when single-stepping} with commands
 like @code{step} or @code{next}.  
 
 In particular, @value{GDBN} cannot single-step all threads in lockstep.
-Since thread scheduling is up to your host operating system, rather than
-controlled by @value{GDBN}, other threads may execute more than one
-statement while the current thread completes a single step.
-Moreover, in general other threads stop in the middle of a statement,
-rather than at a clean statement boundary, when the program stops.
+Since thread scheduling is up to your debugging target's operating
+system (not controlled by @value{GDBN}), other threads may
+execute more than one statement while the current thread completes a
+single step.  Moreover, in general other threads stop in the middle of a
+statement, rather than at a clean statement boundary, when the program
+stops.
 
 You might even find your program stopped in another thread after
 continuing or even single-stepping.  This happens whenever some other
@@ -5242,14 +5252,15 @@ together.
 @kindex g++
 @cindex GNU C++
 The C++ debugging facilities are jointly implemented by the GNU C++
-compiler and @value{GDBN}.  Therefore, to debug your C++ code effectively,
-you must compile your C++ programs with the GNU C++ compiler,
-@code{g++}.  Also, you must be using the stabs debugging format; see the
-documentation for the GNU C++ compiler for more information on how to
-select that format.
-
-In particular, cfront based compilers such as Sun's C++ are not fully
-supported.
+compiler and @value{GDBN}.  Therefore, to debug your C++ code
+effectively, you must compile your C++ programs with the GNU C++
+compiler, @code{g++}.
+
+For best results when debugging C++ programs, use the stabs debugging
+format.  You can select that format explicitly with the @code{g++}
+command-line options @samp{-gstabs} or @samp{-gstabs+}.  See
+@ref{Debugging Options,,Options for Debugging Your Program or GNU CC,
+gcc.info, Using GNU CC}, for more information.
 @end ifclear
 @ifset CONLY
 @node C
@@ -6821,9 +6832,10 @@ target is @dots{}}''
 @end ifset
 
 The file is loaded at whatever address is specified in the executable.
-For some object file formats, like a.out, the object file format fixes
-the address and so it won't necessarily match the address you gave to
-the linker.
+For some object file formats, you can specify the load address when you
+link the program; for other formats, like a.out, the object file format
+specifies a fixed address.
+@c FIXME! This would be a good place for an xref to the GNU linker doc.
 
 @ifset VXWORKS
 On VxWorks, @code{load} will dynamically link @var{filename} on the
diff --git a/gdb/doc/remote.texi b/gdb/doc/remote.texi
index a1a75de..26611a8 100644
--- a/gdb/doc/remote.texi
+++ b/gdb/doc/remote.texi
@@ -168,14 +168,18 @@ It may be identical to @code{putchar} for your target system; a
 different name is used to allow you to distinguish the two if you wish.
 @end table
 
+@cindex control C, and remote debugging
+@cindex interrupting remote targets
 If you want @value{GDBN} to be able to stop your program while it is
 running, you need to use an interrupt-driven serial driver, and arrange
-for it to stop when it receives a control C character (getting it to
-return the proper status to GDB probably requires changes to the
-standard stub; one quick and dirty way is to just execute a breakpoint
-instruction.  @value{GDBN} will return a SIGTRAP instead of a SIGINT).
-That is the character which @value{GDBN} uses to tell the remote system
-to stop.
+for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
+character).  That is the character which @value{GDBN} uses to tell the
+remote system to stop.
+
+Getting the debugging target to return the proper status to @value{GDBN}
+probably requires changes to the standard stub; one quick and dirty way
+is to just execute a breakpoint instruction (the ``dirty'' part is that
+@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
 
 Other routines you need to supply are:
 
@@ -444,19 +448,24 @@ that @value{GDBN} itself does.  In fact, a system that can run
 because it is a much smaller program than @value{GDBN} itself.  It is
 also easier to port than all of @value{GDBN}, so you may be able to get
 started more quickly on a new system by using @code{gdbserver}.
+Finally, if you develop code for real-time systems, you may find that
+the tradeoffs involved in real-time operation make it more convenient to
+do as much development work as possible on another system, for example
+by cross-compiling.  You can use @code{gdbserver} to make a similar
+choice for debugging.
 
 @value{GDBN} and @code{gdbserver} communicate via either a serial line
 or a TCP connection, using the standard @value{GDBN} remote serial
 protocol.
 
 @table @emph
-@item On the target,
+@item On the target machine,
 you need to have a copy of the program you want to debug.
 @code{gdbserver} does not need your program's symbol table, so you can
 strip the program if necessary to save space.  @value{GDBN} on the host
 system does all the symbol handling.
 
-To use the server, you must tell it how to communicate with @value{GDB};
+To use the server, you must tell it how to communicate with @value{GDBN};
 the name of your program; and the arguments for your program.  The
 syntax is:
 
@@ -465,7 +474,7 @@ target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
 @end smallexample
 
 @var{comm} is either a device name (to use a serial line) or a TCP
-hostname and portnumber.  For example, to debug emacs with the argument
+hostname and portnumber.  For example, to debug Emacs with the argument
 @samp{foo.txt} and communicate with @value{GDBN} over the serial port
 @file{/dev/com1}:
 
@@ -488,20 +497,22 @@ TCP.  The @samp{host:2345} argument means that @code{gdbserver} is to
 expect a TCP connection from machine @samp{host} to local TCP port 2345.
 (Currently, the @samp{host} part is ignored.)  You can choose any number
 you want for the port number as long as it does not conflict with any
-TCP ports already in use on the target system.@footnote{If you choose a
-port number that conflicts with another service, @code{gdbserver} prints
-an error message and exits.} You must use the same port number with the
-host @value{GDBN} @code{target remote} command.
-
-@item On the host,
-you need an unstripped copy of your program, since
-@value{GDBN} needs symbols and debugging information.  Start up
-@value{GDBN} as usual, using the name of the local copy of your program
-as the first argument.  (You may also need the
-@samp{--baud} option if the serial line is running at anything other than 9600 bps.)
-After that, use @code{target remote} to establish communications with @code{gdbserver}.  Its argument is either
-a device name (usually a serial device, like @file{/dev/ttyb}), or a TCP
-port descriptof in the form @code{@var{host}:@var{PORT}}.  For example:
+TCP ports already in use on the target system (for example, @code{23} is
+reserved for @code{telnet}).@footnote{If you choose a port number that
+conflicts with another service, @code{gdbserver} prints an error message
+and exits.} You must use the same port number with the host @value{GDBN}
+@code{target remote} command.
+
+@item On the @value{GDBN} host machine,
+you need an unstripped copy of your program, since @value{GDBN} needs
+symbols and debugging information.  Start up @value{GDBN} as usual,
+using the name of the local copy of your program as the first argument.
+(You may also need the @w{@samp{--baud}} option if the serial line is
+running at anything other than 9600 bps.)  After that, use @code{target
+remote} to establish communications with @code{gdbserver}.  Its argument
+is either a device name (usually a serial device, like
+@file{/dev/ttyb}), or a TCP port descriptor in the form
+@code{@var{host}:@var{PORT}}.  For example:
 
 @smallexample
 (@value{GDBP}) target remote /dev/ttyb
@@ -515,7 +526,7 @@ communicates with the server via serial line @file{/dev/ttyb}, and
 @end smallexample
 
 @noindent
-communicates via a TCP connection to port 2345 on host @file{the-target}.
+communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
 For TCP connections, you must start up @code{gdbserver} prior to using
 the @code{target remote} command.  Otherwise you may get an error whose
 text depends on the host system, but which usually looks something like
@@ -1177,6 +1188,11 @@ development board as a ``normal exit'' of your program.
 MIPS board attached to a serial line.  This is available when
 you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
 
+@noindent
+Use these @value{GDBN} commands to specify the connection to your target board:
+
+@table @code
+@item target mips @var{port}
 @kindex target mips @var{port}
 To run a program on the board, start up @code{@value{GDBP}} with the
 name of your program as the argument.  To connect to the board, use the
@@ -1185,19 +1201,62 @@ the serial port connected to the board.  If the program has not already
 been downloaded to the board, you may use the @code{load} command to
 download it.  You can then use all the usual @value{GDBN} commands.
 
-You can also specify @var{port} as a TCP connection (for instance, to a
-serial line managed by a terminal concentrator), using the syntax
-@code{@var{hostname}:@var{portnumber}}.
+For example, this sequence connects to the target board through a serial
+port, and loads and runs a program called @var{prog} through the
+debugger:
+
+@example
+host$ @value{GDBP} @var{prog}
+GDB is free software and @dots{}
+(gdb) target mips /dev/ttyb
+(gdb) load @var{prog}
+(gdb) run
+@end example
+
+@item target mips @var{hostname}:@var{portnumber}
+On some @value{GDBN} host configurations, you can specify a TCP
+connection (for instance, to a serial line managed by a terminal
+concentrator) instead of a serial port, using the syntax
+@samp{@var{hostname}:@var{portnumber}}.
+@end table
+
+@noindent
+@value{GDBN} also supports these special commands for MIPS targets:
 
+@table @code
+@item set mipsfpu off
+@itemx show mipsfpu
+@kindex set mipsfpu off
+@kindex show mipsfpu
+@cindex MIPS remote floating point
+@cindex floating point, MIPS remote
+If your target board does not support the MIPS floating point
+coprocessor, you should use the command @samp{set mipsfpu off} (if you
+need this, you may wish to put the command in your @value{GDBINIT}
+file).  This tells @value{GDBN} how to find the return value of
+functions which return floating point values.  It also allows
+@value{GDBN} to avoid saving the floating point registers when calling
+functions on the board.  (As usual, you can inquire about the
+@code{mipsfpu} variable with @samp{show mipsfpu}.)
+
+@item set remotedebug @var{n}
+@itemx show remotedebug
+@kindex set remotedebug
+@kindex show remotedebug
 @cindex @code{remotedebug}, MIPS protocol
+@cindex MIPS @code{remotedebug} protocol
 @c FIXME! For this to be useful, you must know something about the MIPS
 @c FIXME...protocol.  Where is it described?
 You can see some debugging information about communications with the board
-by setting the @code{remotedebug} variable.  If you set it to 1 using
-@samp{set remotedebug 1} every packet will be displayed.  If you set it
-to 2 every character will be displayed.  You can check the current value
+by setting the @code{remotedebug} variable.  If you set it to @code{1} using
+@samp{set remotedebug 1}, every packet is displayed.  If you set it
+to @code{2}, every character is displayed.  You can check the current value
 at any time with the command @samp{show remotedebug}.
 
+@item set timeout @var{seconds}
+@itemx set retransmit-timeout @var{seconds}
+@itemx show timeout
+@itemx show retransmit-timeout
 @cindex @code{timeout}, MIPS protocol
 @cindex @code{retransmit-timeout}, MIPS protocol
 @kindex set timeout
@@ -1212,16 +1271,7 @@ retransmit-timeout @var{seconds}} command.  The default is 3 seconds.
 You can inspect both values with @code{show timeout} and @code{show
 retransmit-timeout}.  (These commands are @emph{only} available when
 @value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
-
-@kindex set mipsfpu off
-@cindex MIPS remote floating point
-@cindex floating point, MIPS remote
-If your target board does not support the MIPS floating point
-coprocessor, you should use the command @samp{set mipsfpu off} (you may
-wish to put this in your @value{GDBINIT} file).  This tells @value{GDBN}
-how to find the return value of functions which return floating point
-values.  It also allows @value{GDBN} to avoid saving the floating point
-registers when calling functions on the board.
+@end table
 @end ifset
 
 @ifset SIMS