[PATCH] GDB/MI documentation

[PATCH] GDB/MI documentation

[Nick Roberts]

I think it would be quite easy to read GDB/MI General Design and still not
understand the overall purpose of GDB/MI.  It dives straight into detail about
notifications which appear to be buried much later in the node called GDB/MI
Async Records.

Perhaps there could be some background mentioning annotations as a predecessor and
saying `something like':

  The problem with annotations is that it marks up output intended for a human
  to read.  That means that the syntax might change at any time.  In contrast,
  MI is more formal output intended for parsing by computers, that should
  provide a more robust interface.

Here are just a few basic changes that preserve the content.

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


2009-05-13  Nick Roberts  <nickrob@snap.net.nz>

	* gdb.texinfo (GDB/MI General Design): Break up into four nodes.
        Simplify English.


*** gdb.texinfo	13 May 2009 17:43:30 +1200	1.591
--- gdb.texinfo	13 May 2009 21:54:04 +1200	
*************** may repeat one or more times.
*** 19788,19804 ****
  @cindex GDB/MI General Design
  
  Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three
! parts---commands sent to @value{GDBN}, responses to those commands
  and notifications.  Each command results in exactly one response,
  indicating either successful completion of the command, or an error.
! For the commands that do not resume the target, the response contains the
! requested information.  For the commands that resume the target, the
  response only indicates whether the target was successfully resumed.
! Notifications is the mechanism for reporting changes in the state of the
  target, or in @value{GDBN} state, that cannot conveniently be associated with
  a command and reported as part of that command response.
  
! The important examples of notifications are:
  @itemize @bullet
  
  @item 
--- 19788,19805 ----
  @cindex GDB/MI General Design
  
  Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three
! parts: commands sent to @value{GDBN}; responses to those commands;
  and notifications.  Each command results in exactly one response,
  indicating either successful completion of the command, or an error.
! For commands that do not resume the target, the response contains the
! requested information, while for those that do resume the target, the
  response only indicates whether the target was successfully resumed.
! Notifications are used for reporting changes in the state of the
  target, or in @value{GDBN} state, that cannot conveniently be associated with
  a command and reported as part of that command response.
  
! Important types of notifications are:
! 
  @itemize @bullet
  
  @item 
*************** processed.  Therefore, whenever an MI co
*** 19834,19839 ****
--- 19835,19848 ----
  we recommend that the frontend refreshes all the information shown in 
  the user interface.
  
+ 
+ @menu
+ * Context management::
+ * Asynchronous command execution and non-stop mode::
+ * Thread groups::
+ @end menu
+ 
+ @node Context management
  @subsection Context management
  
  In most cases when @value{GDBN} accesses the target, this access is
*************** all subsequent commands.  No frontend is
*** 19886,19891 ****
--- 19895,19901 ----
  right, so it is suggested to just always pass the @samp{--thread} and
  @samp{--frame} options.
  
+ @node Asynchronous command execution and non-stop mode
  @subsection Asynchronous command execution and non-stop mode
  
  On some targets, @value{GDBN} is capable of processing MI commands
*************** highly target dependent.  However, the t
*** 19921,19926 ****
--- 19931,19937 ----
  @code{-exec-interrupt}, to stop a thread, and @code{-thread-info},
  to find the state of a thread, will always work.
  
+ @node Thread groups
  @subsection Thread groups
  @value{GDBN} may be used to debug several processes at the same time.
  On some platfroms, @value{GDBN} may support debugging of several

Re: [PATCH] GDB/MI documentation

[Vladimir Prus]

Nick Roberts wrote:

> I think it would be quite easy to read GDB/MI General Design and still not
> understand the overall purpose of GDB/MI.  It dives straight into detail about
> notifications which appear to be buried much later in the node called GDB/MI
> Async Records.

It might not be ideal.

> 
> Perhaps there could be some background mentioning annotations as a predecessor and
> saying `something like':
> 
> The problem with annotations is that it marks up output intended for a human
> to read.  That means that the syntax might change at any time.  In contrast,
> MI is more formal output intended for parsing by computers, that should
> provide a more robust interface.

I suspect that 99% of the readers have no idea what annotations are. Therefore,
it is best to stress MI differences from CLI.

> Here are just a few basic changes that preserve the content.
> 
> Nick                                           http://www.inet.net.nz/~nickrob
> 
> 
> 2009-05-13  Nick Roberts  <nickrob@snap.net.nz>
> 
> * gdb.texinfo (GDB/MI General Design): Break up into four nodes.
> Simplify English.
> 
> 
> *** gdb.texinfo 13 May 2009 17:43:30 +1200      1.591
> --- gdb.texinfo 13 May 2009 21:54:04 +1200
> *************** may repeat one or more times.
> *** 19788,19804 ****
> @cindex GDB/MI General Design

> 
> Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three
> ! parts---commands sent to @value{GDBN}, responses to those commands
> and notifications.  Each command results in exactly one response,
> indicating either successful completion of the command, or an error.
> ! For the commands that do not resume the target, the response contains the
> ! requested information.  For the commands that resume the target, the
> response only indicates whether the target was successfully resumed.
> ! Notifications is the mechanism for reporting changes in the state of the
> target, or in @value{GDBN} state, that cannot conveniently be associated with
> a command and reported as part of that command response.
> 
> ! The important examples of notifications are:
> @itemize @bullet
> 
> @item
> --- 19788,19805 ----
> @cindex GDB/MI General Design
> 
> Interaction of a @sc{GDB/MI} frontend with @value{GDBN} involves three
> ! parts: commands sent to @value{GDBN}; responses to those commands;
> and notifications.  

I am not sure that ';' use here is appropriate or that there's any problem
with original text.

> Each command results in exactly one response, 
> indicating either successful completion of the command, or an error.
> ! For commands that do not resume the target, the response contains the
> ! requested information, while for those that do resume the target, the
> response only indicates whether the target was successfully resumed.
> ! Notifications are used for reporting changes in the state of the
> target, or in @value{GDBN} state, that cannot conveniently be associated with
> a command and reported as part of that command response.
> 
> ! Important types of notifications are:
> !
> @itemize @bullet
> 
> @item
> *************** processed.  Therefore, whenever an MI co
> *** 19834,19839 ****
> --- 19835,19848 ----
> we recommend that the frontend refreshes all the information shown in
> the user interface.
> 
> +
> + @menu
> + * Context management::
> + * Asynchronous command execution and non-stop mode::
> + * Thread groups::
> + @end menu
> +
> + @node Context management
> @subsection Context management
> 
> In most cases when @value{GDBN} accesses the target, this access is
> *************** all subsequent commands.  No frontend is
> *** 19886,19891 ****
> --- 19895,19901 ----
> right, so it is suggested to just always pass the @samp{--thread} and
> @samp{--frame} options.
> 
> + @node Asynchronous command execution and non-stop mode
> @subsection Asynchronous command execution and non-stop mode
> 
> On some targets, @value{GDBN} is capable of processing MI commands
> *************** highly target dependent.  However, the t
> *** 19921,19926 ****
> --- 19931,19937 ----
> @code{-exec-interrupt}, to stop a thread, and @code{-thread-info},
> to find the state of a thread, will always work.
> 
> + @node Thread groups
> @subsection Thread groups
> @value{GDBN} may be used to debug several processes at the same time.
> On some platfroms, @value{GDBN} may support debugging of several

The remaining edits appear to be pure english and/or texinfo, and I
have no comment on those. I home this "menu" thing does not appear
in either HTML or PDF?

- Volodya

Re: [PATCH] GDB/MI documentation

[Eli Zaretskii]

> From:  Vladimir Prus <vladimir@codesourcery.com>
> Date:  Wed, 13 May 2009 15:59:15 +0400
> 
> The remaining edits appear to be pure english and/or texinfo, and I
> have no comment on those.

Nick added nodes where previously there were sections and subsections
without nodes.

> I home this "menu" thing does not appear in either HTML or PDF?

No, they don't.

Re: [PATCH] GDB/MI documentation

[Eli Zaretskii]

> Date: Wed, 13 May 2009 22:36:11 +1200
> From: nickrob@snap.net.nz (Nick Roberts)
> 
> 
> 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

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

> + * Asynchronous command execution and non-stop mode::

This node's name is too long, consider making it shorter (it does not
have to be identical to the subsection name).

Thanks.

Re: [PATCH] GDB/MI documentation

[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

Re: [PATCH] GDB/MI documentation

[Vladimir Prus]

Nick Roberts wrote:

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

Unfortunately, you have made a semantic change to the sentence. Original
sentence was definition what notification is. The changed sentence, instead,
say what notifications do, and is not a definition.

- Volodya

Re: [PATCH] GDB/MI documentation

[Nick Roberts]

Vladimir Prus writes:
 > Nick Roberts wrote:
 > 
 > > - 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.
 > 
 > Unfortunately, you have made a semantic change to the sentence. Original
 > sentence was definition what notification is. The changed sentence, instead,
 > say what notifications do, and is not a definition.

You've defined them by what they do, so the definition here is implicit.  If
you want to emphasise the definition, you could use @dfn{}.  In any case,
in the patch I've committed, I've not changed this.

After describing them in the node, GDB/MI General Design, the documentation
uses older terminolgy and they are generally referred to as async records.

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

Re: [PATCH] GDB/MI documentation

[Eli Zaretskii]

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

Re: [PATCH] GDB/MI documentation

[Nick Roberts]

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

Hmm, you might be right.  My point, if I had one, was that changes don't need
to be perfect but just an improvement.  It is quite likekly that they will change
again.

I've just committed the part that breaks the node up into four smaller ones
with a shorter node name as you suggested (Asynchronous and non-stop modes).

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

Re: [PATCH] GDB/MI documentation

[Eli Zaretskii]

> Date: Fri, 15 May 2009 09:50:01 +1200
> Cc: gdb-patches@sourceware.org
> From: nickrob@snap.net.nz (Nick Roberts)
> 
> I've just committed the part that breaks the node up into four smaller ones
> with a shorter node name as you suggested (Asynchronous and non-stop modes).

Thank you.