[PATCH v2] * GDB Texinfo manual: Correctly reference Emacs facilities

[Jeremy Bryant <jb@jeremybryant.net>]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Fri, 02 May 2025 09:20:43 +0300
>> From: Eli Zaretskii <eliz@gnu.org>
>> Cc: gdb-patches@sourceware.org, tom@tromey.com
>> 
>> > From: Jeremy Bryant <jb@jeremybryant.net>
>> > Date: Thu, 01 May 2025 23:08:04 +0100
>> 
>> > More generally, I believe that this section predates the changes in
>> > Emacs of M-x gdb vs M-x gud-gdb, so I will propose further patches down
>> > the line.  (vc-annotate indicates the text hasn't been updated in a long
>> > time)
>> 
>> In that case, I suggest to submit a single patch with all the changes
>> together.  It will make the job of reviewing the patch easier.
>
> On second thought, perhaps the GDB manual should just mention the
> Emacs front-end shortly, and point to the Emacs manual for the
> details?  It is sub-optimal to have the GDB-related features described
> in two manuals maintained by 23 different projects; doing that will
> necessarily risk incompatibilities and inconsistencies.

OK, agree it is suboptimal to duplicate, and the existing text appears
out-of-date (not updated in two decades).

I've revised the introduction, adapting styles from the previous section
introduction and the current Emacs manual (30.1)

Revised patch, in-line, below.
WDYT?




From ed9de3eae5cb72ae755994832a32d2817741e92a Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <jb@jeremybryant.net>
Date: Fri, 2 May 2025 21:56:35 +0100
Subject: [PATCH] * gdb/doc/gdb.texinfo (Emacs): Refer to Emacs manual

The manual section on using GDB under Emacs is out-of-date and
duplicates existing and comprehensive documentation in the Emacs
manual.

Replace the section by a short introduction and reference.
---
 gdb/doc/gdb.texinfo | 135 ++------------------------------------------
 1 file changed, 5 insertions(+), 130 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 9b4aa5b47b2..ed812e5ec05 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -31292,138 +31292,13 @@ appropriate @code{set style} commands.  @xref{Output Styling}.
 
 @cindex Emacs
 @cindex @sc{gnu} Emacs
-A special interface allows you to use @sc{gnu} Emacs to view (and
-edit) the source files for the program you are debugging with
-@value{GDBN}.
-
-To use this interface, use the command @kbd{M-x gdb} in Emacs.  Give the
-executable file you want to debug as an argument.  This command starts
-@value{GDBN} as a subprocess of Emacs, with input and output through a newly
-created Emacs buffer.
-@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.)
-
-Running @value{GDBN} under Emacs can be just like running @value{GDBN} normally except for two
-things:
-
-@itemize @bullet
-@item
-All ``terminal'' input and output goes through an Emacs buffer, called
-the GUD buffer.
-
-This applies both to @value{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
-in this way.
-
-All the facilities of Emacs' Shell mode are available for interacting
-with your program.  In particular, you can send signals the usual
-way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a
-stop.
-
-@item
-@value{GDBN} displays source code through Emacs.
-
-Each time @value{GDBN} displays a stack frame, Emacs automatically finds the
-source file for that frame and puts an arrow (@samp{=>}) at the
-left margin of the current line.  Emacs uses a separate buffer for
-source display, and splits the screen to show both your @value{GDBN} session
-and the source.
-
-Explicit @value{GDBN} @code{list} or search commands still produce output as
-usual, but you probably have no reason to use them from Emacs.
-@end itemize
-
-We call this @dfn{text command mode}.  Emacs 22.1, and later, also uses
-a graphical mode, enabled by default, which provides further buffers
-that can control the execution and describe the state of your program.
-@xref{GDB Graphical Interface,,, Emacs, The @sc{gnu} Emacs Manual}.
-
-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 the directory associated
-with the previous buffer.  In this case, @value{GDBN} may find your
-program by searching your environment's @env{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 GUD 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 GUD buffer, you can use these special Emacs commands in
-addition to the standard Shell mode commands:
-
-@table @kbd
-@item C-h m
-Describe the features of Emacs' GUD Mode.
-
-@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 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 C-c C-i
-Execute one instruction, like the @value{GDBN} @code{stepi} 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 C-c C-r
-Continue execution of your program, like the @value{GDBN} @code{continue}
-command.
-
-@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.
-
-@item C-c >
-Go down the number of frames indicated by the numeric argument, like the
-@value{GDBN} @code{down} command.
-@end table
-
-In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break})
-tells @value{GDBN} to set a breakpoint on the source line point is on.
-
-In text command mode, if you type @kbd{M-x speedbar}, Emacs displays a
-separate frame which shows a backtrace when the GUD 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.  In graphical mode, the
-speedbar displays watch expressions.
-
-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
-the source buffer if necessary to show you the context of the current
-frame.
 
-The source files displayed in Emacs are in ordinary Emacs buffers
-which are visiting the source files in the usual way.  You can edit
-the files with these buffers if you wish; but keep in mind that @value{GDBN}
-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.
+In @sc{gnu} Emacs there is a special interface to @value{GDBN}, which
+facilitates viewing the source code for the program you are debugging.
+There is also an IDE-like interface to GDB, with specialized buffers for
+breakpoints, stack frames and other aspects of the debugger state.
 
-A more detailed description of Emacs' interaction with @value{GDBN} is
+A detailed description of Emacs' interaction with @value{GDBN} is
 given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu}
 Emacs Manual}).
 
-- 
2.47.2