[PATCH] GDB/MI documentation

[nickrob at snap dot net dot 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.  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