From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 19760 invoked by alias); 13 May 2009 11:59:31 -0000 Received: (qmail 19737 invoked by uid 22791); 13 May 2009 11:59:30 -0000 X-SWARE-Spam-Status: No, hits=-2.9 required=5.0 tests=AWL,BAYES_00,J_CHICKENPOX_37,RCVD_IN_DNSWL_LOW,SPF_HELO_PASS,SPF_PASS X-Spam-Check-By: sourceware.org Received: from main.gmane.org (HELO ciao.gmane.org) (80.91.229.2) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Wed, 13 May 2009 11:59:23 +0000 Received: from list by ciao.gmane.org with local (Exim 4.43) id 1M4D7J-0004Rs-0r for gdb-patches@sources.redhat.com; Wed, 13 May 2009 11:59:21 +0000 Received: from h86-62-88-129.ln.rinet.ru ([86.62.88.129]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Wed, 13 May 2009 11:59:21 +0000 Received: from vladimir by h86-62-88-129.ln.rinet.ru with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Wed, 13 May 2009 11:59:21 +0000 To: gdb-patches@sources.redhat.com From: Vladimir Prus Subject: Re: [PATCH] GDB/MI documentation Date: Wed, 13 May 2009 11:59:00 -0000 Message-ID: References: <18954.41627.111280.24736@totara.tehura.co.nz> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8Bit User-Agent: KNode/0.10.9 X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2009-05/txt/msg00270.txt.bz2 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   > > * 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