Re: [PATCH] GDB/MI documentation

[nickrob@snap.net.nz (Nick Roberts)]

 > > Here are just a few basic changes that preserve the content.
 > 
 > I'm okay with adding nodes, but the rest of the changes don't make the
 > text any clearer than it is already.

I thought this change was so basic, obvious almost, that approval would be a
formality.  Let's just look at two changes:

- Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three
- parts---commands sent to @value{GDBN}, responses to those commands
- and notifications.

+ Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three
+ parts: commands sent to @value{GDBN}; responses to those commands;
+ and notifications.

A wide dash (Em dash?) is normally used parenthetically while a semi-colon is
generally used for a list, often with a colon.  The example at
http://en.wikipedia.org/wiki/Semicolon:

  "She saw three men: Donald, who came from New Zealand; Jon, the milkman's son;
  and George, a gaunt kind of man."

is almost identical to my change.

- Notifications is the mechanism for reporting changes in the state of the
- target,

+ Notifications are used for reporting changes in the state of the
+ target,

It's generally considered bad English to use "is" after a plural word.

If you think that correct punctuation and grammar don't make the text any
clearer then I'm a bit at a loss at what to say.  Perhaps speling doesn't
matter either.


 > > I think it would be quite easy to read GDB/MI General Design and still not
 > > understand the overall purpose of GDB/MI.
 > 
 > Feel free to suggest the text you think is missing.  I'd welcome any
 > such patches.
 > 
 > TIA

Frankly, the overhead seems too high.  I don't think it should be necessary
for every little change to have so many iterations.  One step backward for
every four forward is better than taking no steps at all.

-- 
Nick                                           http://www.inet.net.nz/~nickrob