Texinfo doc for GDB-UI

[Nick Roberts <nick@nick.uklinux.net>]

Here is my attempt at writing something for gdb-ui.el for the emacs manual.
I've not spent much time on it as it will probably change again. I just want
to do enough so that it explains the mode and doesn't harm the `emacs brand
name'. It probably also shows a lack of knowledge of texinfo. This file
(building.texi) could also say something about bashdb.

Any comments ?

Nick

*** building.texi.~1.26.~	Tue Oct 29 18:18:41 2002
--- building.texi	Fri Dec 20 01:10:35 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,315 ----
  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}
+ @findex gdba
+ 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
+ @xref{GDB-UI}.
+ 
  @item M-x dbx @key{RET} @var{file} @key{RET}
  @findex dbx
  Similar, but run DBX instead of GDB.
***************
*** 438,443 ****
--- 445,459 ----
  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)}
***************
*** 586,591 ****
--- 602,797 ----
  variable values can be displayed in tooltips by pointing at them with
  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
+ 
+ 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 isalso possible to dive into structures..
+ @end itemize
+ 
+ It is generally best to stay in GDB while editing and re-compiling a
+ program.  This can be done within emacs and this is generally 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.
+ 
+ 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.
+ 
+ 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
+ The extra buffers may either be displayed in the same frame
+ (@code{gdb-display-*-*}) or a different frame (@code{gdb-frame-*-*})
+ where *-* needs to be replaced by the relevant buffer name.
+ 
+ If @code{gdb-many-windows} is nil (the default value) then GDB starts with
+ just two windows : the GUD and the source buffer. If it is t the
+ following layout will appear (keybindings given in relevant buffer) :
+ 
+ @verb{+---------------------------------------------------------------------
+                                GDB Toolbar                           
+ ---------------------------------------------------------------------
+ GUD buffer (I/O of GDB)           | Locals buffer                    
+                                    |                                  
+                                    |                                  
+                                    |                                  
+ ---------------------------------------------------------------------
+ Source buffer                     | Input/Output (of debuggee) buffer
+                                    | (comint-mode)                    
+                                    |                                  
+                                    |                                  
+                                    |                                  
+                                    |                                  
+                                    |                                  
+                                    |                                  
+ ---------------------------------------------------------------------
+ Stack buffer                      | Breakpoints buffer               +}
+ `Mouse-2' gdb-frames-mouse-select | @key{SPC}  gdb-toggle-bp-this-line
+                                       | `g'    gdb-goto-bp-this-line
+                                        | `d'    gdb-delete-bp-this-line
+ ---------------------------------------------------------------------
+ 
+ @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 @xref{Set Breaks,,
+ info breakpoints, Gdb, The GNU debugger}. There are three commands
+ available :
+ 
+ @table @kbd
+ @item @key{SPC} 
+ 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 `B' or `b'.
+ 
+ @item @kbd{g}
+ 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}
+ 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
+ @xref{Backtrace,,info stack, Gdb, The GNU debugger}. 
+ 
+ A frame stack is a list of nested subroutine calls which shows the
+ context of the current frame.
+ 
+ (@code{gdb-frames-mouse-select}) on @kbd{Mouse-2} makes the selected
+ frame become the current one and displays the associated source in the
+ source buffer.
+ 
+ @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 @xref{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 values held by the registers and uses
+ the output from the GDB command @xref{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 set up to display
+ automatically and uses the output from the GDB command @xref{Auto
+ Display,,info display, Gdb, The GNU debugger}. As with the
+ breakpoints the displayed may be enabled/disabled or deleted.
+ 
+ @table @kbd
+ @item @key{SPC} 
+ Enable/disable the display on the current line
+ (@code{gdb-toggle-disp-this-line}).
+ 
+ @item @kbd{d}
+ Delete the display on the current line (@code{gdb-delete-disp-this-line}).
+ @end table
+ 
+ @node Data Display
+ @subsubsection Data Display
+ 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.
+ 
+ One dimensional arrays can be visualised using the graph program from
+ plotutils if this is installed by typing @kbd{v} (@code{gdb-array-visualise}).
+ 
+ Pointers in structures may be followed by in a tree-like fashion
+ clicking on them with the middle mouse button (@code{gdb-dive}).
+ 
+ To delete the displayed expression and the window type
+ @kbd{q} (@code{gdb-delete-display}).
  
  @node Executing Lisp
  @section Executing Lisp Expressions