Texinfo doc for GDB-UI

[Nick Roberts]

Thanks for the comments. I've tried to revise the documentation accordingly
and realise now what the index commands are for. As I'm not that familiar
with Texinfo and because the manual has its own written style, I submit it as
a patch for someone else to install, if appropriate and when convenient.

Nick

*** building.texi.~1.26.~       Tue Oct 29 18:18:41 2002
--- building.texi       Thu Dec 26 00:27:32 2002
***************
*** 288,293 ****
--- 288,294 ----
  * Commands of GUD::   Key bindings for common commands.
  * GUD Customization:: Defining your own commands for GUD.
  * GUD Tooltips::        Showing variable values by pointing with the mouse.
+ * GDB-UI::              Graphical user interface for GDB.
  @end menu
  
  @node Starting GUD
***************
*** 303,308 ****
--- 304,314 ----
  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.  This command generates a more extensive
+ user interface than the command gdb.  These extra features are described in
+ @ref{GDB-UI}.
+ 
  @item M-x dbx @key{RET} @var{file} @key{RET}
  @findex dbx
  Similar, but run DBX instead of GDB.
***************
*** 438,443 ****
--- 444,458 ----
  will run until it hits a breakpoint, terminates, or gets a signal that
  the debugger is checking for (@code{gud-cont}).
  
+ @item C-c C-u
+ @kindex C-c C-u @r{(GUD)}
+ @itemx C-x C-a C-u
+ @findex gud-until
+ Continue execution up to the current line. The program will run until
+ it hits a breakpoint, terminates, gets a signal that the debugger is
+ checking for or reaches the line that the cursor is on
+ (@code{gud-goto}).
+ 
  @need 1000
  @item C-c C-d
  @kindex C-c C-d @r{(GUD)}
***************
*** 587,596 ****
  the mouse in the GUD buffer or in source buffers with major modes in the
  customizable list @code{tooltip-gud-modes}.
  
  @node Executing Lisp
  @section Executing Lisp Expressions
  
!   Emacs has several different major modes for Lisp and Scheme.  They are
  the same in terms of editing commands, but differ in the commands for
  executing Lisp expressions.  Each mode has its own purpose.
  
--- 602,827 ----
  the mouse in the GUD buffer or in source buffers with major modes in the
  customizable list @code{tooltip-gud-modes}.
  
+ @node GDB-UI
+ @subsection GDB-UI
+ 
+ @findex gdba
+ GDB-UI is invoked with the command @code{gdba}.  As well as having the
+ usual features of GUD, it does the following :
+ 
+ @itemize @bullet
+ 
+ @item 
+ Finds the source file where execution begins and displays it in a buffer.
+ 
+ @item 
+ Displays a bullet point icon in the margin on the line at which a
+ breakpoint is placed.  This is red when the breakpoint is enabled and
+ grey when it is disabled.
+ 
+ @item 
+ Separates the IO of the executable from that of GDB and puts it in a
+ different buffer.
+ 
+ @item 
+ Auto-displays data in separate frames and formats arrays and structures. 
+ It is also possible to dive into structures.
+ @end itemize
+ 
+ In addition to the GUD buffer and the source buffer, extra buffers may
+ be displayed :
+ 
+ @menu
+ * Layout::               Control the number of buffers that are displayed.
+ * Breakpoints Buffer::   A breakpoint control panel.
+ * Stack Buffer::         Select a frame from the frame stack. 
+ * Input/Output Buffer::  Input and output of the executable.
+ * Locals Buffer::        Display the local variables of the current frame.
+ * Registers Buffer::     Display the register values.
+ * Assembler Buffer::     Display the machine code.
+ * Display Buffer::       Control the displayed expressions.
+ * Data Display::         Display and update expressions in their own frame.
+ @end menu
+ 
+ @node Layout
+ @subsubsection Layout
+ @cindex GDB-UI layout
+ The extra buffers may either be displayed in the same frame or a
+ different one.  The buffers can be selected from the menu-bar under
+ the heading GUD.  If the menu-bar is unavailable then they can be
+ invoked by typing @code{gdb-display-*-buffer} or
+ @code{gdb-frame-*-buffer} respectively where * needs to replaced
+ by the relevant buffer type e.g breakpoints.
+ 
+ @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 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 (comint-mode)
+ @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
+ It is generally best to stay in GDB while editing and re-compiling a
+ program.  This can be done within emacs and is easier with just one or
+ two windows.  So, after re-compilation, the window layout for the
+ debugging session can be restored with @code{gdb-restore-windows}.
+ Once you have ensured the breakpoints are correct, clicking on the run
+ icon will restart the program.
+ 
+ @findex gdb-quit
+ When you have finished debugging a particular program then don't just
+ kill the GUD buffer because this will leave a lot of other buffers
+ lying around.  Instead use @code{gdb-quit} which will kill these
+ buffers and reset things like the toolbar and margin in the source
+ buffers.
+ 
+ @node Breakpoints Buffer
+ @subsubsection Breakpoints Buffer
+ 
+ This buffer allows control of the breakpoints which have been set
+ previously and uses the output from the GDB command @ref{Set Breaks,,
+ info breakpoints, gdb, The GNU debugger}.  There are three commands
+ available :
+ 
+ @table @kbd
+ @item @key{SPC} 
+ @kindex SPC @r{(GDB-UI breakpoints)}
+ @findex gdb-toggle-bp-this-line
+ Enable/disable the breakpoint on the current line
+ (@code{gdb-toggle-bp-this-line}).  On a graphical display, a bullet
+ point icon is displayed in the margin of the source buffer at the
+ relevant line.  This changes to red when the breakpoint is enabled and
+ grey when it is disabled.  Text-only terminals will correspondingly
+ display a @samp{B} or @samp{b}.
+ 
+ @item @kbd{g}
+ @kindex g @r{(GDB-UI breakpoints)}
+ @findex gdb-goto-bp-this-line
+ Display the file in the source buffer that contains the breakpoint 
+ described on the current line (@code{gdb-goto-bp-this-line}).
+ 
+ @item @kbd{d}
+ @kindex d @r{(GDB-UI breakpoints)}
+ @findex gdb-delete-bp-this-line
+ Delete the breakpoint on the current line (@code{gdb-delete-bp-this-line}).
+ @end table
+ 
+ @node Stack Buffer
+ @subsubsection Stack Buffer
+ 
+ This buffer displays a frame stack and uses the output from the GDB command
+ @ref{Backtrace,,info stack, gdb, The GNU debugger}. 
+ 
+ A frame stack is a list of nested subroutine calls which shows the the
+ current state of the executable in context. Any frame can be examined
+ by making it the current frame. Clicking @kbd{Mouse-2}
+ (@code{gdb-frames-mouse-select}) makes the selected frame become the
+ current one and displays the associated source in the source
+ buffer. If the locals buffer is being displayed then its contents are
+ also updated for the current frame.
+ 
+ @node Input/Output Buffer
+ @subsubsection Input/Output Buffer
+ 
+ The executable program takes its input and displays its output here. 
+ Some of the commands from shell mode are available here.  @xref{Shell Mode}.
+ 
+ @node Locals Buffer
+ @subsubsection Locals Buffer
+ 
+ This buffer displays the values of local variables of the current
+ frame and uses the output from the GDB command @ref{Frame Info,,
+ info locals, gdb, The GNU debugger}.
+ 
+ Arrays and structures only have their type displayed.  To
+ examine the values of these types the place the cursor over the
+ variable name and click on the display icon in the toolbar.
+ 
+ @node Registers Buffer
+ @subsubsection Registers Buffer
+ 
+ This buffer displays the values held by the registers and uses
+ the output from the GDB command @ref{Registers,,info registers, gdb,
+ The GNU debugger}.
+ 
+ @node Assembler Buffer
+ @subsubsection Assembler Buffer
+ 
+ This buffer displays the current frame as machine code.  An overlay
+ arrow points to the current instruction and breakpoints can be set and
+ removed as with the source buffer.  Breakpoint icons are also displayed.
+ 
+ @node Display Buffer
+ @subsubsection Display Buffer
+ 
+ This buffer controls the list of expressions that are displayed and
+ updated in their own frame. It uses the output from the GDB command
+ @ref{Auto Display,,info display, gdb, The GNU debugger}.  As with the
+ breakpoints the displayed expressions may be enabled/disabled or
+ deleted.
+ 
+ @table @kbd
+ @item @key{SPC}
+ @kindex SPC @r{(GDB-UI display)}
+ @findex gdb-toggle-disp-this-line
+ Enable/disable the display on the current line
+ (@code{gdb-toggle-disp-this-line}).
+ 
+ @item @kbd{d}
+ @kindex d @r{(GDB-UI display)}
+ @findex gdb-delete-disp-this-line
+ Delete the display on the current line (@code{gdb-delete-disp-this-line}).
+ @end table
+ 
+ @node Data Display
+ @subsubsection Data Display
+ @cindex displaying expressions in GDB
+ 
+ Displayed expressions appear in separate frames.  Arrays are formatted
+ in an easy to read fashion and may be displayed as a slice.  To do this,
+ at the top of the display window, click on the array index that you
+ want to restrict and you will be prompted in the mini-buffer for a
+ start and a stop value.
+ 
+ @table @kbd
+ @item @kbd{v}
+ @kindex v @r{(GDB-UI data)}
+ @findex gdb-array-visualise
+ One dimensional arrays can be visualised using the graph program from
+ plotutils if this is installed.
+ (@code{gdb-array-visualise}).
+ 
+ @item @kbd{Mouse-2}
+ @kindex Mouse-2 @r{(GDB-UI data)}
+ @findex gdb-dive
+ Clicking on a pointer will follow its reference.  In this manner
+ structures may be followed in a tree-like fashion (@code{gdb-dive}).
+ 
+ @item @kbd{q}
+ @kindex q @r{(GDB-UI data)}
+ @findex gdb-delete-display
+ Delete the displayed expression and the associated frame
+ (@code{gdb-delete-display}).
+ @end table
+ 
  @node Executing Lisp
  @section Executing Lisp Expressions
  
! Emacs has several different major modes for Lisp and Scheme.  They are
  the same in terms of editing commands, but differ in the commands for
  executing Lisp expressions.  Each mode has its own purpose.