[doc] improve MI varobj introduction

[Nick Roberts]

Vladimir Prus writes:
 > On Wednesday 20 December 2006 01:24, Nick Roberts wrote:
 > > 
 > > I think it's a good idea to add this.
 > > 
 > >  > +For a leaf variable object it is possible to obtain its value as a
 > >  > +string, or set the value from a string.  String value can be also
 > >                                     ^^^^^^
 > > -var-assign var1 8  <- not a string
 > > ^done,value="8"
 > 
 > Actually, it is. The entire MI interface is based on strings. You cannot do:
 > 
 > 	int value;
 > 	mi_assign("V", value);

I don't follow.  AFAICS there is no function mi_assign and the manual is
about the interface not GDB internals.

 > You mean the first two paragraphs? Let me go though them:
 > 
 > 	- The basic idea behind variable objects is the creation 
 > 
 > This passage is just awkward, if not grammatically wrong.
 > 
 >   of a named object 
 >   -to represent a variable, an expression, a memory location or even a CPU
 >   -register.  For each object created, a set of operations is available for 
 >   -examining or changing its properties.
 > 
 > "Examining or changing its properties" is very vague. This is the first
 > paragraph of the introduction to MI varobjs, it should explicitly say what
 > user might want to use them for -- and abstract "property" is not explicit
 > enough.

I had no problem when I first read it but in any case it's Eli's call.

 >   -Furthermore, complex data types, such as C structures, are represented
 >   -in a tree format.  For instance, the @code{struct} type variable is the
 >   -root and the children will represent the struct members.  If a child
 >   -is itself of a complex type, it will also have children of its own.
 >
 > This is not so bad, but it fails to describe important properties of this
 > tree -- namely that only leafs carry any data.

That's why I suggested _adding_ your paragraph.

 > 	-Appropriate language differences are handled for C, C@t{++} and Java.
 >
 > This sentence is content-free. It's pretty obvious that a debugger cannot be
 > language-agnostic, and it's not clear that "Appropriate" differences are
 > and why would I care.

It tells me variable objects might not work for other languages.

 > > or that elaborating on the PRINT-VALUES option is a good idea. 
 > 
 > You mean the suggestion to use --all-values. I think it's important
 > information, and given that we have just one MI doc document, it's natural
 > to include this information. MI docs presently have too little content, not
 > too much.

I don't think the manual should recommend ways to use MI commands.  I guess
it could say that 

   the @samp{--all-values} option reduces the number of MI commands needed +on
   each program stop.

but that should be obvious anyway and we're starting to guess how someone is
using MI.

 > > Also expanding the introduction allows the removal of the summary of
 > > commands which just duplicates what comes after.
 > 
 > I'm not sure -- which summaries can be removed now?

The list just after:

 The following is the complete set of GDB/MI operations...

-- 
Nick                                           http://www.inet.net.nz/~nickrob