Re: [PATCH] GDB/MI documentation

[Vladimir Prus <vladimir@codesourcery.com>]

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