Re: Better MI memory commands

[Eli Zaretskii <eliz@gnu.org>]

> From: Vladimir Prus <vladimir@codesourcery.com>
> 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 <vladimir@codesourcery.com>
> > > 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.