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 address@hidden' 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                             address@hidden