(GDB Graphical Interface): Update and describe layout first.

1 files changed, 58 insertions, 45 deletions

diff --git a/man/building.texi b/man/building.texi
index 2985a04895c..994e3be3f59 100644
--- a/man/building.texi
+++ b/man/building.texi
@@ -286,7 +286,7 @@ Emacs.  @xref{MS-DOS}.
 The GUD (Grand Unified Debugger) library provides an interface to
 various symbolic debuggers from within Emacs.  We recommend the debugger
 GDB, which is free software, but you can also run DBX, SDB or XDB if you
-have them.  GUD can also serve as an interface to the Perl's debugging
+have them.  GUD can also serve as an interface to Perl's debugging
 mode, the Python debugger PDB, and to JDB, the Java Debugger.
 @xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference Manual},
 for information on debugging Emacs Lisp programs.
@@ -311,9 +311,13 @@ to a particular debugger program.
 @table @kbd
 @item M-x gdb @key{RET} @var{file} @key{RET}
 @findex gdb
-Run GDB as a subprocess of Emacs.  This command creates a buffer
-for input and output to GDB, and switches to it.  If a GDB buffer
-already exists, it just switches to that buffer.
+Run GDB as a subprocess of Emacs.  If the variable
+@code{gud-gdb-command-name} is ``gdb --annotate=3'' (the default
+value) then GDB starts as for @kbd{M-x gdba} below.  If you want to
+GDB to start as in Emacs 21.3 and earlier then set
+@code{gud-gdb-command-name} to ``gdb --fullname''.  In this case, the
+command creates a buffer for input and output to GDB, and switches to
+it.  If a GDB buffer already exists, it just switches to that buffer.
 
 @item M-x gdba @key{RET} @var{file} @key{RET}
 Run GDB as a subprocess of Emacs, providing a graphical interface
@@ -638,13 +642,59 @@ mode is that you can do it through menus and clicks, without needing
 to know GDB commands.
 
 @menu
+* Layout::               Control the number of displayed buffers.
 * Breakpoints Buffer::   A breakpoint control panel.
 * Stack Buffer::         Select a frame from the call stack. 
 * Watch Expressions::    Monitor variable values in the speedbar.
 * Other Buffers::        Input/output, locals, registers and assembler buffers.
-* Layout::               Control the number of displayed buffers.
 @end menu
 
+@node Layout
+@subsubsection Layout
+@cindex GDB User Interface layout
+
+@findex gdb-many-windows
+@vindex gdb-many-windows
+
+If the variable @code{gdb-many-windows} is @code{nil} (the default
+value) then gdb just pops up the GUD buffer unless the variable
+@code{gdb-show-main} is non-@code{nil}.  In this case it starts with
+two windows: one displaying the GUD buffer and the other with the
+source file with the main routine of the inferior.
+
+If @code{gdb-many-windows} is non-@code{nil}, regardless of the value of
+@code{gdb-show-main}, the layout below will appear unless
+@code{gdb-use-inferior-io-buffer} is @code{nil}.  In this case the
+source buffer occupies the full width of the frame.
+
+@multitable @columnfractions .5 .5
+@item GUD buffer (I/O of GDB)
+@tab Locals buffer
+@item
+@tab
+@item Source buffer
+@tab Input/Output (of inferior) buffer
+@item
+@tab
+@item Stack buffer
+@tab Breakpoints buffer
+@end multitable
+
+To toggle this layout, do @kbd{M-x gdb-many-windows}.
+
+@findex gdb-restore-windows
+If you change the window layout, for example, while editing and
+re-compiling your program, then you can restore it with the command
+@code{gdb-restore-windows}.
+
+You may also choose which additional buffers you want to display,
+either in the same frame or a different one.  Select GDB-windows or
+GDB-Frames from the menu-bar under the heading GUD.  If the menu-bar
+is unavailable, type @code{M-x
+gdb-display-@var{buffertype}-buffer} or @code{M-x
+gdb-frame-@var{buffertype}-buffer} respectively, where @var{buffertype}
+is the relevant buffer type e.g breakpoints.
+
 @node Breakpoints Buffer
 @subsubsection Breakpoints Buffer
 
@@ -705,7 +755,7 @@ on the tag to the left of the expression.
 @kindex RET @r{(GDB speedbar)}
 @findex gdb-var-delete
 With the cursor over the root expression of a complex data type, type
-@key{D} to delete it from the speedbar
+@kbd{D} to delete it from the speedbar
 (@code{gdb-var-delete}).
 
 @findex gdb-edit-value
@@ -730,7 +780,8 @@ the default value is @code{nil}.
 
 @table @asis
 @item Input/Output Buffer
-The executable program that is being debugged takes its input and
+If the variable @code{gdb-use-inferior-io-buffer} is non-@code{nil},
+the executable program that is being debugged takes its input and
 displays its output here.  Some of the commands from shell mode are
 available here.  @xref{Shell Mode}.
 
@@ -763,44 +814,6 @@ make the selected thread become the current one.
 
 @end table
 
-@node Layout
-@subsubsection Layout
-@cindex GDB User Interface layout
-
-@findex gdb-many-windows
-@vindex gdb-many-windows
-If @code{gdb-many-windows} is @code{nil} (the default value), then GDB starts
-with just two windows: the GUD and the source buffer.  If it is @code{t}, then
-six windows with the following layout will appear:
-
-@multitable @columnfractions .5 .5
-@item GUD buffer (I/O of GDB)
-@tab Locals buffer
-@item
-@tab
-@item Source buffer
-@tab Input/Output (of debuggee) buffer
-@item
-@tab
-@item Stack buffer
-@tab Breakpoints buffer
-@end multitable
-
-To toggle this layout, do @kbd{M-x gdb-many-windows}.
-
-@findex gdb-restore-windows
-If you change the window layout, for example, while editing and
-re-compiling your program, then you can restore it with
-@code{gdb-restore-windows}.
-
-You may also choose which additional buffers you want to display,
-either in the same frame or a different one.  Select GDB-windows or
-GDB-Frames from the menu-bar under the heading GUD.  If the menu-bar
-is unavailable, type @code{M-x
-gdb-display-@var{buffertype}-buffer} or @code{M-x
-gdb-frame-@var{buffertype}-buffer} respectively, where @var{buffertype}
-is the relevant buffer type e.g breakpoints.
-
 @node Executing Lisp
 @section Executing Lisp Expressions