From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 5702 invoked by alias); 12 Aug 2010 17:04:47 -0000 Received: (qmail 5601 invoked by uid 22791); 12 Aug 2010 17:04:43 -0000 X-SWARE-Spam-Status: No, hits=0.2 required=5.0 tests=AWL,BAYES_20,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mtaout20.012.net.il (HELO mtaout20.012.net.il) (80.179.55.166) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 12 Aug 2010 17:04:35 +0000 Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0L7100G00TZNFU00@a-mtaout20.012.net.il> for gdb-patches@sources.redhat.com; Thu, 12 Aug 2010 20:04:33 +0300 (IDT) Received: from HOME-C4E4A596F7 ([77.126.102.143]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0L7100F94U3IQGB0@a-mtaout20.012.net.il>; Thu, 12 Aug 2010 20:04:31 +0300 (IDT) Date: Thu, 12 Aug 2010 17:04:00 -0000 From: Eli Zaretskii Subject: Re: Better MI memory commands In-reply-to: <201008121125.02659.vladimir@codesourcery.com> To: Vladimir Prus Cc: gdb-patches@sources.redhat.com Reply-to: Eli Zaretskii Message-id: <83d3tnvk2j.fsf@gnu.org> References: <201006251232.55281.vladimir@codesourcery.com> <201008111637.49621.vladimir@codesourcery.com> <83fwyluj0q.fsf@gnu.org> <201008121125.02659.vladimir@codesourcery.com> 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: 2010-08/txt/msg00178.txt.bz2 > From: Vladimir Prus > Date: Thu, 12 Aug 2010 11:25:02 +0400 > Cc: gdb-patches@sources.redhat.com > > On Wednesday 11 August 2010 22:00:21 Eli Zaretskii wrote: > > > > From: Vladimir Prus > > > Date: Wed, 11 Aug 2010 16:37:49 +0400 > > > Cc: gdb-patches@sources.redhat.com > > > > > > > > +The output of the command has a result record named @samp{memory}, > > > > ^^^^^^^^^^^^^^^^^^^ > > > > Perhaps "is a result record"? > > > > > > Nope. "result record" is actually a nonterminal in MI grammar, and output > > > of a command may have result records but is never a result record itself. > > > > > > > And what is the importance of naming > > > > this record `memory'? why is the name important here? > > > > > > Because for frontend to access a result record in a command output, it > > > has to know its name. > > > > Then perhaps > > > > The result record (@pxref{GDB/MI Result Records}) that is output of > > the command includes a field named @samp{memory} whose content is a > > list of tuples ... > > This is still not accurate. The output of the command is: > > - the character sequence "^done" > - zero, one, or more result results, separated with spaces. > > So, it's still an command output that "has" a result record named "memory" > as opposed to "result record .. is .. output of the command" This is a misunderstanding. In the text I suggested, "record that is output", the "output" part is a verb, not a noun. (I should have said "output by the command", though.) IOW, the text says that the command outputs some stuff, and part of that stuff is the result vector with a field named "memory". Saying "output has the result record" is not good English, because the result record is part of the output, not some attribute of it. I could try to be more accurate, if "that is output by the command" is not good enough, but please note that our current definition of what exactly is a "result record" is quite vague. In fact, we don't say what it is at all. For starters, it talks about "result indications": In addition to a number of out-of-band notifications, the response to a @sc{gdb/mi} command includes one of the following result indications: @table @code @findex ^done @item "^done" [ "," @var{results} ] The synchronous operation was successful, @code{@var{results}} are the return values. @item "^running" @findex ^running This result record is equivalent to @samp{^done}. Historically, it was output instead of @samp{^done} if the command has resumed the target. This behaviour is maintained for backward compatibility, but all frontends should treat @samp{^done} and @samp{^running} identically and rely on the @samp{*running} output record to determine which threads are resumed. My reading of this is that ^done, ^running, etc. _are_ examples of result records. By contrast, you say above that a result record is everything _after_ these indications. This inconsistency is the main reason why I deliberately left the text I suggested slightly vague. I'm open to other suggestions, but if we want to be rigorous, we should be more consistent than we are now regarding what exactly is a result record. > > > > > +@item @var{contents} > > > > > +The hex-encoded bytes to write. The size of this parameter determines > > > > > +how many bytes should be written.^^^^^^^^ > > > > > > > > You probably meant "the value", not "the size". > > > > > > Actually, "the size". A parameter is a string, a string has a size > > > > A string has a length, not size, so please use that. Actually, > > perhaps this sentence should be simply removed, as it seems to say > > something trivial, doesn't it? > > It's your call. It seemed to me that clarifying that there's no explicit option > for size might help users, who otherwise might decide the docs are > incompletely. I don't mind leaving it, if you think it's important.