Emacs section of Gdb Manual

[Nick Roberts <nick at nick dot uklinux dot net>]

Here's my patch for gdb.texinfo for the section `Using GDB under GNU Emacs'.

This is basically what I've done:

I've rewritten the paragraph on the current working directory as I don't think
Emacs does get confused (although the user might). It knows as much as GDB
about where the source files are (through the annotation) but the user might
not understand how the current working directory is set.

I've corrected/updated key bindings.

I've removed the description of  `C-x &' (send-gdb-command) as this applies
to XEmacs and not GNU Emacs.

I've added a paragraph on the speedbar.


Nick


--- gdb.texinfo.~1.164.~	2003-06-11 23:44:25.000000000 +0100
+++ gdb.texinfo	2003-06-16 23:07:54.000000000 +0100
@@ -14082,36 +14082,26 @@
 Explicit @value{GDBN} @code{list} or search commands still produce output as
 usual, but you probably have no reason to use them from Emacs.
 
-@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 does not
-appear to show your source.  @value{GDBN} can find programs by searching your
-environment's @code{PATH} variable, so the @value{GDBN} input and output
-session proceeds normally; but Emacs does not get enough information
-back from @value{GDBN} to locate the source files in this situation.  To
-avoid this problem, either start @value{GDBN} mode from the directory where
-your program resides, or specify an absolute file name when prompted for the
-@kbd{M-x gdb} argument.
-
-A similar confusion can result if you use the @value{GDBN} @code{file} command to
-switch to debugging a program in some other location, from an existing
-@value{GDBN} buffer in Emacs.
-@end quotation
-
-By default, @kbd{M-x gdb} calls the program called @file{gdb}.  If
-you need to call @value{GDBN} by a different name (for example, if you keep
-several configurations around, with different names) you can set the
-Emacs variable @code{gdb-command-name}; for example,
-
-@smallexample
-(setq gdb-command-name "mygdb")
-@end smallexample
-
-@noindent
-(preceded by @kbd{M-:} or @kbd{ESC :}, or typed in the @code{*scratch*} buffer, or
-in your @file{.emacs} file) makes Emacs call the program named
-``@code{mygdb}'' instead.
+If you specify an absolute file name when prompted for the @kbd{M-x
+gdb} argument, then Emacs sets your current working directory to where
+your program resides.  If you only specify the file name, then Emacs
+sets your current working directory to to the directory associated
+with the previous buffer.  In this case, @value{GDBN} may find your
+program by searching your environment's @code{PATH} variable, but on
+some operating systems it might not find the source.  So, although the
+@value{GDBN} input and output session proceeds normally, the auxiliary
+buffer does not display the current source and line of execution.
+
+The initial working directory of @value{GDBN} is printed on the top
+line of the @value{GDBN} I/O buffer and this serves as a default for
+the commands that specify files for @value{GDBN} to operate
+on.  @xref{Files, ,Commands to specify files}.
+
+By default, @kbd{M-x gdb} calls the program called @file{gdb}.  If you
+need to call @value{GDBN} by a different name (for example, if you
+keep several configurations around, with different names) you can
+customize the Emacs variable @code{gud-gdb-command-name} to run the
+one you want.
 
 In the @value{GDBN} I/O buffer, you can use these special Emacs commands in
 addition to the standard Shell mode commands:
@@ -14120,66 +14110,47 @@
 @item C-h m
 Describe the features of Emacs' @value{GDBN} Mode.
 
-@item M-s
+@item C-c C-s
 Execute to another source line, like the @value{GDBN} @code{step} command; also
 update the display window to show the current file and location.
 
-@item M-n
+@item C-c C-n
 Execute to next source line in this function, skipping all function
 calls, like the @value{GDBN} @code{next} command.  Then update the display window
 to show the current file and location.
 
-@item M-i
+@item C-c C-i
 Execute one instruction, like the @value{GDBN} @code{stepi} command; update
 display window accordingly.
 
-@item M-x gdb-nexti
-Execute to next instruction, using the @value{GDBN} @code{nexti} command; update
-display window accordingly.
-
 @item C-c C-f
 Execute until exit from the selected stack frame, like the @value{GDBN}
 @code{finish} command.
 
-@item M-c
+@item C-c C-r
 Continue execution of your program, like the @value{GDBN} @code{continue}
 command.
 
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-p}.
-
-@item M-u
+@item C-c <
 Go up the number of frames indicated by the numeric argument
 (@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}),
 like the @value{GDBN} @code{up} command.
 
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-u}.
-
-@item M-d
+@item C-c >
 Go down the number of frames indicated by the numeric argument, like the
 @value{GDBN} @code{down} command.
-
-@emph{Warning:} In Emacs v19, this command is @kbd{C-c C-d}.
-
-@item C-x &
-Read the number where the cursor is positioned, and insert it at the end
-of the @value{GDBN} I/O buffer.  For example, if you wish to disassemble code
-around an address that was displayed earlier, type @kbd{disassemble};
-then move the cursor to the address display, and pick up the
-argument for @code{disassemble} by typing @kbd{C-x &}.
-
-You can customize this further by defining elements of the list
-@code{gdb-print-command}; once it is defined, you can format or
-otherwise process numbers picked up by @kbd{C-x &} before they are
-inserted.  A numeric argument to @kbd{C-x &} indicates that you
-wish special formatting, and also acts as an index to pick an element of the
-list.  If the list element is a string, the number to be inserted is
-formatted using the Emacs function @code{format}; otherwise the number
-is passed as an argument to the corresponding list element.
 @end table
 
-In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
+In any source file, the Emacs command @kbd{C-x SPC} (@code{gud-break})
 tells @value{GDBN} to set a breakpoint on the source line point is on.
 
+If you type @kbd{M-x speedbar}, then Emacs displays a separate frame which
+shows a backtrace when the @value{GDBN} I/O buffer is current.  Move
+point to any frame in the stack and type @key{RET} to make it become the
+current frame and display the associated source in the source buffer.
+Alternatively, click @kbd{Mouse-2} to make the selected frame become the
+current one.
+
 If you accidentally delete the source-display buffer, an easy way to get
 it back is to type the command @code{f} in the @value{GDBN} buffer, to
 request a frame display; when you run under Emacs, this recreates
@@ -14192,6 +14163,10 @@
 communicates with Emacs in terms of line numbers.  If you add or
 delete lines from the text, the line numbers that @value{GDBN} knows cease
 to correspond properly with the code.
+  
+The description given here is for GNU Emacs version 21.3 and a more
+detailed description of its interaction with @value{GDBN} is given in
+the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} Emacs Manual}).
 
 @c The following dropped because Epoch is nonstandard.  Reactivate
 @c if/when v19 does something similar. ---doc@cygnus.com 19dec1990