General editing pass. Highlights:

Update stuff on option flags, full text, mention -help;
Better localization of target-specific stuff;
introduce 'path' command and discussion of exec path as opp src path;
document which commands don't repeat w RTN;
update and improve several examples, eg deleting (...)
Throughout: attempts to clarify etc.

1 files changed, 559 insertions, 424 deletions

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 9882beb..738c9b2 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -77,9 +77,9 @@ _fi__(!_GENERIC__)
 @c Maybe crank this up to "Fourth Edition" when released at FSF
 @c @subtitle Third Edition---_GDBN__ version 4.0
 @subtitle _GDBN__ version 4.0
-@subtitle January 1991
+@subtitle April 1991
 @author{Richard M. Stallman}
-@author{Roland H. Pesch (Cygnus Support)}
+@author{Roland H. Pesch --- Cygnus Support}
 @page
 
 @tex
@@ -281,24 +281,26 @@ subroutine, the program runs as usual---it filters standard input.
 @var{changequote(<,>)}
 
 Breakpoint 1, m4_changequote (argc=3, argv=0x2b958) at builtin.c:812
-812         if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3))
+812     if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3))
 @end smallexample
 @noindent
 To trigger the breakpoint, we called @code{changequote}.  _GDBN__
 suspended execution of @code{m4}, displaying information about the
 context where it stopped.
 
+@group
 @smallexample
 (_GDBP__) @var{s}
 bad_argc (name=0xf851cfb4<Address 0xf851cfb4 out of bounds>, argc=3,
     min=1, max=3) at builtin.c:230
-230         if (min > 0 && argc < min) @{
+230     if (min > 0 && argc < min) @{
 @end smallexample
 @noindent
 We've used the command @samp{s} (@code{step}) to advance execution to
 the next source line; since there was a subroutine call, we've stopped
 in the first line of that subroutine, not in the next line of
 @code{m4_changequote}.
+@end group
 
 The command @samp{next} would have taken us to the next line of
 @code{m4_changequote}.  To see where we are in the stack, we can use the
@@ -326,7 +328,7 @@ Run till exit from #0  bad_argc (name=0xf851cfb4<Address 0xf851cfb4 out
  of bounds>, 
     argc=3, min=1, max=3) at builtin.c:230
 0x59ec in m4_changequote (argc=3, argv=0x2b958) at builtin.c:812
-812         if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3))
+812     if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3))
 Value returned is $1 = false
 @end smallexample
 
@@ -342,8 +344,7 @@ again will get us to the next line of @code{m4_changequote}.
 
 @smallexample
 (_GDBP__) @var{s}
-815         lquote = (argc >= 2) ? TOKEN_DATA_TEXT(argv[1])[0] : DEF_LQ
-UOTE;
+815     lquote = (argc >= 2) ? TOKEN_DATA_TEXT(argv[1])[0] : DEF_LQUOTE;
 (_GDBP__) @var{whatis lquote}
 type = char
 (_GDBP__) @var{p lquote}
@@ -359,21 +360,18 @@ command.
 
 @smallexample
 (_GDBP__) @var{l}
-810         token_data **argv;
+810     token_data **argv;
 811     @{
-812         if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3))
-813             return;
+812     if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3))
+813     return;
 814     
-815         lquote = (argc >= 2) ? TOKEN_DATA_TEXT(argv[1])[0] : DEF_LQ
-UOTE;
-816         rquote = (argc >= 3) ? TOKEN_DATA_TEXT(argv[2])[0] : DEF_RQ
-UOTE;
+815     lquote = (argc >= 2) ? TOKEN_DATA_TEXT(argv[1])[0] : DEF_LQUOTE;
+816     rquote = (argc >= 3) ? TOKEN_DATA_TEXT(argv[2])[0] : DEF_RQUOTE;
 817     @}
 818     
 819     /* 
 (_GDBP__) @var{s}
-816         rquote = (argc >= 3) ? TOKEN_DATA_TEXT(argv[2])[0] : DEF_RQ
-UOTE;
+816     rquote = (argc >= 3) ? TOKEN_DATA_TEXT(argv[2])[0] : DEF_RQUOTE;
 (_GDBP__) @var{s}
 817     @}
 (_GDBP__) @var{p lquote}
@@ -416,8 +414,8 @@ the _GDBN__ @samp{quit} command.
 @node Starting _GDBN__,,,
 @section Starting _GDBN__
 
-_GDBN__ is invoked with the shell command @samp{_GDBP__}.  Once started, it reads
-commands from the terminal until you tell it to exit.
+_GDBN__ is invoked with the shell command @samp{_GDBP__}.  Once started,
+it reads commands from the terminal until you tell it to exit.
 
 You can start by just calling @samp{_GDBP__} with no arguments or
 options; but the most usual way to start _GDBN__ is with one argument or
@@ -426,15 +424,23 @@ two, specifying an executable program as the argument:
 _GDBP__ program
 @end example
 @noindent
-or you can start with both an executable program and a core file specified:
+You can also start with both an executable program and a core file specified:
 @example
 _GDBP__ program core
 @end example
 
-You can get more detailed control over how _GDBN__ starts up using some of
-the command-line options.
+You can further control how _GDBN__ starts up by using command-line
+options.
+
+_GDBN__ itself can remind you of the options available:
+@example
+gdb -help
+@end example
+@noindent
+will display all available options and briefly describe their use
+(@samp{gdb -h} is a shorter equivalent).
 
-All the options and command line arguments given are processed
+All options and command line arguments you give are processed
 in sequential order.  The order makes a difference when the
 @samp{-x} option is used.  
 
@@ -444,13 +450,16 @@ in sequential order.  The order makes a difference when the
 As shown above, any arguments other than options specify an executable
 file and core file; that is, the first argument encountered with no
 associated option flag is equivalent to a @samp{-se} option, and the
-second, if any, is equivalent to a @samp{-c} option.
+second, if any, is equivalent to a @samp{-c} option.  Many options have
+both long and short forms; both are shown here.
 
 @table @code
-@item -s @var{file}
+@item -symbols @var{file}
+@itemx -s @var{file}
 Read symbol table from file @var{file}.
 
-@item -e @var{file}
+@item -exec @var{file}
+@itemx -e @var{file}
 Use file @var{file} as the executable file to execute when
 appropriate, and for examining pure data in conjunction with a core
 dump.
@@ -459,13 +468,16 @@ dump.
 Read symbol table from file @var{file} and use it as the executable
 file.
 
-@item -c @var{file}
+@item -core @var{file}
+@itemx -c @var{file}
 Use file @var{file} as a core dump to examine.
 
-@item -x @var{file}
+@item -command @var{file}
+@itemx -x @var{file}
 Execute _GDBN__ commands from file @var{file}.  @xref{Command Files}.
 
-@item -d @var{directory}
+@item -directory @var{directory}
+@itemx -d @var{directory}
 Add @var{directory} to the path to search for source files.
 @end table
 
@@ -474,12 +486,14 @@ Add @var{directory} to the path to search for source files.
 
 @table @code
 @item -nx
-Do not execute commands from the init files @file{_GDBINIT__}.
+@itemx -n
+Do not execute commands from any @file{_GDBINIT__} initialization files.
 Normally, the commands in these files are executed after all the
 command options and arguments have been processed.  @xref{Command
 Files}.
 
-@item -q
+@item -quiet
+@itemx -q
 ``Quiet''.  Do not print the introductory and copyright messages.  These
 messages are also suppressed in batch mode, or if an executable file name is
 specified on the _GDBN__ command line.
@@ -500,7 +514,12 @@ Program exited normally.
 (which is ordinarily issued whenever a program running under _GDBN__ control
 terminates) is not issued when running in batch mode.
 
+@item -cd @var{directory}
+Run _GDBN__ using @var{directory} as its working directory,
+instead of the current directory.
+
 @item -fullname
+@itemx -f
 This option is used when Emacs runs _GDBN__ as a subprocess.  It tells _GDBN__
 to output the full file name and line number in a standard,
 recognizable fashion each time a stack frame is displayed (which
@@ -513,6 +532,9 @@ a signal to display the source code for the frame.
 @item -b @var{bps}
 Set the line speed (baud rate or bps) of any serial interface used by
 _GDBN__ for remote debugging.
+
+@item -tty @var{device}
+Run using @code{device} for your program's standard input and output.
 @end table
 
 _if__(_I960__)
@@ -571,8 +593,8 @@ target architecture.
 
 @quotation
 @emph{Warning:} if you specify @samp{-O}, but are actually trying to
-connect to a target system using the current protocol, the connection
-will fail appearing to be a speed mismatch, and _GDBN__ will repeatedly
+connect to a target system that expects the newer protocol, the connection
+will fail, appearing to be a speed mismatch.  _GDBN__ will repeatedly
 attempt to reconnect at several different line speeds.  You can abort
 this process with an interrupt.
 @end quotation
@@ -580,8 +602,6 @@ this process with an interrupt.
 @item -brk
 Specify that _GDBN__ should first send a @samp{BREAK} signal to the target
 system, in an attempt to reset it, before connecting to a Nindy target.
-This option is only available when _GDBN__ is configured for the Intel 960
-target architecture.
 
 @quotation
 @emph{Warning:} Many target systems do not have the hardware that this
@@ -592,6 +612,19 @@ requires; it only works with a few boards.
 
 The standard @samp{-b} option controls the line speed used on the serial
 port. 
+
+@group
+@node Nindy reset,,,
+@subsubsection Nindy Reset Command
+@table @code
+@item reset
+@kindex reset
+For a Nindy target, this command sends a ``break'' to the remote target
+system; this is only useful if the target has been equipped with a
+circuit to perform a hard reset (or some other interesting action) when
+a break is detected.
+@end table
+@end group
 _fi__(_I960__)
 
 _if__(_AMD29K__)
@@ -631,7 +664,7 @@ _1__@end example
 @noindent
 (Later, if you wish to return control to the DOS console, you can use
 the command @samp{CTTY con}---but you must send it over the device that
-had control, in our example over the @samp{com1} serial line).
+had control, in our example over the @samp{COM1} serial line).
 
 From the Unix host, use a communications program such as @code{tip} or
 @code{cu} to communicate with the PC; for example,
@@ -647,7 +680,7 @@ tip -9600 /dev/ttya
 @end example
 @noindent
 Your system may define a different name where our example uses
-@samp{/dev/ttya} (the argument to @code{tip}).  The communications
+@samp{/dev/ttya} as the argument to @code{tip}.  The communications
 parameters, including what port to use, are associated with the
 @code{tip} argument in the ``remote'' descriptions file---normally the
 system table @file{/etc/remote}.
@@ -664,10 +697,10 @@ Using the @samp{tip} or @samp{cu} connection, change the DOS working
 directory to the directory containing a copy of your 29K program, then
 start the PC program @samp{EBMON} (an EB29K control program supplied
 with your board by AMD).  You should see an initial display from
-@code{EBMON} similar to the one in our example, ending with the
+@code{EBMON} similar to the one that follows, ending with the
 @code{EBMON} prompt @samp{#}---
 _0__@example
-C:\> g:
+C:\> G:
 
 G:\> CD \usr\joe\work29k
 
@@ -731,7 +764,7 @@ target amd-eb /dev/ttya 9600 MYFOO
 In this example, we've assumed your program is in a file called
 @samp{myfoo}.  Note that the filename given as the last argument to
 @samp{target amd-eb} should be the name of the program as it appears to DOS.
-In our example it is simply @samp{MYFOO}, but in general it can include
+In our example this is simply @samp{MYFOO}, but in general it can include
 a DOS path, and depending on your transfer mechanism may not resemble
 the name on the Unix side.
 
@@ -759,7 +792,7 @@ The @samp{target amd-eb} command creates a file @file{eb.log} in the
 current working directory, to help debug problems with the connection.
 @file{eb.log} records all the output from @code{EBMON}, including echoes
 of the commands sent to it.  Running @samp{tail -f} on this file in
-another window often helps to debug trouble with @code{EBMON}, or
+another window often helps to understand trouble with @code{EBMON}, or
 unexpected events on the PC side of the connection.
 _fi__(_AMD29K__)
 
@@ -780,7 +813,7 @@ debugging is enabled in the VxWorks configuration.
 Defining @code{INCLUDE_RDB} in the VxWorks configuration file
 @code{configAll.h} includes the RDB interface routines and spawns the
 source debugging task @code{tRdbTask} when VxWorks is booted.  For more
-information on configuring and remaking VxWorks, @cite{VxWorks
+information on configuring and remaking VxWorks, see the @cite{VxWorks
 Programmer's Guide}.
 
 Once you have included the RDB interface in your VxWorks system image
@@ -815,20 +848,21 @@ Attaching remote machine across net... Success!
 
 _GDBN__ will then attempt to read the symbol tables of any object
 modules loaded into the VxWorks target since it was last booted.
-_GDBN__ will locate the object files by searching the directories listed
-in the source path (@pxref{Source Path}); if it fails to find an object
-file, it will display a message such as:
+_GDBN__ locates these files by searching the directories listed in the
+command search path (@pxref{Command Path}); if it fails to find an
+object file, it will display a message such as:
 
 @smallexample
 prog.o: No such file or directory.
 @end smallexample
 
-This will cause the @samp{target} command to abort.  When this happens, you
-should add the appropriate directory to the source path and execute the
-@samp{target} command again.
+This will cause the @samp{target} command to abort.  When this happens,
+you should add the appropriate directory to the search path, with the
+_GDBN__ command @samp{path}, and execute the @samp{target} command
+again.
 
 @node VxWorks download,,,
-@subsubsection Downloading to VxWorks
+@subsubsection VxWorks Download
 
 If you have connected to the VxWorks target and you want to debug an
 object that has not yet been loaded, you can use the _GDBN__ @samp{load}
@@ -870,7 +904,7 @@ table.)
 @node VxWorks attach,,,
 @subsubsection Running Tasks
 
-You can also attach to an existing task using the attach command as
+You can also attach to an existing task using the @samp{attach} command as
 follows:
 
 @smallexample
@@ -883,8 +917,8 @@ the time of attachment.
 
 _fi__(_VXWORKS__)
 
-@node Stopping _GDBN__,,,
-@section Stopping _GDBN__
+@node Leaving _GDBN__,,,
+@section Leaving _GDBN__
 @cindex exiting _GDBN__
 @kindex quit
 To exit _GDBN__, use the @samp{quit} command (abbreviated @samp{q}), or type
@@ -903,7 +937,7 @@ you can release it with the @samp{detach} command; @pxref{Attach}.
 @node Shell Commands,,,
 @section Shell Commands
 If you just need to execute occasional shell commands during your
-debugging session, there's no need to stop or suspend _GDBN__; you can
+debugging session, there's no need to leave or suspend _GDBN__; you can
 just use the @samp{shell} command.
 
 @table @code
@@ -919,11 +953,11 @@ The utility @samp{make} is often needed in development environments.
 You don't have to use the @samp{shell} command for this purpose in _GDBN__:
 
 @table @code
-@item make @dots{}
+@item make @var{make-args}
 @kindex make
 @cindex calling make
 Causes _GDBN__ to execute an inferior @code{make} program with the specified
-arguments.  This is equivalent to @samp{shell make @dots{}}.
+arguments.  This is equivalent to @samp{shell make @var{make-args}}.
 @end table
 
 @node Commands,,,
@@ -941,17 +975,20 @@ no arguments.  Some command names do not allow any arguments.
 @cindex abbreviation
 _GDBN__ command names may always be truncated if that abbreviation is
 unambiguous.  Other possible command abbreviations are listed in the
-documentation of the individual commands.  Sometimes even ambiguous
+documentation for individual commands.  Sometimes even ambiguous
 abbreviations are allowed; for example, @samp{s} is specially defined as
 equivalent to @samp{step} even though there are other commands whose
 names start with @samp{s}.
 
 @cindex repeating commands
 A blank line as input to _GDBN__ means to repeat the previous command.
-Certain commands will not repeat this way; these are commands for which
-unintentional repetition might cause trouble and which you are unlikely
-to want to repeat.  Certain others (@samp{list} and @samp{x}) act
-differently when repeated because that is more useful.
+Certain commands (for example, @samp{run}) will not repeat this way;
+these are commands for which unintentional repetition might cause
+trouble and which you are unlikely to want to repeat.
+
+The @samp{list} and @samp{x} commands construct new arguments when
+repeated, rather than repeating exactly as typed, to permit easy
+scanning of source or memory.
 
 @kindex #
 @cindex comment
@@ -994,7 +1031,7 @@ Command name abbreviations are allowed if unambiguous.
 Using one of the general help categories as an argument, you can get a
 list of the individual commands in a category.  For example, here is the
 help display for category @samp{status}:
-@example
+@smallexample
 (_GDBP__) help status
 Status inquiries.
 
@@ -1006,7 +1043,7 @@ info -- Generic command for printing status
 Type "help" followed by command name for full documentation.
 Command name abbreviations are allowed if unambiguous.
 (_GDBP__) 
-@end example
+@end smallexample
 
 @item help @var{command}
 With a command name as @samp{help} argument, _GDBN__ will display a
@@ -1036,7 +1073,7 @@ In contrast, @samp{show} is for describing the state of _GDBN__ itself.
 You can change most of the things you can @code{show}, by using the
 related command @samp{set}; for example, you can control what number
 system is used for displays with @samp{set radix}, or simply inquire
-which possibility is currently in use with @samp{show radix}.  
+which is currently in use with @samp{show radix}.  
 
 @kindex info set
 To display all the settable parameters and their current
@@ -1050,15 +1087,15 @@ values, you can use @samp{show} with no arguments; you may also use
 @kindex show version
 @item show version
 @c FIXME: chgd to "show version" from "info".  Verify John doing same to GDBv4.
-This @samp{show} subcommand is one of those with no corresponding
-@samp{set} subcommand.  As _GDBN__ evolves, new commands are introduced,
-and old ones may wither away.  If multiple versions of _GDBN__ are in
-use at your site, it may occasionally be useful to make sure what
-version of _GDBN__ you're running.  It is also useful to include this
-information in _GDBN__ bug-reports.  _GDBN__ announces its version
-number if you start it with no arguments; but you can make it give this
-information on request, with the @samp{show version} command.
+Show what version of _GDBN__ is running.  You should include this
+information in _GDBN__ bug-reports.  If multiple versions of _GDBN__ are
+in use at your site, you may occasionally want to make sure what version
+of _GDBN__ you're running; as _GDBN__ evolves, new commands are
+introduced, and old ones may wither away.  The version number is also
+announced when you start _GDBN__ with no arguments.
 
+This @samp{show} subcommand is one of those with no corresponding
+@samp{set} subcommand.
 @end table
 
 @node Running,,,
@@ -1067,18 +1104,18 @@ information on request, with the @samp{show version} command.
 @node Compilation,,,
 @section Compiling for Debugging
 
-In order to debug a program effectively, you need to ask for debugging
-information when you compile it.  This debugging information is stored
-in the object file; it describes the data type of each variable or
-function and the correspondence between source line numbers and
-addresses in the executable code.
+In order to debug a program most effectively, you need to generate
+debugging information when you compile it.  This debugging information
+is stored in the object file; it describes the data type of each
+variable or function and the correspondence between source line numbers
+and addresses in the executable code.
 
 To request debugging information, specify the @samp{-g} option when you run
 the compiler.
 
-The Unix C compiler is unable to handle the @samp{-g} and @samp{-O} options
-together.  This means that you cannot ask for optimization if you ask for
-debugger information.
+Many C compilers are unable to handle the @samp{-g} and @samp{-O}
+options together.  Using those compilers, you cannot generate optimized
+executables containing debugging information.
 
 The GNU C compiler supports @samp{-g} with or without @samp{-O}, making it
 possible to debug optimized code.  We recommend that you @emph{always} use
@@ -1088,7 +1125,7 @@ correct, but there's no sense in pushing your luck.
 Some things do not work as well with @samp{-g -O} as with just
 @samp{-g}, particularly on machines with instruction scheduling.  If in
 doubt, recompile with @samp{-g} alone, and if this fixes the problem,
-please report it as a bug (including a test case---@pxref{_GDBN__ Bugs}).
+please report it as a bug (including a test case!).
 
 Older versions of the GNU C compiler permitted a variant option
 @samp{-gg} for debugging information.  _GDBN__ no longer supports this
@@ -1118,25 +1155,24 @@ option or use shorter file names.  Alternatively, use a version of GNU
 @kindex run
 To start your program under _GDBN__, use the @samp{run} command.  
 _if__(_VXWORKS__)
-Except on VxWorks, the 
+Except on VxWorks, you
 _fi__(_VXWORKS__)
 _if__(!_VXWORKS__)
-The
+You
 _fi__(!_VXWORKS__)
-program must already have been specified using the
-@samp{file} or @samp{exec-file} command, or with an argument to _GDBN__
-(@pxref{Files}).@refill
+must first specify the program name with an argument to _GDBN__
+(@pxref{Invocation}), or using the @samp{file} or @samp{exec-file}
+command (@pxref{Files}).@refill
 
 On targets that support processes, @samp{run} creates an inferior
 process and makes that process run your program.  On other targets,
-@samp{run} jumps to the location it has recorded for the start of the
-program.
+@samp{run} jumps to the start of the program.
 
 The execution of a program is affected by certain information it
 receives from its superior.  _GDBN__ provides ways to specify this
 information, which you must do @i{before} starting the program.  (You
-can change it after starting the program, but such changes do not affect
-the program unless you start it over again.)  This information may be
+can change it after starting the program, but such changes will only affect
+the program the next time you start it.)  This information may be
 divided into four categories:
 
 @table @asis
@@ -1181,21 +1217,22 @@ it.  In this process, it tries to retain your current breakpoints.
 @section Your Program's Arguments
 
 @cindex arguments (to your program)
-The arguments to your program are specified by the arguments of the 
+The arguments to your program can be specified by the arguments of the
 @samp{run} command.  They are passed to a shell, which expands wildcard
 characters and performs redirection of I/O, and thence to the program.
+_GDBN__ uses the shell indicated by your environment variable
+@code{SHELL} if it exists; otherwise, _GDBN__ uses @samp{/bin/sh}.
 
 @samp{run} with no arguments uses the same arguments used by the previous
-@samp{run}.
+@samp{run}, or those set by the @samp{set args} command.
 
 @kindex set args
 @table @code
 @item set args
-The command @samp{set args} can be used to specify the arguments to be used
-the next time the program is run.  If @samp{set args} has no arguments, it
-means to use no arguments the next time the program is run.  If you have
-run your program with arguments and want to run it again with no arguments,
-this is the only way to do so.
+Specify the arguments to be used the next time your program is run.  If
+@samp{set args} has no arguments, @samp{run} will execute your program
+with no arguments.  Once you have run your program with arguments, this
+is the only way to run it again without arguments.
 
 @item show args
 @kindex show args
@@ -1206,32 +1243,47 @@ Show the arguments to give your program when it is started.
 @section Your Program's Environment
 
 @cindex environment (of your program)
-The @dfn{environment} consists of a set of @dfn{environment variables} and
+The @dfn{environment} consists of a set of environment variables and
 their values.  Environment variables conventionally record such things as
 your user name, your home directory, your terminal type, and your search
 path for programs to run.  Usually you set up environment variables with
 the shell and they are inherited by all the other programs you run.  When
-debugging, it can be useful to try running the program with different
-environments without having to start the debugger over again.
+debugging, it can be useful to try running the program with a modified
+environment without having to start _GDBN__ over again.
 
 @table @code
+@item path @var{directory}
+@kindex path
+Add @var{directory} to the front of the @code{PATH} environment variable
+(the search path for executables), for both _GDBN__ and your program.
+You may specify several directory names, separated by @samp{:} or
+whitespace.  If a directory is already in the path, it is moved to the
+front, so it will be searched sooner.  You can use the string
+@samp{$cwd} to refer to the current working directory.
+
+This command will not repeat if you press @key{RET} a second time after
+using it once.
+
 @item show environment @var{varname}
 @kindex show environment
 Print the value of environment variable @var{varname} to be given to
-your program when it is started.
+your program when it starts.
 
 @item show environment
 Print the names and values of all environment variables to be given to
-your program when it is started.
+your program.
 
 @item set environment @var{varname} @var{value}
 @itemx set environment @var{varname} = @var{value}
 @kindex set environment
-Sets environment variable @var{varname} to @var{value}, for your program
-only, not for _GDBN__ itself.  @var{value} may be any string; the values of
-environment variables are just strings, and any interpretation is
-supplied by your program itself.  The @var{value} parameter is optional;
-if it is eliminated, the variable is set to a null value.
+Sets environment variable @var{varname} to @var{value}.  The value
+changes for your program only, not for _GDBN__ itself.  @var{value} may
+be any string; the values of environment variables are just strings, and
+any interpretation is supplied by your program itself.  The @var{value}
+parameter is optional; if it is eliminated, the variable is set to a
+null value.
+@c FIXME: I think "any string" here doesn't include leading, trailing
+@c FIXME... blanks. Queried J Gilmore.  ---pesch@cygnus.com, 4apr91
 
 For example, this command:
 
@@ -1240,16 +1292,15 @@ set env USER = foo
 @end example
 
 @noindent
-tells the program, when subsequently run, to assume it is being run
-on behalf of the user named @samp{foo}.
+tells a Unix program, when subsequently run, that its user is named
+@samp{foo}.
 
 @item unset environment @var{varname}
 @kindex unset environment
 Remove variable @var{varname} from the environment to be passed to your
-program.  This is different from @samp{set env @var{varname}@ =};
+program.  This is different from @samp{set env @var{varname}=};
 @samp{unset environment} removes the variable from the environment,
-rather than assigning it an empty value.  This command can be
-abbreviated @samp{d e}.
+rather than assigning it an empty value.  
 @end table
 
 @node Working Directory,,,
@@ -1285,8 +1336,8 @@ Print _GDBN__'s working directory.
 By default, the program you run under _GDBN__ does input and output to the same
 terminal that _GDBN__ uses.
 
-You can redirect the program's input and/or output using @samp{sh}-style
-redirection commands in the @samp{run} command.  For example,
+You can redirect the program's input and/or output using shell
+redirection with the @samp{run} command.  For example,
 
 _0__@example
 run > outfile
@@ -1316,7 +1367,7 @@ effect on input/output redirection, but not its effect on the
 controlling terminal.
 
 When you use the @samp{tty} command or redirect input in the @samp{run}
-command, only the @emph{input for your program} is affected.  The input
+command, only the input @emph{for your program} is affected.  The input
 for _GDBN__ still comes from your terminal.
 
 @node Attach,,,
@@ -1325,19 +1376,22 @@ for _GDBN__ still comes from your terminal.
 @cindex attach
 
 @table @code
-@item attach @var{process--id}
-This command attaches to a running process, if your currently selected
-target supports processes.  (@samp{info files} will show your active
-targets).  The command takes as argument a process ID.
-
-You specify a process ID to debug an already-running process that was
-started outside of _GDBN__.  (The usual way to find out the process-id of
+@item attach @var{process-id}
+If your currently selected target supports processes, this command
+attaches to a running process---one that was started outside _GDBN__.
+(@samp{info files} will show your active targets).  The command takes as
+argument a process ID.  The usual way to find out the process-id of
 a Unix process is with the @code{ps} utility, or with the @code{jobs -l}
-shell command.)  In this case, you must have permission to send the
-process a signal, and it must have the same effective user ID as the
-_GDBN__ process.
+shell command.   
+
+@samp{attach} will not repeat if you press @key{RET} a second time after
+executing the command.
 @end table
 
+To use @samp{attach}, you must have permission to send the process a
+signal, and it must have the same effective user ID as the _GDBN__
+process.
+
 When using @samp{attach}, you should first use the @samp{file} command
 to specify the program running in the process and load its symbol table.
 
@@ -1355,6 +1409,8 @@ When you have finished debugging the attached process, you can use the
 the process continues its execution.  After the @samp{detach} command,
 that process and _GDBN__ become completely independent once more, and you
 are ready to @samp{attach} another process or start one with @samp{run}.
+@samp{detach} will not repeat if you press @key{RET} again after using
+it once.
 
 If you exit _GDBN__ or use the @samp{run} command while you have an attached
 process, you kill that process.  By default, you will be asked for
@@ -1362,6 +1418,7 @@ confirmation if you try to do either of these things; you can control
 whether or not this happens by using the @samp{set caution} command
 (@pxref{Messages/Warnings}).
 
+@group
 @node Kill Process,,,
 @section Killing the Child Process
 
@@ -1374,6 +1431,7 @@ Kill the child process in which your program is running under _GDBN__.
 This command is useful if you wish to debug a core dump instead of a
 running process.  _GDBN__ ignores any core dump file while your program
 is running.
+@end group
 
 On some operating systems, you can't execute your program in another
 process while breakpoints are active inside _GDBN__.  You can use the
@@ -1723,7 +1781,7 @@ will not change the state of your other breakpoints).
 
 The simplest sort of breakpoint breaks every time the program reaches a
 specified place.  You can also specify a @dfn{condition} for a
-breakpoint.  A condition is just a boolean expression in your
+breakpoint.  A condition is just a Boolean expression in your
 programming language.  (@xref{Expressions}).  A breakpoint with a
 condition evaluates the expression each time the program reaches it, and
 the program stops only if the condition is true.
@@ -1782,10 +1840,8 @@ To make the breakpoint stop the next time it is reached, specify
 a count of zero.
 
 @item continue @var{count}
-@itemx cont @var{count}
 @itemx c @var{count}
 @itemx fg @var{count}
-@kindex cont @var{count}
 @kindex continue @var{count}
 Continue execution of the program, setting the ignore count of the
 breakpoint that the program stopped at to @var{count} minus one.
@@ -1793,7 +1849,7 @@ Thus, the program will not stop at this breakpoint until the
 @var{count}'th time it is reached.
 
 An argument to this command is meaningful only when the program stopped
-due to a breakpoint.  At other times, the argument to @samp{cont} is
+due to a breakpoint.  At other times, the argument to @samp{continue} is
 ignored.
 
 The synonym @samp{fg} is provided purely for convenience, and has
@@ -1804,12 +1860,12 @@ If a breakpoint has a positive ignore count and a condition, the condition
 is not checked.  Once the ignore count reaches zero, the condition will
 be checked.
 
-Note that you could achieve the effect of the ignore count with a
+You could achieve the effect of the ignore count with a
 condition such as _0__@w{@samp{$foo-- <= 0}}_1__ using a debugger convenience
 variable that is decremented each time.  @xref{Convenience Vars}.
 
 @node Break Commands,,,
-@subsection Commands Executed on Breaking
+@subsection Breakpoint Command Lists
 
 @cindex breakpoint commands
 You can give any breakpoint a series of commands to execute when the
@@ -1818,7 +1874,10 @@ print the values of certain expressions, or enable other breakpoints.
 
 @table @code
 @item commands @var{bnum}
+@itemx @dots @var{command-list} @dots
+@itemx end
 @kindex commands
+@kindex end
 Specify a list of commands for breakpoint number @var{bnum}.  The commands
 themselves appear on the following lines.  Type a line containing just
 @samp{end} to terminate the commands.
@@ -1831,8 +1890,12 @@ With no arguments, @samp{commands} refers to the last breakpoint set
 (not to the breakpoint most recently encountered).
 @end table
 
+Pressing @key{RET} as a means of repeating the last _GDBN__ command is
+disabled from the time you enter @samp{commands} to just after the
+corresponding @samp{end}. 
+
 You can use breakpoint commands to start the program up again.  Simply
-use the @samp{cont} command, or @samp{step}, or any other command to
+use the @samp{continue} command, or @samp{step}, or any other command to
 resume execution.  However, if you do this, any further commands in the
 same breakpoint's command list are ignored.  When the program stops
 again, _GDBN__ will act according to the cause of that stop.
@@ -1866,7 +1929,7 @@ One application for breakpoint commands is to correct one bug so you can
 test another.  Put a breakpoint just after the erroneous line of code, give
 it a condition to detect the case in which something erroneous has been
 done, and give it commands to assign correct values to any variables that
-need them.  End with the @samp{cont} command so that the program does not
+need them.  End with the @samp{continue} command so that the program does not
 stop, and start with the @samp{silent} command so that no output is
 produced.  Here is an example:
 
@@ -1970,12 +2033,14 @@ An argument is a repeat count, as in @samp{step}.
 @samp{next} within a function that lacks debugging information acts as does
 @samp{step}, but any function calls appearing within the code of the
 function are executed without stopping.
+@c FIXME: great; so what does *step* do within a fn that lacks debug info?
 
 @item finish
 @kindex finish
 Continue running until just after the selected stack frame returns (or
 until there is some other reason to stop, such as a fatal signal or a
-breakpoint).  Print value returned by the selected stack frame (if any).
+breakpoint).  Print the value returned by the selected stack frame (if
+any).
 
 Contrast this with the @samp{return} command (@pxref{Returning}).
 
@@ -2046,7 +2111,7 @@ it stops at that breakpoint, and then step through the suspect area,
 examining the variables that are interesting, until you see the problem
 happen.
 
-The @samp{cont} command can be used after stepping to resume execution
+The @samp{continue} command can be used after stepping to resume execution
 until the next breakpoint or signal.
 
 @node Continuing,,,
@@ -2057,19 +2122,17 @@ the bug you are looking for has not happened yet.
 
 @table @code
 @item continue
-@item cont
-@kindex cont
 @kindex continue
 Continue running the program at the place where it stopped.
 @end table
 
 If the program stopped at a breakpoint, the place to continue running
 is the address of the breakpoint.  You might expect that continuing would
-just stop at the same breakpoint immediately.  In fact, @samp{cont}
+just stop at the same breakpoint immediately.  In fact, @samp{continue}
 takes special care to prevent that from happening.  You do not need
 to delete the breakpoint to proceed through it after stopping at it.
 You can, however, specify an ignore-count for the breakpoint that the
-program stopped at, by means of an argument to the @samp{cont} command.
+program stopped at, by means of an argument to the @samp{continue} command.
 @xref{Conditions}.
 
 If the program stopped because of a signal other than @code{SIGINT} or
@@ -2090,10 +2153,11 @@ the @samp{handle} command (@pxref{Signals}).
 A signal is an asynchronous event that can happen in a program.  The
 operating system defines the possible kinds of signals, and gives each
 kind a name and a number.  For example, in Unix @code{SIGINT} is the
-signal a program gets when you type @kbd{Ctrl-c}; @code{SIGSEGV} is the
-signal a program gets from referencing a place in memory far away from
-all the areas in use; @code{SIGALRM} occurs when the alarm clock timer
-goes off (which happens only if the program has requested an alarm).
+signal a program gets when you type an interrupt (often @kbd{C-c});
+@code{SIGSEGV} is the signal a program gets from referencing a place in
+memory far away from all the areas in use; @code{SIGALRM} occurs when
+the alarm clock timer goes off (which happens only if the program has
+requested an alarm).
 
 @cindex fatal signals
 Some signals, including @code{SIGALRM}, are a normal part of the
@@ -2101,7 +2165,7 @@ functioning of the program.  Others, such as @code{SIGSEGV}, indicate
 errors; these signals are @dfn{fatal} (kill the program immediately) if the
 program has not specified in advance some other way to handle the signal.
 @code{SIGINT} does not indicate an error in the program, but it is normally
-fatal so it can carry out the purpose of @kbd{Ctrl-c}: to kill the program.
+fatal so it can carry out the purpose of the interrupt: to kill the program.
 
 _GDBN__ has the ability to detect any occurrence of a signal in the program
 running under _GDBN__'s control.  You can tell _GDBN__ in advance what to do for
@@ -2186,6 +2250,7 @@ stack}.
 When your program stops, the _GDBN__ commands for examining the stack allow you
 to see all of this information.
 
+@cindex selected frame
 One of the stack frames is @dfn{selected} by _GDBN__ and many _GDBN__ commands
 refer implicitly to the selected frame.  In particular, whenever you ask
 _GDBN__ for the value of a variable in the program, the value is found in the
@@ -2234,15 +2299,9 @@ and so on upward.  These numbers do not really exist in your program;
 they are assigned by _GDBN__ to give you a way of designating stack
 frames in _GDBN__ commands.
 
-@cindex selected frame
-Many _GDBN__ commands refer implicitly to one stack frame, called the
-@dfn{selected} stack frame.  You can select any frame using one set of
-_GDBN__ commands, and then other commands will operate on that frame.  When
-your program stops, _GDBN__ automatically selects the innermost frame.
-
 @cindex frameless execution
 Some compilers allow functions to be compiled so that they operate
-without stack frames.  (For example, the _GCC__ option
+without stack frames.  (For example, the @code{_GCC__} option
 @samp{-fomit-frame-pointer} will generate functions without a frame.)
 This is occasionally done with heavily used library functions to save
 the frame setup time.  _GDBN__ has limited facilities for dealing with
@@ -2285,34 +2344,28 @@ Similar, but print only the outermost @var{n} frames.
 The names @samp{where} and @samp{info stack} are additional aliases
 for @samp{backtrace}.
 
-Each line in the backtrace shows the frame number and the function
-name.  The program counter value is also shown---unless you use
-@samp{set addressprint off}.
-
-If the function is in a source file whose symbol table data has been
-fully read, the backtrace shows the source file name and line number, as
-well as the arguments to the function.  When the line number is shown,
-the program counter value is omitted if it is at the beginning of the
-code for that line number.
+Each line in the backtrace shows the frame number and the function name.
+The program counter value is also shown---unless you use @samp{set
+addressprint off}.  The backtrace also shows the source file name and
+line number, as well as the arguments to the function.  The program
+counter value is omitted if it is at the beginning of the code for that
+line number.
 
 Here is an example of a backtrace.  It was made with the command
 @samp{bt 3}, so it shows the innermost three frames.
 
-@example
-#0  rtx_equal_p (x=(rtx) 0x8e58c, y=(rtx) 0x1086c4) \
-(/gp/rms/cc/rtlanal.c line 337)
-#1  0x246b0 in expand_call (...) (...)
-#2  0x21cfc in expand_expr (...) (...)
+@smallexample
+#0  m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) at builtin.c:993
+#1  0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
+#2  0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
+    at macro.c:71
 (More stack frames follow...)
-@end example
+@end smallexample
 
 @noindent
-_GDBN__ displayed the functions @code{expand_call} and @code{expand_expr}
-with place-holders in place of their argument values and line numbers,
-because each is in a file whose symbol details have not been fully read.
-Full detail is available for the function @code{rtx_equal_p}, which is
-in the file @file{rtlanal.c}.  Its arguments, named @code{x} and
-@code{y}, are shown with their typed values.
+The display for frame @code{#0} doesn't begin with a program counter
+value, indicating that the program has stopped at the beginning of the
+code for line @code{993} of @code{builtin.c}.
 
 @node Selection,,,
 @section Selecting a Frame
@@ -2324,13 +2377,16 @@ of the stack frame just selected.
 
 @table @code
 @item frame @var{n}
+@itemx f @var{n}
 @kindex frame
+@kindex f
 Select frame number @var{n}.  Recall that frame zero is the innermost
 (currently executing) frame, frame one is the frame that called the
 innermost one, and so on.  The highest-numbered frame is @code{main}'s
 frame.
 
 @item frame @var{addr}
+@itemx f @var{addr}
 Select the frame at address @var{addr}.  This is useful mainly if the
 chaining of stack frames has been damaged by a bug, making it
 impossible for _GDBN__ to assign numbers properly to all frames.  In
@@ -2385,6 +2441,7 @@ stack frame.
 
 @table @code
 @item frame
+@itemx f
 When used without any argument, this command does not change which frame
 is selected, but prints a brief description of the currently
 selected stack frame.  It can be abbreviated @samp{f}.  With an
@@ -2430,13 +2487,17 @@ exception handlers, visit the associated frame (using the @samp{up},
 @node Source,,,
 @chapter Examining Source Files
 
-_GDBN__ knows which source files your program was compiled from, and
-can print parts of their text.  When your program stops, _GDBN__
-spontaneously prints the line it stopped in.  Likewise, when you
+_GDBN__ can print parts of your program's source, since the debugging
+information recorded in your program tells _GDBN__ what source files
+were used to built it.  When your program stops, _GDBN__
+spontaneously prints the line where it stopped.  Likewise, when you
 select a stack frame (@pxref{Selection}), _GDBN__ prints the line
-which execution in that frame has stopped in.  You can also
+where execution in that frame has stopped.  You can also
 print parts of source files by explicit command.
 
+If you use _GDBN__ through its GNU Emacs interface, you may prefer to
+use Emacs facilities to view source; @pxref{Emacs}.
+
 @node List,,,
 @section Printing Source Lines
 
@@ -2508,8 +2569,8 @@ Here are the ways of specifying a single source line---all the
 kinds of linespec.
 
 @table @code
-@item @var{linenum}
-Specifies line @var{linenum} of the current source file.
+@item @var{number}
+Specifies line @var{number} of the current source file.
 When a @samp{list} command has two linespecs, this refers to
 the same source file as the first linespec.
 
@@ -2522,18 +2583,19 @@ first linespec.
 @item -@var{offset}
 Specifies the line @var{offset} lines before the last line printed.
 
-@item @var{filename}:@var{linenum}
-Specifies line @var{linenum} in the source file @var{filename}.
+@item @var{filename}:@var{number}
+Specifies line @var{number} in the source file @var{filename}.
 
 @item @var{function}
+@c FIXME: "of the open-brace" is C-centric.  When we add other langs...
 Specifies the line of the open-brace that begins the body of the
 function @var{function}.
 
 @item @var{filename}:@var{function}
 Specifies the line of the open-brace that begins the body of the
-function @var{function} in the file @var{filename}.  The file name is
-needed with a function name only for disambiguation of identically
-named functions in different source files.
+function @var{function} in the file @var{filename}.  You only need the
+file name with a function name to avoid ambiguity when there are
+identically named functions in different source files.
 
 @item *@var{address}
 Specifies the line containing the program address @var{address}.
@@ -2558,7 +2620,7 @@ as @samp{fo}.  The synonym @samp{search @var{regexp}} is also supported.
 The command @samp{reverse-search @var{regexp}} checks each line, starting
 with the one before the last line listed and going backward, for a match
 for @var{regexp}.  It lists the line that is found.  You can abbreviate
-this command with as little as @samp{rev}.
+this command as @samp{rev}.
 
 @node Source Path,,,
 @section Specifying Source Directories
@@ -2568,7 +2630,7 @@ this command with as little as @samp{rev}.
 Executable programs sometimes do not record the directories of the source
 files from which they were compiled, just the names.  Even when they do,
 the directories could be moved between the compilation and your debugging
-session.  _GDBN__ remembers a list of directories to search for source files;
+session.  _GDBN__ has a list of directories to search for source files;
 this is called the @dfn{source path}.  Each time _GDBN__ wants a source file,
 it tries all the directories in the list, in the order they are present
 in the list, until it finds a file with the desired name.  Note that
@@ -2576,10 +2638,11 @@ the executable search path is @emph{not} used for this purpose.  Neither is
 the current working directory, unless it happens to be in the source
 path.
 
-If it can't find a source file in the source path, and the object program
-records what directory it was compiled in, _GDBN__ tries that directory too.
-If the source path is empty, and there is no record of the compilation
-directory, _GDBN__ will, as a last resort, look in the current directory.
+If _GDBN__ can't find a source file in the source path, and the object
+program records a directory, _GDBN__ tries that directory too.  If the
+source path is empty, and there is no record of the compilation
+directory, _GDBN__ will, as a last resort, look in the current
+directory.
 
 Whenever you reset or rearrange the source path, _GDBN__ will clear out
 any information it has cached about where source files are found, where
@@ -2590,15 +2653,20 @@ When you start _GDBN__, its source path is empty.
 To add other directories, use the @samp{directory} command.
 
 @table @code
-@item directory @var{dirnames...}
+@item directory @var{dirname} @dots
 Add directory @var{dirname} to the front of the source path.  Several
-directory names may be given to this command, separated by whitespace or
-@samp{:}.  If a name is already in the source path, it is moved to the
-front of the path, so it will be searched sooner.
+directory names may be given to this command, separated by @samp{:} or
+whitespace.  You may specify a directory that is already in the source
+path; this moves it forward, so it will be searched sooner.  You can use
+the string @samp{$cwd} to refer to the current working directory, and
+@samp{$cdir} to refer to the compilation directory (if one is recorded).
 
 @item directory
 Reset the source path to empty again.  This requires confirmation.
 
+The @samp{directory} command will not repeat if you press @key{RET} a
+second time after executing it once.
+
 @item info directories
 @kindex info directories
 Print the source path: show which directories it contains.
@@ -2631,11 +2699,11 @@ Print the starting and ending addresses of the compiled code for
 source line @var{linespec}.
 
 @kindex $_
-The default examine address for the @samp{x} command is changed to the
-starting address of the line, so that @samp{x/i} is sufficient to
-begin examining the machine code (@pxref{Memory}).  Also, this address
-is saved as the value of the convenience variable @code{$_}
-(@pxref{Convenience Vars}).
+After @samp{info line}, the default address for the @samp{x}
+command is changed to the starting address of the line, so that
+@samp{x/i} is sufficient to begin examining the machine code
+(@pxref{Memory}).  Also, this address is saved as the value of the
+convenience variable @code{$_} (@pxref{Convenience Vars}).
 
 @kindex disassemble
 @kindex disasm
@@ -2677,19 +2745,19 @@ type.
 
 A more low-level way of examining data is with the @samp{x} command.
 It examines data in memory at a specified address and prints it in a
-specified format.
+specified format.  @xref{Memory}.
 
 @node Expressions,,,
 @section Expressions
 
 @cindex expressions
-Many different _GDBN__ commands accept an expression and compute its value.
-Any kind of constant, variable or operator defined by the programming
-language you are using is legal in an expression in _GDBN__.  This includes
-conditional expressions, function calls, casts and string constants.  It
-unfortunately does not include symbols defined by preprocessor
-@code{#define} commands, or C++ expressions involving @samp{::}, the
-name resolution operator.
+@code{print} and many other _GDBN__ commands accept an expression and
+compute its value.  Any kind of constant, variable or operator defined
+by the programming language you are using is legal in an expression in
+_GDBN__.  This includes conditional expressions, function calls, casts
+and string constants.  It unfortunately does not include symbols defined
+by preprocessor @code{#define} commands, or C++ expressions involving
+@samp{::}, the name resolution operator.
 @c FIXME: actually C++ a::b works except in obscure circumstances where it
 @c FIXME...can conflict with GDB's own name scope resolution.
 
@@ -2707,12 +2775,12 @@ languages:
 
 @item ::
 @samp{::} allows you to specify a variable in terms of the file or
-function it is defined in.  @xref{Variables}.
+function where it is defined.  @xref{Variables}.
 
 @item @{@var{type}@} @var{addr}
 Refers to an object of type @var{type} stored at address @var{addr} in
 memory.  @var{addr} may be any expression whose value is an integer or
-pointer (but parentheses are required around nonunary operators, just as in
+pointer (but parentheses are required around binary operators, just as in
 a cast).  This construct is allowed regardless of what kind of data is
 officially supposed to reside at @var{addr}.@refill
 @end table
@@ -2746,12 +2814,12 @@ within the function @code{foo}, but the variable @code{b} is visible
 only while the program is executing inside the block in which @code{b}
 is declared.
 
-As a special exception, you can refer to a variable or function whose
+There is an exception: you can refer to a variable or function whose
 scope is a single source file even if the current execution point is not
 in this file.  But it is possible to have more than one such variable or
-function with the same name (in different source files).  In such a
-case, it is not defined which one you will get.  If you wish, you can
-specify any one of them using the colon-colon construct:
+function with the same name (in different source files).  If that happens,
+referring to that name has unpredictable effects.  If you wish, you can
+specify a variable in a particular file, using the colon-colon construct:
 
 @cindex colon-colon
 @cindex scope
@@ -2801,18 +2869,18 @@ p *array@@len
 The left operand of @samp{@@} must reside in memory.  Array values made
 with @samp{@@} in this way behave just like other arrays in terms of
 subscripting, and are coerced to pointers when used in expressions.
-(It would probably appear in an expression via the value history,
-after you had printed it out.)
+Artificial arrays most often appear in expressions via the value history
+(@pxref{Value History}), after printing one out.)
 
 @node Output formats,,,
 @section Output formats
 
 @cindex formatted output
 @cindex output formats
-_GDBN__ normally prints all values according to their data types.  Sometimes
+By default, _GDBN__ prints a value according to its data type.  Sometimes
 this is not what you want.  For example, you might want to print a number
 in hex, or a pointer in decimal.  Or you might want to view data in memory
-at a certain address as a character string or an instruction.  To do
+at a certain address as a character string or as an instruction.  To do
 these things, specify an @dfn{output format} when you print a value.
 
 The simplest use of output formats is to say how to print a value
@@ -2872,25 +2940,34 @@ expression.  For example, @samp{p/x} reprints the last value in hex.
 @cindex examining memory
 @table @code
 @kindex x
-@item x
+@item x/@var{Nuf} @var{expr}
 The command @samp{x} (for `examine') can be used to examine memory
-without reference to the program's data types.  The format in which you
-wish to examine memory is instead explicitly specified.  The allowable
-formats are a superset of the formats described in the previous section.
+without being constrained by your program's data types.  You can specify
+the unit size @var{u} of memory to inspect, and a repeat count @var{N} of how
+many of those units to display.  @samp{x} understands the formats
+@var{f} used by @samp{print}; two additional formats, @samp{s} (string)
+and @samp{i} (machine instruction) can be used without specifying a unit
+size.
 @end table
 
-@samp{x} is followed by a slash and an output format specification,
-followed by an expression for an address.  The expression need not have
-a pointer value (though it may); it is used as an integer, as the
-address of a byte of memory.  @xref{Expressions} for more information on
-expressions.  For example, @samp{x/4xw $sp} prints the four words of
-memory above the stack pointer in hexadecimal.
+For example, @samp{x/3hu 0x54320} is a request to display three halfwords
+(@code{h}) of memory, formatted as unsigned decimal integers (@code{u}),
+starting at address @code{0x54320}.  @samp{x/4wx $sp} prints the four
+words (@code{w}) of memory above the stack pointer (here, @samp{$sp};
+@pxref{Registers}) in hexadecimal (@code{x}).
 
-The output format in this case specifies both how big a unit of memory
-to examine and how to print the contents of that unit.  This is done
-with one or two of the following letters:
+Since the letters indicating unit sizes are all distinct from the
+letters specifying output formats, you don't have to remember whether
+unit size or format comes first; either order will work.  The output
+specifications @samp{4xw} and @samp{4wx} mean exactly the same thing.
 
-These letters specify the size of unit to examine:
+After the format specification, you indicate the address where _GDBN__
+is to begin reading memory for display, using an expression.  The
+expression need not have a pointer value (though it may); it is always
+interpreted as an integer address of a byte of memory.
+@xref{Expressions} for more information on expressions.  
+
+These are the memory units @var{u} you can specify with @samp{x}:
 
 @table @samp
 @item b
@@ -2914,34 +2991,12 @@ runs on.
 Examine giant words (8 bytes).
 @end table
 
-These letters specify the way to print the contents:
-
-@table @samp
-@item x
-Print as integers in unsigned hexadecimal.
-
-@item d
-Print as integers in signed decimal.
-
-@item u
-Print as integers in unsigned decimal.
-
-@item o
-Print as integers in unsigned octal.
+You can combine these unit specifications with any of the formats
+described for @samp{print}.  @xref{Output formats}.
 
-@item a
-Print as an address, both absolute in hex and then relative
-to a symbol defined as an address below it.
+@samp{x} has two additional output specifications which derive the unit
+size from the data inspected:
 
-@item c
-Print as character constants.
-
-@item f
-Print as floating point.  This works only with sizes @samp{w} and
-@samp{g}.
-@end table
-
-These letters specify both the unit size and the output format:
 @table @samp
 @item s
 Print a null-terminated string of characters.  Any explicitly specified
@@ -2956,9 +3011,9 @@ modes used.  The command @samp{disassemble} gives an alternative way of
 inspecting machine instructions.  @xref{Machine Code}.
 @end table
 
-If either the manner of printing or the size of unit fails to be specified,
-the default is to use the same one that was used last.  If you don't want
-to use any letters after the slash, you can omit the slash as well.
+If you omit either the format @var{f} or the unit size @var{u}, @samp{x}
+will use the same one that was used last.  If you don't use any letters
+after the slash, you can omit the slash as well.
 
 You can also omit the address to examine.  Then the address used is just
 after the last unit examined.  This is why string and instruction
@@ -2977,10 +3032,12 @@ specified previously (if any) is ignored, so that the repeated command
 examines the successive locations in memory rather than the same ones.
 
 You can examine several consecutive units of memory with one command by
-writing a repeat-count after the slash (before the format letters, if any).
-The repeat count must be a decimal integer.  It has the same effect as
-repeating the @samp{x} command that many times except that the output may
-be more compact with several units per line.  For example,
+writing a repeat-count after the slash (before the format letters, if
+any).  Omitting the repeat count @var{N} displays one unit of the
+appropriate size.  The repeat count must be a decimal integer.  It has
+the same effect as repeating the @samp{x} command @var{N} times except
+that the output may be more compact, with several units per line.  For
+example,
 
 @example
 x/10i $pc
@@ -2988,7 +3045,7 @@ x/10i $pc
 
 @noindent
 prints ten instructions starting with the one to be executed next in the
-selected frame.  After doing this, you could print another seven following
+selected frame.  After doing this, you could print a further seven
 instructions with
 
 @example
@@ -2996,7 +3053,7 @@ x/7
 @end example
 
 @noindent
-in which the format and address are allowed to default.
+---where the format and address are allowed to default.
 
 @kindex $_
 @kindex $__
@@ -3031,7 +3088,13 @@ The automatic display looks like this:
 @end example
 
 @noindent
-showing item numbers, expressions and their current values.
+showing item numbers, expressions and their current values.  As with
+displays you request manually using @samp{x} or @samp{print}, you can
+specify the output format you prefer; in fact, @dfn{display} decides
+whether to use @code{print} or @code{x} depending on how elaborate your
+format specification is---it uses @code{x} if you specify a unit size,
+or one of the two formats (@samp{i} and @samp{s}) that are only
+supported by @code{x}; otherwise it uses @code{print}.
 
 @table @code
 @item display @var{exp}
@@ -3039,10 +3102,13 @@ showing item numbers, expressions and their current values.
 Add the expression @var{exp} to the list of expressions to display
 each time the program stops.  @xref{Expressions}.
 
+@samp{display} will not repeat if you press @key{RET} again after using it.
+
 @item display/@var{fmt} @var{exp}
 For @var{fmt} specifying only a display format and not a size or
 count, add the expression @var{exp} to the auto-display list but
 arranges to display it each time in the specified format @var{fmt}.
+@xref{Output formats}.
 
 @item display/@var{fmt} @var{addr}
 For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
@@ -3062,6 +3128,8 @@ is a common name for the program counter; @pxref{Registers}).
 @kindex undisplay
 Remove item numbers @var{dnums} from the list of expressions to display.
 
+@samp{undisplay} will not repeat if you press @key{RET} after using it.
+
 @item disable display @var{dnums}@dots{}
 @kindex disable display
 Disable the display of item numbers @var{dnums}.  A disabled display
@@ -3102,8 +3170,8 @@ display expression once again.
 
 @cindex format options
 @cindex print settings
-_GDBN__ provides a few ways to control how arrays, structures, and symbols are
-printed.  
+_GDBN__ provides the following ways to control how arrays, structures,
+and symbols are printed.
 
 @table @code
 @item set array-max @var{number-of-elements}
@@ -3251,9 +3319,9 @@ $1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@}
 @noindent
 and with @samp{set unionprint off} in effect it would print
 
-@example
+@smallexample
 $1 = @{it = Tree, form = @{...@}@}
-@end example
+@end smallexample
 @end table
 
 @node Value History,,,
@@ -3276,7 +3344,7 @@ the history number assigned to a value by printing @samp{$@var{num} = }
 before the value; here @var{num} is the history number.
 
 To refer to any previous value, use @samp{$} followed by the value's
-history number.  The output printed by @samp{print} is designed to
+history number.  The way @samp{print} labels its output is designed to
 remind you of this.  Just @code{$} refers to the most recent value in
 the history, and @code{$$} refers to the value before that.
 @code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2}
@@ -3378,7 +3446,7 @@ a field from successive elements of an array of structures:
 _0__@example
 set $i = 0
 print bar[$i++]->contents
-@i{@dots{}repeat that command by typing @key{RET}.}
+@i{@dots{} repeat that command by typing @key{RET}.}
 _1__@end example
 
 Some convenience variables are created automatically by _GDBN__ and given
@@ -3446,7 +3514,7 @@ frame will make no difference.
 @table @code
 @item info registers
 @kindex info registers
-Print the names and relativized values of all registers.
+Print the names and values of all registers (in the selected stack frame).
 
 @item info registers @var{regname}
 Print the relativized value of register @var{regname}.  @var{regname}
@@ -3487,9 +3555,11 @@ off the stack, regardless of machine architecture, use @samp{return};
 
 The commands described in this section allow you to inquire about the
 symbols (names of variables, functions and types) defined in your
-program.  This information is found by _GDBN__ in the symbol table loaded by
-the @samp{symbol-file} command; it is inherent in the text of your
-program and does not change as the program executes.
+program.  This information is inherent in the text of your program and
+does not change as the program executes.  _GDBN__ finds it in your
+program's symbol table, as indicated when you started _GDBN__ 
+(@pxref{File Options}), or by one of the file-management commands
+(@pxref{Files}).
 
 @table @code
 @item info address @var{symbol}
@@ -3521,12 +3591,24 @@ the name of a type, or for C code it may have the form
 @samp{enum @var{enum-tag}}.@refill
 
 @item ptype @var{exp}
-Print a description of the type of expression @var{exp}.  This is like
-@samp{whatis} except it prints a detailed description, instead of just
-the name of the type.  For example, if the type of a variable is
-@samp{struct complex @{double real; double imag;@}}, @samp{whatis} will
-print @samp{struct complex} and @samp{ptype} will print @samp{struct
-complex @{double real; double imag;@}}
+Print a description of the type of expression @var{exp}.  @samp{ptype}
+differs from @samp{whatis} by printing a detailed description, instead of just
+the name of the type.  For example, if your program declares a variable
+as
+@example
+struct complex {double real; double imag;} v;
+@end example
+@noindent
+compare the output of the two commands:
+@example
+(_GDBP__) whatis v
+type = struct complex
+(_GDBP__) ptype v
+type = struct complex {
+    double real;
+    double imag;
+}
+@end example
 
 @item info sources
 @kindex info sources
@@ -3614,7 +3696,7 @@ If you are not interested in seeing the value of the assignment, use the
 @samp{set} command instead of the @samp{print} command.  @samp{set} is
 really the same as @samp{print} except that the expression's value is not
 printed and is not put in the value history (@pxref{Value History}).  The
-expression is evaluated only for side effects.
+expression is evaluated only for its effects.
 
 If the beginning of the argument string of the @samp{set} command
 appears identical to a @samp{set} subcommand, use the @samp{set
@@ -3645,13 +3727,13 @@ stores the value 4 into that memory location.
 @section Continuing at a Different Address
 
 Ordinarily, when you continue the program, you do so at the place where
-it stopped, with the @samp{cont} command.  You can instead continue at
+it stopped, with the @samp{continue} command.  You can instead continue at
 an address of your own choosing, with the following commands:
 
 @table @code
 @item jump @var{linenum}
 @kindex jump
-Resume execution at line number @var{linenum}.  Execution may stop
+Resume execution at line number @var{linenum}.  Execution will stop
 immediately if there is a breakpoint there.
 
 The @samp{jump} command does not change the current stack frame, or
@@ -3661,8 +3743,8 @@ a different function from the one currently executing, the results may
 be bizarre if the two functions expect different patterns of arguments or
 of local variables.  For this reason, the @samp{jump} command requests
 confirmation if the specified line is not in the function currently
-executing.  However, even bizarre results are predictable based on
-careful study of the machine-language code of the program.
+executing.  However, even bizarre results are predictable if you are
+well acquainted with the machine-language code of the program.
 
 @item jump *@var{address}
 Resume execution at the instruction at address @var{address}.
@@ -3678,7 +3760,7 @@ set $pc = 0x485
 @end example
 
 @noindent
-causes the next @samp{cont} command or stepping command to execute at
+causes the next @samp{continue} command or stepping command to execute at
 address 0x485, rather than at the address where the program stopped.
 @xref{Stepping}.
 
@@ -3686,6 +3768,7 @@ The most common occasion to use the @samp{jump} command is to back up,
 perhaps with more breakpoints set, over a portion of a program that has
 already executed.
 
+@group
 @node Signaling,,,
 @section Giving the Program a Signal
 
@@ -3698,9 +3781,13 @@ signal number @var{signalnum}.
 Alternatively, if @var{signalnum} is zero, continue execution without
 giving a signal.  This is useful when the program stopped on account of
 a signal and would ordinary see the signal when resumed with the
-@samp{cont} command; @samp{signal 0} causes it to resume without a
+@samp{continue} command; @samp{signal 0} causes it to resume without a
 signal.
+
+This command does not repeat when you press @key{RET} a second time
+after using it once.
 @end table
+@end group
 
 @node Returning,,,
 @section Returning from a Function
@@ -3745,9 +3832,10 @@ execute a function from your program, but without cluttering the output
 with @code{void} returned values.  The result is printed and saved in
 the value history, if it is not void.
 
-@node Files,,,
+@node GDB Files,,,
 @chapter _GDBN__'s Files
 
+@node Files,,,
 @section Commands to Specify Files
 @cindex core dump file
 @cindex symbol table
@@ -3773,9 +3861,11 @@ Use @var{filename} as the program to be debugged.  It is read for its
 symbols and for the contents of pure memory.  It is also the program
 executed when you use the @samp{run} command.  If you do not specify a
 directory and the file is not found in _GDBN__'s working directory,
+
 _GDBN__ will use the environment variable @code{PATH} as a list of
 directories to search, just as the shell does when looking for a program
-to run.
+to run.  You can change the value of this variable, for both _GDBN__ and
+your program, using the @code{path} command.
 
 @samp{file} with no argument makes _GDBN__ discard any information it
 has on both executable file and the symbol table.
@@ -3784,7 +3874,7 @@ has on both executable file and the symbol table.
 @kindex exec-file
 Specify that the program to be run (but not the symbol table) is found
 in @var{filename}.  _GDBN__ will search the environment variable @code{PATH}
-if necessary to locate the program.
+if necessary to locate the program.  
 
 @item symbol-file @var{filename}
 @kindex symbol-file
@@ -3801,6 +3891,9 @@ auto-display expressions.  This is because they may contain pointers to
 the internal data recording symbols and data types, which are part of
 the old symbol table data being discarded inside _GDBN__.
 
+@samp{symbol-file} will not repeat if you press @key{RET} again after
+executing it once.
+
 On some kinds of object files, the @samp{symbol-file} command does not
 actually read the symbol table in full right away.  Instead, it scans
 the symbol table quickly to find which source files and which symbols
@@ -3817,12 +3910,12 @@ When the symbol table is stored in COFF format, @samp{symbol-file} does
 read the symbol table data in full right away.  We haven't implemented
 the two-stage strategy for COFF yet.
 
-When _GDBN__ is configured for a particular environment, it will understand
-debugging information in whatever format is the standard generated for
-that environment; you may use either the GNU compiler _GCC__, or other
-compilers that adhere to the local conventions.  Best results are
-usually obtained from _GCC__; for example, using _GCC__ you can generate
-debugging information for optimized code.
+When _GDBN__ is configured for a particular environment, it will
+understand debugging information in whatever format is the standard
+generated for that environment; you may use either a GNU compiler, or
+other compilers that adhere to the local conventions.  Best results are
+usually obtained from GNU compilers; for example, using @code{_GCC__}
+you can generate debugging information for optimized code.
 
 @item core-file @var{filename}
 @itemx core @var{filename}
@@ -3844,9 +3937,31 @@ program is running.  To do this, use the @samp{kill} command
 
 @item load @var{filename}
 @kindex load
-This command will dynamically link @var{filename} on the current target,
-performing any necessary downloads, then add @var{filename}'s symbol
-table in the same way as the @samp{add-syms} command.
+_if__(_GENERIC__)
+Depending on what remote debugging facilities are configured into
+_GDBN__, the @samp{load} command may be available.  Where it exists, it
+is meant to make @var{filename} (an executable) available for debugging
+on the remote system---by downloading, or dynamic linking, for example.
+@samp{load} also records @var{filename}'s symbol table in _GDBN__, like
+the @samp{add-syms} command.
+
+If @samp{load} is not available on your _GDBN__, attempting to execute
+it gets the error message ``@code{You can't do that when your target is
+@dots}'' 
+_fi__(_GENERIC__)
+
+_if__(_VXWORKS__) 
+On VxWorks, @samp{load} will dynamically link @var{filename} on the
+current target system as well as adding its symbols in _GDBN__.
+_fi__(_VXWORKS__)
+
+_if__(_I960__)
+With the Nindy interface to an Intel 960 board, @samp{load} will
+download @var{filename} to the 960 as well as adding its symbols in
+_GDBN__. 
+_fi__(_I960__)
+
+@samp{load} will not repeat if you press @key{RET} again after using it.
 
 @item add-syms @var{filename} @var{address}
 @kindex add-syms
@@ -3860,8 +3975,10 @@ file has been loaded; _GDBN__ cannot figure this out for itself.
 The symbol table of the file @var{filename} is added to the symbol table
 originally read with the @samp{symbol-file} command.  You can use the
 @samp{add-syms} command any number of times; the new symbol data thus
-read keeps adding to the old.  The @samp{symbol-file} command forgets
-all the symbol data _GDBN__ has read.
+read keeps adding to the old.  To discard all old symbol data instead,
+use the @samp{symbol-file} command. 
+
+@samp{add-syms} will not repeat if you press @key{RET} after using it.
 
 @item info files
 @itemx info target
@@ -3887,7 +4004,7 @@ name and remembers it that way.
 
 _GDBN__ supports the SunOS shared library format.  Symbols from a shared
 library cannot be referenced before the shared library has been linked
-with the program.  (That is to say, after you type @samp{run} and 
+with the program.  (That is to say, until after you type @samp{run} and 
 the function @code{main} has been entered; or when examining core
 files.)  Once the shared library has been linked in, you can use the
 following commands:
@@ -3896,7 +4013,7 @@ following commands:
 @item sharedlibrary @var{regex}
 @itemx share @var{regex}
 Load shared object library symbols for files matching a UNIX regular
-expression.
+expression.  
 
 @item share
 @itemx sharedlibrary
@@ -3909,7 +4026,11 @@ Load symbols for all shared libraries.
 Print the names of the shared libraries which are currently loaded.
 @end table
 
-@section Errors Reading Symbols
+@samp{sharedlibrary} does not repeat automatically when you press
+@key{RET} after using it once.
+
+@node Symbol Errors,,,
+@section Errors Reading Symbol Files
 While a symbol file is being read, _GDBN__ will occasionally encounter
 problems, such as symbol types it does not recognize, or known bugs in
 compiler output.  By default, it prints one message about each such
@@ -3926,55 +4047,64 @@ The messages currently printed, and their meanings, are:
 The symbol information shows where symbol scopes begin and end
 (such as at the start of a function or a block of statements).  This
 error indicates that an inner scope block is not fully contained
-in its outer scope blocks.  _GDBN__ circumvents the problem by treating
-the inner block as if it had the same scope as the outer block.
-@var{symbol} may be ``(don't know)'' if the outer block is not
-a function.
+in its outer scope blocks.  
+
+_GDBN__ circumvents the problem by treating the inner block as if it had
+the same scope as the outer block.  In the error message, @var{symbol}
+may be shown as ``@code{(don't know)}'' if the outer block is not a
+function.
 
 @item block at @var{address} out of order
 
 The symbol information for symbol scope blocks should occur in 
 order of increasing addresses.  This error indicates that it does not
-do so.  _GDBN__ does not circumvent this problem, and will have trouble
-locating symbols in the source file whose symbols being read.  (You
-can often determine what source file is affected by specifying
-@samp{set verbose on}.  @xref{Messages/Warnings}.)
+do so.  
+
+_GDBN__ does not circumvent this problem, and will have trouble locating
+symbols in the source file whose symbols being read.  (You can often
+determine what source file is affected by specifying @samp{set verbose
+on}.  @xref{Messages/Warnings}.)
 
 @item bad block start address patched
 
 The symbol information for a symbol scope block has a start address
 smaller than the address of the preceding source line.  This is known
-to occur in the SunOS 4.1.1 (and earlier) C compiler.  _GDBN__ circumvents
-the problem by treating the symbol scope block as starting on the
-previous source line.
-
-@comment @item{encountered DBX-style class variable debugging information.
-@comment You seem to have compiled your program with "g++ -g0" instead of "g++ -g".
-@comment Therefore _GDBN__ will not know about your class variables}
-@comment 
-@comment This error indicates that the symbol information produced for a C++
-@comment program includes zero-size fields, which indicated static fields in
-@comment a previous release of the G++ compiler.  This message is probably
-@comment obsolete.
-@comment
+to occur in the SunOS 4.1.1 (and earlier) C compiler.  
+
+_GDBN__ circumvents the problem by treating the symbol scope block as
+starting on the previous source line.
+
+@c @item{encountered DBX-style class variable debugging information.
+@c You seem to have compiled your program with "g++ -g0" instead of "g++ -g".
+@c Therefore _GDBN__ will not know about your class variables}
+@c 
+@c This error indicates that the symbol information produced for a C++
+@c program includes zero-size fields, which indicated static fields in
+@c a previous release of the G++ compiler.  This message is probably
+@c obsolete.
+@c
 @item bad string table offset in symbol @var{n}
 
 @cindex foo
 Symbol number @var{n} contains a pointer into the string table which is
-larger than the size of the string table.  _GDBN__ circumvents the problem
-by considering the symbol to have the name @code{foo}, which may cause
-other problems if many symbols end up with this name.  
+larger than the size of the string table.  
+
+_GDBN__ circumvents the problem by considering the symbol to have the
+name @code{foo}, which may cause other problems if many symbols end up
+with this name.
 
-@item unknown symbol type @code{0xNN}
+@item unknown symbol type @code{0x@var{NN}}
 
 The symbol information contains new data types that _GDBN__ does not yet
-know how to read.  @code{0xNN} is the symbol type of the misunderstood
-information, in hexadecimal.  _GDBN__ circumvents the error by ignoring
-this symbol information.  This will usually allow the program to be
-debugged, though certain symbols will not be accessible.  If you
-encounter such a problem and feel like debugging it, you can debug _GDBP__
-with itself, breakpoint on "complain", then go "up" to
-read_dbx_symtab() and examine *bufp to see the symbol.
+know how to read.  @code{0x@var{NN}} is the symbol type of the misunderstood
+information, in hexadecimal.  
+
+_GDBN__ circumvents the error by ignoring this symbol information.  This
+will usually allow the program to be debugged, though certain symbols
+will not be accessible.  If you encounter such a problem and feel like
+debugging it, you can debug @code{_GDBP__} with itself, breakpoint on
+@samp{complain}, then go up to the function @samp{read_dbx_symtab} and
+examine @code{*bufp} to see the symbol.
 
 @c @item stub type has NULL name
 @c 
@@ -4019,7 +4149,7 @@ allows you to (for example) start a process and inspect its activity
 without abandoning your work on a core file.
 
 More than one target can potentially respond to a request.  In
-particular, when you access memory _GDBN__ will walk down the three strata of
+particular, when you access memory _GDBN__ will examine the three strata of
 targets until it finds a target that can handle that particular address.
 
 Strata are always examined in a fixed order: first a process if there is
@@ -4041,8 +4171,7 @@ choosing a particular running process as a new target. @xref{Attach}.
 Connects the _GDBN__ host environment to a target machine or process.  A
 target is typically a protocol for talking to debugging facilities.  You
 use the argument @var{type} to specify the type or protocol of the
-target machine; for example, @samp{target vxworks} for a TCP/IP link to
-a VxWorks system.
+target machine.
 
 Further @var{parameters} are interpreted by the target protocol, but
 typically include things like device names or host names to connect
@@ -4055,6 +4184,9 @@ with, process numbers, and baud rates.  Executing
 (without any parameters) will issue a message about what
 parameters are required for that target type.
 
+The @samp{target} command will not repeat if you press @key{RET} again
+after executing the command.
+
 @item info targets
 @kindex info targets
 Displays the names of all targets available.  Beware: the similar
@@ -4063,7 +4195,7 @@ all available ones.  @samp{info files} gives the same information as
 @samp{info target} (@pxref{Files}).
 @end table
 
-Here are some common targets (available, or not, depending on _GDBN__
+Here are some common targets (available, or not, depending on the _GDBN__
 configuration):
 
 @table @code
@@ -4079,9 +4211,9 @@ A core dump file.  @samp{target core @var{filename}} is the same as
 
 @item target remote @var{dev}
 @kindex target remote
-Remote serial target in _GDBP__-specific protocol.  The argument @var{dev}
+Remote serial target in _GDBN__-specific protocol.  The argument @var{dev}
 specifies what serial device to use for the connection (e.g.
-@code{/dev/ttya}).
+@code{/dev/ttya}). @xref{Remote}.
 
 _if__(_AMD29K__)
 @item target amd-eb @var{dev} @var{speed} @var{PROG}
@@ -4099,7 +4231,7 @@ _if__(_I960__)
 @kindex target nindy
 An Intel 960 board controlled by a Nindy Monitor.  @var{devicename} is
 the name of the serial device to use for the connection, e.g.
-@samp{/dev/ttya}.  
+@samp{/dev/ttya}.  @xref{i960-Nindy Remote}.
 
 _fi__(_I960__)
 _if__(_VXWORKS__)
@@ -4107,7 +4239,7 @@ _if__(_VXWORKS__)
 @kindex target vxworks
 A VxWorks system, attached via TCP/IP.  The argument @var{machinename}
 is the target system's machine name or IP address.
-
+@xref{VxWorks Remote}.
 _fi__(_VXWORKS__)
 @end table
 
@@ -4124,18 +4256,21 @@ If you are trying to debug a program running on a machine that can't run
 _GDBN__ in the usual way, it is often useful to use remote debugging.  For
 example, you might be debugging an operating system kernel, or debugging
 a small system which does not have a general purpose operating system
-powerful enough to run a full-featured debugger.  Currently _GDBN__ supports
-remote debugging over a serial connection, and (using Sun RPC) over a
-TCP/IP connection.
+powerful enough to run a full-featured debugger.  
+
+Some configurations of _GDBN__ have special serial or TCP/IP interfaces
+to make this work with particular debugging targets.  In addition,
+_GDBN__ comes with a generic serial protocol (specific to _GDBN__, but
+not specific to any particular target system) which you can adapt.
 
-The program to be debugged on the remote machine needs to contain a
-debugging device driver which talks to _GDBN__ over the serial line.  The
-same version of _GDBN__ that is used ordinarily can be used for this.
-Several sample remote debugging drivers are distributed with _GDBN__; see
-the @file{README} file in the _GDBN__ distribution for more information.
+To use the _GDBN__ remote serial protocol, the program to be debugged on
+the remote machine needs to contain a debugging device driver which
+talks to _GDBN__ over the serial line.  Several sample remote debugging
+drivers are distributed with _GDBN__; see the @file{README} file in the
+_GDBN__ distribution for more information.
 
-For details of the communication protocol, see the comments in the _GDBN__
-source file @file{remote.c}.
+For details of this communication protocol, see the comments in the
+_GDBN__ source file @file{remote.c}.
 
 To start remote debugging, first run _GDBN__ and specify as an executable file
 the program that is running in the remote machine.  This tells _GDBN__ how
@@ -4157,32 +4292,25 @@ step and continue the remote program.
 To resume the remote program and stop debugging it, use the @samp{detach}
 command.
 
-Other remote targets be available in your
+Other remote targets may be available in your
 configuration of _GDBN__; use @samp{info targets} to list them.  
 
-@table @code
-@item reset
-@kindex reset
-For a target attached through a serial line, this command sends a
-``break'' to the remote target system; this is only useful if the target
-has been equipped with a circuit to perform a hard reset (or some other
-interesting action) when a break is detected.
-@end table
-
 @node Controlling _GDBN__,,,
 @chapter Controlling _GDBN__
 
 You can alter many aspects of _GDBN__'s interaction with you by using
-the @samp{set} command.
+the @samp{set} command.  For commands controlling how _GDBN__ displays
+data, @pxref{Print Settings}; other settings are described here.
 
 @node Prompt,,,
 @section Prompt
 @cindex prompt
 _GDBN__ indicates its readiness to read a command by printing a string
-called the @dfn{prompt}.  This string is normally @samp{(_GDBP__)}.  You can
-change the prompt string with the @samp{set prompt} command.  For
-instance, when debugging _GDBN__ with _GDBN__, it is useful to change the prompt
-in one of the _GDBN__<>s so that you tell which one you are talking to.
+called the @dfn{prompt}.  This string is normally @samp{(_GDBP__)}.  You
+can change the prompt string with the @samp{set prompt} command.  For
+instance, when debugging _GDBN__ with _GDBN__, it is useful to change
+the prompt in one of the _GDBN__<>s so that you tell which one you are
+talking to.
 
 @table @code
 @item set prompt @var{newprompt}
@@ -4233,7 +4361,7 @@ the file from which _GDBN__ will read an initial command history
 list or to which it will write this list when it exits.  This list is
 accessed through history expansion or through the history
 command editing characters listed below.  This file defaults to the
-value of the environmental variable @code{GDBHISTFILE}, or to
+value of the environment variable @code{GDBHISTFILE}, or to
 @file{./.gdb_history} if this variable is not set.
 
 @cindex history write
@@ -4250,7 +4378,7 @@ Stop recording command history in a file.
 @kindex set history size
 @item set history size @var{size}
 Set the number of commands which _GDBN__ will keep in its history list.
-This defaults to the value of the environmental variable
+This defaults to the value of the environment variable
 @code{HISTSIZE}, or to 256 if this variable is not set.
 @end table
 
@@ -4286,6 +4414,7 @@ or @samp{vi} may wish to read it.
 @xref{Command Line Editing}.
 @end iftex
 
+@group
 @kindex show history
 @item show history
 @itemx show history file
@@ -4294,6 +4423,7 @@ or @samp{vi} may wish to read it.
 @itemx show history expansion
 These commands display the state of the _GDBN__ history parameters.
 @samp{show history} by itself displays all four states.
+@end group
 
 @end table
 
@@ -4314,19 +4444,19 @@ Print ten commands just after the commands last printed.
 @section Screen Size
 @cindex size of screen
 @cindex pauses in output
-Certain commands to _GDBN__ may produce large amounts of information output
-to the screen.  To help you read all of it, _GDBN__ pauses and asks you for
-input at the end of each page of output.  Type @key{RET} when you want
-to continue the output.  Normally _GDBN__ knows the size of the screen from
-the termcap data base together with the value of the @code{TERM}
-environment variable and the @code{stty rows} and @code{stty cols}
-settings. If this is not correct, you can override it with
-the @samp{set screen-height} and @samp{set screen-width} commands:
-
-_GDBN__ also uses the screen width setting to determine when to wrap lines
-of output.  Depending what is being printed, it tries to break the
-line at a readable place, rather than simply letting it overflow onto
-the following line.
+Certain commands to _GDBN__ may produce large amounts of information
+output to the screen.  To help you read all of it, _GDBN__ pauses and
+asks you for input at the end of each page of output.  Type @key{RET}
+when you want to continue the output.  _GDBN__ also uses the screen
+width setting to determine when to wrap lines of output.  Depending on
+what is being printed, it tries to break the line at a readable place,
+rather than simply letting it overflow onto the following line.
+
+Normally _GDBN__ knows the size of the screen from the termcap data base
+together with the value of the @code{TERM} environment variable and the
+@code{stty rows} and @code{stty cols} settings. If this is not correct,
+you can override it with the @samp{set screen-height} and @samp{set
+screen-width} commands:
 
 @table @code
 @item set screen-height @var{lpp}
@@ -4417,7 +4547,7 @@ By default, if _GDBN__ encounters bugs in the symbol table of an object file,
 it prints a single message about each type of problem it finds, then 
 shuts up.  You can suppress these messages, or allow more than one such
 message to be printed if you want to see how frequent the problems are.
-@xref{Files}.
+@xref{Symbol Errors}.
 
 @table @code
 @kindex set complaints
@@ -4544,16 +4674,17 @@ when called from command files.
 @node Output,,,
 @section Commands for Controlled Output
 
-During the execution of a command file or a user-defined command, the only
-output that appears is what is explicitly printed by the commands of the
-definition.  This section describes three commands useful for generating
-exactly the output you want.
+During the execution of a command file or a user-defined command, normal
+_GDBN__ output is suppressed; the only output that appears is what is
+explicitly printed by the commands in the definition.  This section
+describes three commands useful for generating exactly the output you
+want.
 
 @table @code
 @item echo @var{text}
 @kindex echo
-@comment I don't consider backslash-space a standard C escape sequence
-@comment because it's not in ANSI.
+@c I don't consider backslash-space a standard C escape sequence
+@c because it's not in ANSI.
 Print @var{text}.  Nonprinting characters can be included in @var{text}
 using C escape sequences, such as @samp{\n} to print a newline.  @b{No
 newline will be printed unless you specify one.} In addition to the
@@ -4562,8 +4693,8 @@ space.  This is useful for outputting a string with spaces at the
 beginning or the end, since leading and trailing spaces are otherwise
 trimmed from all arguments.  Thus, to print @samp{@ and foo =@ }, use the
 command @samp{echo \@ and foo = \@ }.
-@comment FIXME: verify hard copy actually issues enspaces for '@ '!  Will this
-@comment        confuse texinfo?
+@c FIXME: verify hard copy actually issues enspaces for '@ '!  Will this
+@c        confuse texinfo?
 
 A backslash at the end of @var{text} can be used, as in C, to continue
 the command onto subsequent lines.  For example,
@@ -4590,8 +4721,9 @@ value history either.  @xref{Expressions} for more information on
 expressions. 
 
 @item output/@var{fmt} @var{expression}
-Print the value of @var{expression} in format @var{fmt}.
-@xref{Output formats}, for more information.
+Print the value of @var{expression} in format @var{fmt}.  You can use
+the same formats as for @samp{print}; @pxref{Output formats}, for more
+information.
 
 @item printf @var{string}, @var{expressions}@dots{}
 @kindex printf
@@ -4633,9 +4765,11 @@ things:
 
 @itemize @bullet
 @item
-All ``terminal'' input and output goes through the Emacs buffer.  This
-applies both to _GDBN__ commands and their output, and to the input and
-output done by the program you are debugging.
+All ``terminal'' input and output goes through the Emacs buffer.  
+@end itemize
+
+This applies both to _GDBN__ commands and their output, and to the input
+and output done by the program you are debugging.
 
 This is useful because it means that you can copy the text of previous
 commands and input them again; you can even use parts of the output
@@ -4643,31 +4777,35 @@ in this way.
 
 All the facilities of Emacs' Shell mode are available for this purpose.
 
+@itemize @bullet
 @item
-_GDBN__ displays source code through Emacs.  Each time _GDBN__ displays a
-stack frame, Emacs automatically finds the source file for that frame
-and puts an arrow (_0__@samp{=>}_1__) at the left margin of the current line.
-Emacs uses a separate buffer for source display, and splits the window
-to show both your _GDBN__ session and the source.
+_GDBN__ displays source code through Emacs.  
+@end itemize
+
+Each time _GDBN__ displays a stack frame, Emacs automatically finds the
+source file for that frame and puts an arrow (_0__@samp{=>}_1__) at the
+left margin of the current line.  Emacs uses a separate buffer for
+source display, and splits the window to show both your _GDBN__ session
+and the source.
 
 Explicit _GDBN__ @samp{list} or search commands still produce output as
 usual, but you probably will have no reason to use them.
-@end itemize
 
 @quotation
 @emph{Warning:} If the directory where your program resides is not your
 current directory, it can be easy to confuse Emacs about the location of
 the source files, in which case the auxiliary display buffer will not
 appear to show your source.  _GDBN__ can find programs by searching your
-environment's @samp{PATH} variable, so the _GDBN__ I/O session will proceed
-normally; but Emacs doesn't get enough information back from _GDBN__ to
-locate the source files in this situation.  To avoid this problem,
-either start _GDBN__ mode from the directory where your program resides, or
-specify a full path name when prompted for the @kbd{M-x gdb} argument.
+environment's @samp{PATH} variable, so the _GDBN__ input and output
+session will proceed normally; but Emacs doesn't get enough information
+back from _GDBN__ to locate the source files in this situation.  To
+avoid this problem, either start _GDBN__ mode from the directory where
+your program resides, or specify a full path name when prompted for the
+@kbd{M-x gdb} argument.
 
 A similar confusion can result if you use the _GDBN__ @samp{file} command to
 switch to debugging a program in some other location, from an existing
-_GDBN__ I/O buffer in Emacs.
+_GDBN__ buffer in Emacs.
 @end quotation
 
 By default, @kbd{M-x gdb} calls the program called ``@code{gdb}''.  If
@@ -4711,17 +4849,17 @@ Execute until exit from the selected stack frame, like the _GDBN__
 @samp{finish} command.
 
 @item M-c
-@comment C-c C-p in emacs 19
-Continue execution of the program, like the _GDBN__ @samp{cont} command.
+@c C-c C-p in emacs 19
+Continue execution of the program, like the _GDBN__ @samp{continue} command.
 
 @item M-u
-@comment C-c C-u in emacs 19
+@c C-c C-u in emacs 19
 Go up the number of frames indicated by the numeric argument
 (@pxref{Arguments, , Numeric Arguments, emacs, The GNU Emacs Manual}),
 like the _GDBN__ @samp{up} command.@refill
 
 @item M-d
-@comment C-c C-d in emacs 19
+@c C-c C-d in emacs 19
 Go down the number of frames indicated by the numeric argument, like the
 _GDBN__ @samp{down} command.
 
@@ -4758,8 +4896,8 @@ communicates with Emacs in terms of line numbers.  If you add or
 delete lines from the text, the line numbers that _GDBN__ knows will cease
 to correspond properly to the code.
 
-@comment The following dropped because Epoch is nonstandard.  Reactivate
-@comment if/when v19 does something similar. ---pesch@cygnus.com 19dec1990
+@c The following dropped because Epoch is nonstandard.  Reactivate
+@c if/when v19 does something similar. ---pesch@cygnus.com 19dec1990
 @ignore
 @kindex emacs epoch environment  
 @kindex epoch
@@ -4772,7 +4910,7 @@ each value is printed in its own window.
 @end ignore
 
 @node _GDBN__ Bugs,,,
-@comment  node-name,  next,  previous,  up
+@c  node-name,  next,  previous,  up
 @chapter Reporting Bugs in _GDBN__
 @cindex Bugs in _GDBN__
 @cindex Reporting Bugs in _GDBN__
@@ -4872,7 +5010,7 @@ the bug.  Play it safe and give a specific, complete example.  That is the
 easiest thing for you to do, and the most helpful.
 
 Keep in mind that the purpose of a bug report is to enable us to fix
-the bug if it is new to us.  It isn't very important what happens if
+the bug if it is new to us.  It isn't as important what happens if
 the bug is already known.  Therefore, always write your bug reports on
 the assumption that the bug has not been reported previously.
 
@@ -4900,10 +5038,7 @@ What compiler (and its version) was used to compile _GDBN__---e.g.
 ``_GCC__-1.37.1''.
 
 @item
-What compiler (and its version) was used to compile _GDBN__.
-
-@item
-The command arguments you gave the compiler to compile that example and
+The command arguments you gave the compiler to compile your example and
 observe the bug.  For example, did you use @samp{-O}?  To guarantee
 you won't omit something important, list them all.
 
@@ -4926,7 +5061,7 @@ Even if the problem you experience is a fatal signal, you should still
 say so explicitly.  Suppose something strange is going on, such as,
 your copy of _GDBN__ is out of synch, or you have encountered a
 bug in the C library on your system.  (This has happened!)  Your copy
-might crash and ours would not.  If you @i{told} us to expect a crash,
+might crash and ours would not.  If you told us to expect a crash,
 then when ours fails to crash, we would know that the bug was not
 happening for us.  If you had not told us to expect a crash, then we
 would not be able to draw any conclusion from our observations.
@@ -4936,7 +5071,7 @@ If you wish to suggest changes to the _GDBN__ source, send us context
 diffs.  If you even discuss something in the _GDBN__ source, refer to
 it by context, not by line number.
 
-The line numbers in our development sources don't match those in your
+The line numbers in our development sources won't match those in your
 sources.  Your line numbers would convey no useful information to us.
 
 @end itemize