Re: [PATCH] GDB/MI documentation

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Thu, 14 May 2009 18:50:56 +1200
> Cc: gdb-patches@sourceware.org
> From: 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.

If you feel strongly about them, go ahead and commit them, but I still
think that the new text is not any clearer or more correct than the
original one.

Anyway, I thought you wanted to suggest some real additions to the
manual.  That would be most welcome, thanks.

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

No, it isn't: in the example from Wiki, there are commas ("Donald, who
came..."), so using semi-colons disambiguates the intent.  In the GDB
manual case, there are no commas to create ambiguity in the first
place, so commas are okay, IMO.

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

You are right about this one.

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

That's because the changes you submitted are insignificant.  For real
changes of content, I can assure you that there will be no more
iterations than necessary.  You can try looking through submissions by
others and my review of them.