Texinfo doc for GDB-UI

Texinfo doc for GDB-UI

[Nick Roberts]

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

Re: Texinfo doc for GDB-UI

[Robert J. Chassell]

   Here is my attempt at writing something for gdb-ui.el for the emacs manual.
   ...
   Any comments ?

In smallbook format, the @verb section produces overfull \hboxes,
since the lines are too wide.  Also, the offset vertical bars remain
visibly offset.

For an example of an Emacs screenshot as complex as this, you might
follow the @image route.  You already have a .txt file for Info; the
GIMP can produce a screen shot in PostScript, PNG, or HTML format for
other output formats.  As a minimum, the doc has to look good when
typeset for printing and on a Web page as well as in Info.

Also, you will need alternative text for people who listen to the
document using Emacspeak.  (Think of someone driving a car as
`situationally blind', as well as the permanently blind.  With Eflite,
you can now run Emacspeak using only free software.  You have no need
for proprietary software packages that its vendor no longer supports
or for expensive hardware cards.)

A side effect of creating a document that listens well is that it is
also likely to work well for sighted people.

I have not had time (nor will I) to read or listen to the
contents... :-(

Minor typo

   + It isalso possible to dive into structures..
        ^^^^^^                                 ^^
should be

   + It is also possible to dive into structures.

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

Re: Texinfo doc for GDB-UI

[Eli Zaretskii]

> From: Nick Roberts <nick@nick.uklinux.net>
> Date: Mon, 23 Dec 2002 21:54:28 +0000
> 
> Here is my attempt at writing something for gdb-ui.el for the emacs manual.

Thanks!

A few comments:

> + @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}.

First, please don't use @xref except at the beginning of a sentence,
since the text it produces begins with a capitalized "See", and will
look like a typo in the middle of a sentence.

Secondly, an index entry for a command ("@findex gdba" above) should
be where the command is explained in full, not where it's mentioned
for the first time.  So the right place for the index entry is in the
second paragraph of the node GDB-UI.

Finally, please make sure every sentence has either two spaces or a
newline after the period that ends the sentence.  This is so TeX
typesets the sentence separation correctly.

> + 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}.

Please make an @findex entry for every command you mention in the
manual (here gdb-restore-windows).  (There are other places where
commands are mentioned without an @findex entry.)

> + @node Layout
> + @subsubsection Layout

It is generally advisable to make @cindex entries where important
parts of the UI are described, under the assumption that users may
wish to find those details quickly.  For example, this section would
probably benefit from an entry such as "@cindex GDB-UT layout".  The
subsection name is in many cases a good starting point for the
@cindex entry.

> + If @code{gdb-many-windows} is nil (the default value)

`nil' is a symbol, so it should have the @code markup.

> + @verb{+---------------------------------------------------------------------
> +                                GDB Toolbar                           
> + ---------------------------------------------------------------------
> + GUD buffer (I/O of GDB)           | Locals buffer                    

I suggest to make the lines here shorter; anything longer than 64
characters will produce overfull hbox warnings from TeX, and will
spill over to the margin of the page.

> + 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}.

Does this xref really work?  The GDB manual's name is `gdb.info', not
`Gdb.info', so on a case-sensitive filesystem the xref might not work
(but I didn't actually try that, so I might be missing something).

> + grey when it is disabled. Text-only terminals will correspondingly
> + display a `B' or `b'.

Please use @samp{b} and @samp{B}, not `b' and `B' here.

> + 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.

I think the last sentence should say "displayed expressions" or maybe
"displays", not "displayed".

Re: Texinfo doc for GDB-UI

[Andreas Schwab]

"Eli Zaretskii" <eliz@is.elta.co.il> writes:

|> Finally, please make sure every sentence has either two spaces or a
|> newline after the period that ends the sentence.  This is so TeX
|> typesets the sentence separation correctly.

TeX does not care.  For TeX every amount of consecutive whitespace is
equivalent to a single space.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Deutschherrnstr. 15-19, D-90429 Nürnberg
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Texinfo doc for GDB-UI

[Alex Schroeder]

Andreas Schwab <schwab@suse.de> writes:

> "Eli Zaretskii" <eliz@is.elta.co.il> writes:
>
> |> Finally, please make sure every sentence has either two spaces or a
> |> newline after the period that ends the sentence.  This is so TeX
> |> typesets the sentence separation correctly.
>
> TeX does not care.  For TeX every amount of consecutive whitespace is
> equivalent to a single space.

Correct.  It is for the info output, not the TeX output, I guess.
>From the texinfo manual:

  Ordinarily, TeX collapses multiple whitespace characters (space, tab,
and newline) into a single space.  Info output, on the other hand,
preserves whitespace as you type it, except for changing a newline into
a space; this is why it is important to put two spaces at the end of
sentences in Texinfo documents.

Alex.

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.

Re: Texinfo doc for GDB-UI

[Richard Stallman]

The reason for the two spaces is so M-e in Emacs will work.

Re: Texinfo doc for GDB-UI

[Robert J. Chassell]

   + Continue execution up to the current line. 
                        ^^
This language sounds reversed to me.  It is potentially confusing,
since I think of execution as continuing through a text, line by line.
For me, the point of current execution goes *down* the screen.

Thus, if I set a break point for in aline that is is not as yet
executed, I expect to go *down* the display of the source code to find
that line, not up the screen to it.

Please simply write

   + Continue execution to the current line. 

and not use the words `up' or `down'.


In my experience, readers for whom English is a second or third
language have an easier time when the language is formal.  They were
taught such a language in school.  And, in general, formal English is
easier to understand since related concepts are closer to each other,
or linked in well established ways.

Here is a sentence that is easily understood by a fluent English
speaker:

     .... 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

You might change those lines to:

   + it hits a breakpoint, terminates, receives a signal that the
   + debugger seeks, or reaches the line on which the cursor currently
   + sits.


You might change from 

   + GDB-UI is invoked with the command @code{gdba}.  As well as having the
   + usual features of GUD, it does the following :   ^^^^^^^^^^
                                        ^^^^^^^^^^^   
                                                 |
                                                  - extraneous space
to

   + GDB-UI is invoked with the command @code{gdba}.  In addition to
   + the usual features of GUD, it has the following:
                                           ^^^^^^^^^^ 



The imperative verb in a sentences such as the following is often read in an
isolated context:

from:

   + @item 
   + Finds the source file where execution begins and displays it in a buffer.
     ^^^^^
to 

   + Find the source file where execution begins and displays it in a buffer.
     ^^^^

from
   + Displays a bullet point icon in the margin on the line at which a
     ^^^^^^^^   ^^^^^^^^^^^^^^^^^
to

   + Display a bullet in the margin on the line at which a
     ^^^^^^^   ^^^^^^


The following is weird:

   + breakpoint is placed.  This is red when the breakpoint is enabled and
   + grey when it is disabled.      ^^^
     ^^^^

What color is the breakpoint when the user changes the color, as I do,
or when the user can display only a single color, or when the user
listens to the buffer, rather than looks at it?  The sentence reads as
if you are planning only for non-blind people to run GDB locally in a
fully working, expensive system with a working graphical interface.

Please re-write the sentence to explain the user interface to someone
listening to the buffer (using eflite, which does not offer different
voices as yet), and to someone viewing the buffer while working
remotely over a slow line.


   + The extra buffers may either be displayed in the same frame or a

Are the buffers `extra', meaning `superfluous' or are they
`additional'?  If the latter, please use the word `additional', since
that word is more immediately comprehensible in this context to
someone for whom understanding is difficult.

   + @code{gdb-frame-*-buffer} respectively where * needs to replaced
                     ^                            ^

The `@var' command in Texinfo provides a way to display and discuss
metasyntactic variables; please use it.  Please select a meaningful
word for the metasyntactic variable (unfortunately, I cannot think of
one).

I hope this helps. I lack the time to make more comments, but this should
give you some ideas.

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

Re: Texinfo doc for GDB-UI

[Richard Stallman]

    + @node Breakpoints Buffer
    + @subsubsection Breakpoints Buffer
    + 
    + This buffer

Say explicitly which buffer you mean.  The text should never refer
back to the section title in that way.

		  allows control

That's clumsy writing--can you make it smoother?

				 of the breakpoints which have been set
    + previously

That's the useful info for the user.  It says what this feature does.

		 and uses the output from the GDB command @ref{Set Breaks,,
    + info breakpoints, gdb, The GNU debugger}.

That's implementation info; it should not be stated here at all,
because it is not relevant for the readers who will use GDB-UI.

      There are three commands
    + available :

That's not very clean.  It is better to say,

  There are three special commands in the breakpoints buffer:

Do you see why that reads better?