[doc] improve MI varobj introduction

[doc] improve MI varobj introduction

[Vladimir Prus]

[-- Attachment #1: Type: text/plain, Size: 846 bytes --]


Hello,
I think that at the moment, the introduction for varobj has a number of problems:

	- It does not mention update operation, which is 50% of varobjs relevance
	- It does not adequately describe hierarchy of varobjs, in particular that
	only leaf varobjs hold real data and can be manipulated.
	- There's a paragraph about hex/decimal format, which is minor
	detail and need not be mentioned.
	- The grammar of the text is overly complex sometimes.

The attached patch basically rewrites the introduction. The semantic of -var-update
is also clarified. The new introduction is basically one blob of text. There are places
where docbook <firstterm> would be appropriate, but it looks to be not supported
in info.

Comments?

- Volodya

	* gdb.texinfo (GDB/MI Variable Objects): Improve the 
	introduction.  Specify -var-update more exactly.

[-- Attachment #2: varobj_doc__gdb_mainline.diff --]
[-- Type: text/x-diff, Size: 4280 bytes --]

--- gdb/doc/gdb.texinfo	(/mirrors/gdb_mainline)	(revision 2727)
+++ gdb/doc/gdb.texinfo	(/patches/gdb/varobj_doc/gdb_mainline)	(revision 2727)
@@ -19570,26 +19570,36 @@ least, the following operations:
 
 @end ignore
 
-@subheading Introduction to Variable Objects in @sc{gdb/mi}
+@subheading Introduction to Variable Objects
 
 @cindex variable objects in @sc{gdb/mi}
-The basic idea behind variable objects is the creation 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.
-
-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.
-Appropriate language differences are handled for C, C@t{++} and Java.
-
-When returning the actual values of the objects, this facility allows
-for the individual selection of the display format used in the result
-creation.  It can be chosen among: binary, decimal, hexadecimal, octal
-and natural.  Natural refers to a default format automatically
-chosen based on the variable type (like decimal for an @code{int}, hex
-for pointers, etc.).
+
+Variable object is MI interface to work with expressions.  When
+creating a variable object, a frontend specifies the name of
+the variable object and an expression in the debugged program.
+Such expression can be a simple variable, or it can be an arbitrary
+complex expression, and can even involve CPU registers.  After
+creating a variable object, a frontend can invoke other variable
+object operations -- for example to obtain or change the value of
+a variable object, or to change format.
+
+Variable objects have hierarchical structure.  Any variable object
+that corresponds to a composite type, such as structure in C, has
+a number of child variable objects, for example corresponding to each
+element of a structure.  Child variable objects can children themself,
+util we reach leaf variable objects of built-in types.
+
+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
+obtained for a non-leaf variable object, but its generally a string
+that only indicates the type of the object, and does not list its
+content.  Assignment to a non-leaf variable object is not allowed.
+ 
+A frontend need not read the values of all variable objects each time
+the program stops.  Instead, MI provides update command that lists all
+variable objects which values has changed since the last update
+operation.  This considerably reduces the amount of data that must
+be transferred to the frontend.
 
 The following is the complete set of @sc{gdb/mi} operations defined to
 access this functionality:
@@ -19888,12 +19898,19 @@ subsequent @code{-var-update} list.
  -var-update [@var{print-values}] @{@var{name} | "*"@}
 @end smallexample
 
-Update the value of the variable object @var{name} by evaluating its
-expression after fetching all the new values from memory or registers.
-A @samp{*} causes all existing variable objects to be updated.  The
-option @var{print-values} determines whether names both and values, or
-just names are printed in the manner described for
-@code{-var-list-children} (@pxref{-var-list-children}).
+Reevaluate the expressions corresponding to the variable object
+@var{name} and all its direct and indirect children, and return the
+list of variable object which values has changed as the result. Here,
+``changed'' means that the result of @code{-var-evaluate-expression} before
+and after the @code{-var-update} is different.  If @samp{*} is used
+as the variable object names, all existing variable objects are
+updated.  The option @var{print-values} determines whether both names 
+and values, or just names are printed.  The possible values of
+this options are the same as for @code{-var-list-children}
+(@pxref{-var-list-children}).  It is recommended to use the
+@samp{--all-values} option, to reduce the number of MI commands needed
+on each program stop.
+
 
 @subsubheading Example
 

Re: [doc] improve MI varobj introduction

[Nick Roberts]

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"

 > +obtained for a non-leaf variable object, but its generally a string
 > +that only indicates the type of the object, and does not list its
 > +content.  Assignment to a non-leaf variable object is not allowed.
 >
 > +A frontend need not read the values of all variable objects each time
 > +the program stops.  Instead, MI provides update command that lists all
 > +variable objects which values has changed since the last update
 > +operation.  This considerably reduces the amount of data that must
 > +be transferred to the frontend.

and this:

 > +                                                   and return the
 > +list of variable object which values has changed as the result.

                                                       and return the
    list of variable object whose values have changed.

However, I'm not sure that the replaced parts of the introduction are an
improvement, or that elaborating on the PRINT-VALUES option is a good idea.

Also expanding the introduction allows the removal of the summary of commands
which just duplicates what comes after.

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

Re: [doc] improve MI varobj introduction

[Vladimir Prus]

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);

>  > +obtained for a non-leaf variable object, but its generally a string
>  > +that only indicates the type of the object, and does not list its
>  > +content.  Assignment to a non-leaf variable object is not allowed.
>  >
>  > +A frontend need not read the values of all variable objects each time
>  > +the program stops.  Instead, MI provides update command that lists all
>  > +variable objects which values has changed since the last update
>  > +operation.  This considerably reduces the amount of data that must
>  > +be transferred to the frontend.
> 
> and this:
> 
>  > +                                                   and return the
>  > +list of variable object which values has changed as the result.
> 
>                                                        and return the
>     list of variable object whose values have changed.

Ok.

> However, I'm not sure that the replaced parts of the introduction are an
> improvement, 

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.

	-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.

	-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.


> 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.

> 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?

- Volodya


> 

Re: [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

Re: [doc] improve MI varobj introduction

[Vladimir Prus]

On Wednesday 20 December 2006 23:48, Nick Roberts wrote:
> 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 

Exactly. Therefore, you cannot pass integer value to it. All of MI is purely
text base, so the value you pass to -var-assign is a string. Even if frontend
has

	int value;

is has to convert it to string before passing to MI. That's why I say the value is
assigned from a string.

>  > 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.

That's not my reading of the above. To say that, the sentence must be:

	Variable objects are only supported for programs in C C@t{++} and Java.

As written, we know that some unknown differences between C, C++ and Java are
handled. One has no clue if Pascal is not supported, or appropriate differences with
Pascal are not handled, or maybe if Pascal has no appropriate differences to begin with.

> 
>  > > 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.

I think it's fine that folks hacking on MI have better first approximation to the right
way of using it than somebody how just opened the docs do implement a new
frontend. So, recommending something is quite reasonable.

>  > > 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...

I don't have an opinion. If the list was clickable, it would be useful, but it's not,
and I don't know if info can be persuaded that make them clickable (and not
very interested to change that, anyway)

- Volodya




> 

Re: [doc] improve MI varobj introduction

[Daniel Jacobowitz]

On Thu, Dec 21, 2006 at 09:14:43AM +0300, Vladimir Prus wrote:
> >  > > 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...
> 
> I don't have an opinion. If the list was clickable, it would be useful, but it's not,
> and I don't know if info can be persuaded that make them clickable (and not
> very interested to change that, anyway)

It can be, if you use @xref or @pxref.  There's plenty of examples in
the manual.  They're already marked with @findex, which I think
suffices - try @xref{-var-list-children}.

I didn't really follow this thread, but I would recommend posting a
revised version of the patch with any changes when you're ready to.

-- 
Daniel Jacobowitz
CodeSourcery

Re: [doc] improve MI varobj introduction

[Vladimir Prus]

On Tuesday 26 December 2006 18:32, Daniel Jacobowitz wrote:
> On Thu, Dec 21, 2006 at 09:14:43AM +0300, Vladimir Prus wrote:
> > >  > > 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...
> > 
> > I don't have an opinion. If the list was clickable, it would be useful, but it's not,
> > and I don't know if info can be persuaded that make them clickable (and not
> > very interested to change that, anyway)
> 
> It can be, if you use @xref or @pxref.  There's plenty of examples in
> the manual.  They're already marked with @findex, which I think
> suffices - try @xref{-var-list-children}.

Okay. Anyway, this is a separate change.

> I didn't really follow this thread, but I would recommend posting a
> revised version of the patch with any changes when you're ready to.

I don't have any planned changes so far, except for three-word editorial change
suggested by Nick.

- Volodya

 

Re: [doc] improve MI varobj introduction

[Daniel Jacobowitz]

On Tue, Dec 26, 2006 at 06:51:54PM +0300, Vladimir Prus wrote:
> > I didn't really follow this thread, but I would recommend posting a
> > revised version of the patch with any changes when you're ready to.
> 
> I don't have any planned changes so far, except for three-word editorial change
> suggested by Nick.

Right, but a final patch is still helpful - it lets a reviewer
(probably Eli) look at what you have without having to follow the
discussion.

-- 
Daniel Jacobowitz
CodeSourcery

Re: [doc] improve MI varobj introduction

[Vladimir Prus]

Daniel Jacobowitz wrote:

> On Tue, Dec 26, 2006 at 06:51:54PM +0300, Vladimir Prus wrote:
>> > I didn't really follow this thread, but I would recommend posting a
>> > revised version of the patch with any changes when you're ready to.
>> 
>> I don't have any planned changes so far, except for three-word editorial
>> change suggested by Nick.
> 
> Right, but a final patch is still helpful - it lets a reviewer
> (probably Eli) look at what you have without having to follow the
> discussion.

Here's the final patch.

- Volodya

Re: [doc] improve MI varobj introduction

[Vladimir Prus]

[-- Attachment #1: Type: text/plain, Size: 652 bytes --]

Daniel Jacobowitz wrote:

> On Tue, Dec 26, 2006 at 06:51:54PM +0300, Vladimir Prus wrote:
>> > I didn't really follow this thread, but I would recommend posting a
>> > revised version of the patch with any changes when you're ready to.
>> 
>> I don't have any planned changes so far, except for three-word editorial
>> change suggested by Nick.
> 
> Right, but a final patch is still helpful - it lets a reviewer
> (probably Eli) look at what you have without having to follow the
> discussion.

Here's the final patch.

- Volodya


        * gdb.texinfo (GDB/MI Variable Objects): Improve the 
        introduction.  Specify -var-update more exactly.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: varobj_doc__gdb_mainline.diff --]
[-- Type: text/x-diff; name="varobj_doc__gdb_mainline.diff", Size: 4687 bytes --]

--- gdb/doc/gdb.texinfo	(/patches/gdb/mi_inline_tests/gdb_mainline)	(revision 3043)
+++ gdb/doc/gdb.texinfo	(/patches/gdb/varobj_doc/gdb_mainline)	(revision 3043)
@@ -19570,26 +19570,36 @@ least, the following operations:
 
 @end ignore
 
-@subheading Introduction to Variable Objects in @sc{gdb/mi}
+@subheading Introduction to Variable Objects
 
 @cindex variable objects in @sc{gdb/mi}
-The basic idea behind variable objects is the creation 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.
-
-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.
-Appropriate language differences are handled for C, C@t{++} and Java.
-
-When returning the actual values of the objects, this facility allows
-for the individual selection of the display format used in the result
-creation.  It can be chosen among: binary, decimal, hexadecimal, octal
-and natural.  Natural refers to a default format automatically
-chosen based on the variable type (like decimal for an @code{int}, hex
-for pointers, etc.).
+
+Variable object is MI interface to work with expressions.  When
+creating a variable object, a frontend specifies the name of
+the variable object and an expression in the debugged program.
+Such expression can be a simple variable, or it can be an arbitrary
+complex expression, and can even involve CPU registers.  After
+creating a variable object, the frontend can invoke other variable
+object operations -- for example to obtain or change the value of
+a variable object, or to change display format.
+
+Variable objects have hierarchical structure.  Any variable object
+that corresponds to a composite type, such as structure in C, has
+a number of child variable objects, for example corresponding to each
+element of a structure.  Child variable objects can children themself,
+util we reach leaf variable objects of built-in types.
+
+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
+obtained for a non-leaf variable object, but its generally a string
+that only indicates the type of the object, and does not list its
+content.  Assignment to a non-leaf variable object is not allowed.
+ 
+A frontend need not read the values of all variable objects each time
+the program stops.  Instead, MI provides update command that lists all
+variable objects which values has changed since the last update
+operation.  This considerably reduces the amount of data that must
+be transferred to the frontend.
 
 The following is the complete set of @sc{gdb/mi} operations defined to
 access this functionality:
@@ -19888,12 +19898,19 @@ subsequent @code{-var-update} list.
  -var-update [@var{print-values}] @{@var{name} | "*"@}
 @end smallexample
 
-Update the value of the variable object @var{name} by evaluating its
-expression after fetching all the new values from memory or registers.
-A @samp{*} causes all existing variable objects to be updated.  The
-option @var{print-values} determines whether names both and values, or
-just names are printed in the manner described for
-@code{-var-list-children} (@pxref{-var-list-children}).
+Reevaluate the expressions corresponding to the variable object
+@var{name} and all its direct and indirect children, and return the
+list of variable objects which values have changed. Here,
+``changed'' means that the result of @code{-var-evaluate-expression} before
+and after the @code{-var-update} is different.  If @samp{*} is used
+as the variable object names, all existing variable objects are
+updated.  The option @var{print-values} determines whether both names 
+and values, or just names are printed.  The possible values of
+this options are the same as for @code{-var-list-children}
+(@pxref{-var-list-children}).  It is recommended to use the
+@samp{--all-values} option, to reduce the number of MI commands needed
+on each program stop.
+
 
 @subsubheading Example
 

Property changes on: 
___________________________________________________________________
Name: csl:base
 -/all/patches/gdb/mi_continue_to/gdb_mainline
 +/all/patches/gdb/mi_inline_tests/gdb_mainline
Name: svk:merge
  d48a11ec-ee1c-0410-b3f5-c20844f99675:/patches/gdb/mi_continue_to/gdb_mainline:2736
 +d48a11ec-ee1c-0410-b3f5-c20844f99675:/patches/gdb/mi_inline_tests/gdb_mainline:3041

Re: [doc] improve MI varobj introduction

[Eli Zaretskii]

> From: Vladimir Prus <ghost@cs.msu.su>
> Date: Thu, 04 Jan 2007 21:23:00 +0300
> 
> Here's the final patch.

Thanks.  I have a few comments and suggestions.

> -When returning the actual values of the objects, this facility allows
> -for the individual selection of the display format used in the result
> -creation.  It can be chosen among: binary, decimal, hexadecimal, octal
> -and natural.  Natural refers to a default format automatically
> -chosen based on the variable type (like decimal for an @code{int}, hex
> -for pointers, etc.).

This fragment was removed, but the new text doesn't mention this
feature at all.  Was the old text plain wrong (i.e. there's no such
feature)?  If the feature does exist, I think it should be mentioned.

> +Variable object is MI interface to work with expressions.

Perhaps it's an interface to work with named expressions, because I
believe you don't need anything to work with just expressions, do you?

> +object operations -- for example to obtain or change the value of

Please use 3 dashes in a row, and without blanks on either side, to
get an em-dash in the printed version.

> +Variable objects have hierarchical structure.

The original text said it was a tree structure.  I suggest to add the
``tree'' part back (i.e. ``hierarchical tree structure''), as
otherwise it is not clear why you talk about leaf variables further
down.

>                     Child variable objects can children themself,
> +util we reach leaf variable objects of built-in types. ^^^^^^^^
   ^^^^
Typos, and also something's wrong with this sentence in general.

> +obtained for a non-leaf variable object, but its generally a string
                                                ^^^
"it's"

> +that only indicates the type of the object, and does not list its
> +content.
   ^^^^^^^
"contents".

> +A frontend need not read the values of all variable objects each time
              ^^^^^^^^
"does not need"

> +the program stops.  Instead, MI provides update command that lists all
                                            ^^^^^^^^^^^^^^
"an update command"

> +variable objects which values has changed since the last update
                    ^^^^^^^^^^^^
"whose values"

> +list of variable objects which values have changed. Here,
                            ^^^^^^^^^^^^
Ditto.

Re: [doc] improve MI varobj introduction

[Vladimir Prus]

[-- Attachment #1: Type: text/plain, Size: 2277 bytes --]

On Friday 05 January 2007 00:48, Eli Zaretskii wrote:
> > From: Vladimir Prus <ghost@cs.msu.su>
> > Date: Thu, 04 Jan 2007 21:23:00 +0300
> > 
> > Here's the final patch.
> 
> Thanks.  I have a few comments and suggestions.
> 
> > -When returning the actual values of the objects, this facility allows
> > -for the individual selection of the display format used in the result
> > -creation.  It can be chosen among: binary, decimal, hexadecimal, octal
> > -and natural.  Natural refers to a default format automatically
> > -chosen based on the variable type (like decimal for an @code{int}, hex
> > -for pointers, etc.).
> 
> This fragment was removed, but the new text doesn't mention this
> feature at all.  Was the old text plain wrong (i.e. there's no such
> feature)?  If the feature does exist, I think it should be mentioned.

I did remove it because detailed explanation about display format are too
detailed for the introduction -- it's not a core functionality. The new doc mention
that display format can be changed, and I've just added more docs to
-var-set-format and -var-evaluate-expression so that essential parts of the
above paragraphs are not lost.

> 
> > +Variable object is MI interface to work with expressions.
> 
> Perhaps it's an interface to work with named expressions, because I
> believe you don't need anything to work with just expressions, do you?

Although you can use -data-evaluate-expression, using varobj is the recommended
way. I don't think "named expressions" is the key here -- if MI was an interface
in any object oriented language, you would not need varobj name at all. But since MI
is pipe interface, you need some opaque token instead of object reference in a 
programming language. So no fundamentally named expression are involved.
How about:

	Variable object is the recommended MI interface to work with expressions.

> >                     Child variable objects can children themself,
> > +util we reach leaf variable objects of built-in types. ^^^^^^^^
>    ^^^^
> Typos, and also something's wrong with this sentence in general.

Changed to:


	Child variable objects can themself have children,
	util we reach leaf variable objects of built-in types.

Revised patch attached -- hopefully better this time.

- Volodya


[-- Attachment #2: varobj_doc__gdb_mainline.diff --]
[-- Type: text/x-diff, Size: 5628 bytes --]

--- gdb/doc/gdb.texinfo	(/patches/gdb/mi_inline_tests/gdb_mainline)	(revision 3054)
+++ gdb/doc/gdb.texinfo	(/patches/gdb/varobj_doc/gdb_mainline)	(revision 3054)
@@ -19570,26 +19570,36 @@ least, the following operations:
 
 @end ignore
 
-@subheading Introduction to Variable Objects in @sc{gdb/mi}
+@subheading Introduction to Variable Objects
 
 @cindex variable objects in @sc{gdb/mi}
-The basic idea behind variable objects is the creation 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.
-
-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.
-Appropriate language differences are handled for C, C@t{++} and Java.
-
-When returning the actual values of the objects, this facility allows
-for the individual selection of the display format used in the result
-creation.  It can be chosen among: binary, decimal, hexadecimal, octal
-and natural.  Natural refers to a default format automatically
-chosen based on the variable type (like decimal for an @code{int}, hex
-for pointers, etc.).
+
+Variable object is the recommended MI interface to work with expressions.  
+When creating a variable object, a frontend specifies the name of
+the variable object and an expression in the debugged program.
+Such expression can be a simple variable, or it can be an arbitrary
+complex expression, and can even involve CPU registers.  After
+creating a variable object, the frontend can invoke other variable
+object operations---for example to obtain or change the value of
+a variable object, or to change display format.
+
+Variable objects have hierarchical tree structure.  Any variable object
+that corresponds to a composite type, such as structure in C, has
+a number of child variable objects, for example corresponding to each
+element of a structure.  Child variable objects can themself have children,
+util we reach leaf variable objects of built-in types.
+
+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
+obtained for a non-leaf variable object, but it's generally a string
+that only indicates the type of the object, and does not list its
+contents.  Assignment to a non-leaf variable object is not allowed.
+ 
+A frontend does not need to read the values of all variable objects each time
+the program stops.  Instead, MI provides an update command that lists all
+variable objects whose values has changed since the last update
+operation.  This considerably reduces the amount of data that must
+be transferred to the frontend.
 
 The following is the complete set of @sc{gdb/mi} operations defined to
 access this functionality:
@@ -19712,6 +19722,12 @@ The syntax for the @var{format-spec} is 
  @{binary | decimal | hexadecimal | octal | natural@}
 @end smallexample
 
+The natural format is the default format choosen automatically
+based on the variable type (like decimal for an @code{int}, hex
+for pointers, etc.).
+
+For a variable with children, the format is set only on the 
+variable itself, and the children are not affected.  
 
 @subheading The @code{-var-show-format} Command
 @findex -var-show-format
@@ -19843,8 +19859,8 @@ where @var{attr} is @code{@{ @{ editable
 @end smallexample
 
 Evaluates the expression that is represented by the specified variable
-object and returns its value as a string in the current format specified
-for the object:
+object and returns its value as a string.  The format of the
+string can be changed using the @code{-var-set-format} command.
 
 @smallexample
  value=@var{value}
@@ -19888,12 +19904,19 @@ subsequent @code{-var-update} list.
  -var-update [@var{print-values}] @{@var{name} | "*"@}
 @end smallexample
 
-Update the value of the variable object @var{name} by evaluating its
-expression after fetching all the new values from memory or registers.
-A @samp{*} causes all existing variable objects to be updated.  The
-option @var{print-values} determines whether names both and values, or
-just names are printed in the manner described for
-@code{-var-list-children} (@pxref{-var-list-children}).
+Reevaluate the expressions corresponding to the variable object
+@var{name} and all its direct and indirect children, and return the
+list of variable objects whose values have changed. Here,
+``changed'' means that the result of @code{-var-evaluate-expression} before
+and after the @code{-var-update} is different.  If @samp{*} is used
+as the variable object names, all existing variable objects are
+updated.  The option @var{print-values} determines whether both names 
+and values, or just names are printed.  The possible values of
+this options are the same as for @code{-var-list-children}
+(@pxref{-var-list-children}).  It is recommended to use the
+@samp{--all-values} option, to reduce the number of MI commands needed
+on each program stop.
+
 
 @subsubheading Example
 

Property changes on: 
___________________________________________________________________
Name: csl:base
 -/all/patches/gdb/mi_continue_to/gdb_mainline
 +/all/patches/gdb/mi_inline_tests/gdb_mainline
Name: svk:merge
  d48a11ec-ee1c-0410-b3f5-c20844f99675:/patches/gdb/mi_continue_to/gdb_mainline:2736
 +d48a11ec-ee1c-0410-b3f5-c20844f99675:/patches/gdb/mi_inline_tests/gdb_mainline:3051

Re: [doc] improve MI varobj introduction

[Eli Zaretskii]

> From: Vladimir Prus <ghost@cs.msu.su>
> Date: Fri, 5 Jan 2007 11:39:09 +0300
> Cc: drow@false.org,
>  gdb-patches@sources.redhat.com
> 
> > > +Variable object is MI interface to work with expressions.
> > 
> > Perhaps it's an interface to work with named expressions, because I
> > believe you don't need anything to work with just expressions, do you?
> 
> Although you can use -data-evaluate-expression, using varobj is the recommended
> way. I don't think "named expressions" is the key here -- if MI was an interface
> in any object oriented language, you would not need varobj name at all. But since MI
> is pipe interface, you need some opaque token instead of object reference in a 
> programming language. So no fundamentally named expression are involved.
> How about:
> 
> 	Variable object is the recommended MI interface to work with expressions.

This doesn't give a clue why it is the recommended way.  I have
another suggestion, based on what you explained above:

  Variable objects are an MI convenience feature to reference
  expressions.  When a frontend creates a variable object, it
  specifies a name for an arbitrary expression in the debugged
  program.  That name can henceforth be used as an opaque handle for
  the expression.  The expression can be a simple variable, or it can
  be ...

Okay?

> > >                     Child variable objects can children themself,
> > > +util we reach leaf variable objects of built-in types. ^^^^^^^^
> >    ^^^^
> > Typos, and also something's wrong with this sentence in general.
> 
> Changed to:
> 
> 
> 	Child variable objects can themself have children,
> 	util we reach leaf variable objects of built-in types.

Hmmm... something is still wrong.  I think you meant this:

  A child variable object can itself have children, until we reach
  leaf variable objects which have built-in types.

> Revised patch attached -- hopefully better this time.

Yes, thanks.  The above two gotchas are the only things that need to
be taken care of.

Re: [doc] improve MI varobj introduction

[Vladimir Prus]

Eli Zaretskii wrote:

>> From: Vladimir Prus <ghost@cs.msu.su>
>> Date: Fri, 5 Jan 2007 11:39:09 +0300
>> Cc: drow@false.org,
>>  gdb-patches@sources.redhat.com
>> 
>> > > +Variable object is MI interface to work with expressions.
>> > 
>> > Perhaps it's an interface to work with named expressions, because I
>> > believe you don't need anything to work with just expressions, do you?
>> 
>> Although you can use -data-evaluate-expression, using varobj is the
>> recommended way. I don't think "named expressions" is the key here -- if
>> MI was an interface in any object oriented language, you would not need
>> varobj name at all. But since MI is pipe interface, you need some opaque
>> token instead of object reference in a programming language. So no
>> fundamentally named expression are involved. How about:
>> 
>> Variable object is the recommended MI interface to work with expressions.
> 
> This doesn't give a clue why it is the recommended way.  I have
> another suggestion, based on what you explained above:
> 
>   Variable objects are an MI convenience feature to reference
>   expressions.  When a frontend creates a variable object, it
>   specifies a name for an arbitrary expression in the debugged
>   program.  That name can henceforth be used as an opaque handle for
>   the expression.  The expression can be a simple variable, or it can
>   be ...
> 
> Okay?

You're right that my text did not say why it's recommended, but I think the
above is also not accurate. "convenient feature to reference expressions"
is not quite right -- it sounds like varobj is just a method to create
aliases for expression, and varobjs are much more than that. How about:

        Variable objects are "object-oriented" MI interface for
        examining and changing values of expressions. Unlike some other
        MI interfaces that work with expressions, variable objects are
        specifically designed for simple and efficient 
        presentation in the frontend. A variable object is identified
        by string name. When a variable object is created, the
        frontend specifies the expression for that variable object.
        The expression can be a simple variable ........

        
>> > >                     Child variable objects can children themself,
>> > > +util we reach leaf variable objects of built-in types. ^^^^^^^^
>> >    ^^^^
>> > Typos, and also something's wrong with this sentence in general.
>> 
>> Changed to:
>> 
>> 
>> Child variable objects can themself have children,
>> util we reach leaf variable objects of built-in types.
> 
> Hmmm... something is still wrong.  I think you meant this:
> 
>   A child variable object can itself have children, until we reach
>   leaf variable objects which have built-in types.

That looks fine for me, but should not we have a command before "which"?
Otherwise, it sounds like there are two kind of leaf variable objects --
those of builtin types and those of non-builtin types.

- Volodya

Re: [doc] improve MI varobj introduction

[Eli Zaretskii]

> From: Vladimir Prus <ghost@cs.msu.su>
> Date: Mon, 08 Jan 2007 17:49:12 +0300
> > 
> >   Variable objects are an MI convenience feature to reference
> >   expressions.  When a frontend creates a variable object, it
> >   specifies a name for an arbitrary expression in the debugged
> >   program.  That name can henceforth be used as an opaque handle for
> >   the expression.  The expression can be a simple variable, or it can
> >   be ...
> > 
> > Okay?
> 
> You're right that my text did not say why it's recommended, but I think the
> above is also not accurate. "convenient feature to reference expressions"
> is not quite right -- it sounds like varobj is just a method to create
> aliases for expression, and varobjs are much more than that. How about:
> 
>         Variable objects are "object-oriented" MI interface for
>         examining and changing values of expressions. Unlike some other
>         MI interfaces that work with expressions, variable objects are
>         specifically designed for simple and efficient 
>         presentation in the frontend. A variable object is identified
>         by string name. When a variable object is created, the
>         frontend specifies the expression for that variable object.
>         The expression can be a simple variable ........

The first two sentences sound to me more like advertisement, but if
you feel you need to say that, fine.

> >   A child variable object can itself have children, until we reach
> >   leaf variable objects which have built-in types.
> 
> That looks fine for me, but should not we have a command before "which"?
> Otherwise, it sounds like there are two kind of leaf variable objects --
> those of builtin types and those of non-builtin types.

I just tried to make a minimal modification of your text.  Perhaps a
better variant is this:

  A child variable object can itself have children, recursively.
  Recursion ends when we reach leaf variable objects that have
  built-in types.

Re: [doc] improve MI varobj introduction

[Vladimir Prus]

[-- Attachment #1: Type: text/plain, Size: 2611 bytes --]

Eli Zaretskii wrote:

>> From: Vladimir Prus <ghost@cs.msu.su>
>> Date: Mon, 08 Jan 2007 17:49:12 +0300
>> > 
>> >   Variable objects are an MI convenience feature to reference
>> >   expressions.  When a frontend creates a variable object, it
>> >   specifies a name for an arbitrary expression in the debugged
>> >   program.  That name can henceforth be used as an opaque handle for
>> >   the expression.  The expression can be a simple variable, or it can
>> >   be ...
>> > 
>> > Okay?
>> 
>> You're right that my text did not say why it's recommended, but I think
>> the above is also not accurate. "convenient feature to reference
>> expressions" is not quite right -- it sounds like varobj is just a method
>> to create aliases for expression, and varobjs are much more than that.
>> How about:
>> 
>>         Variable objects are "object-oriented" MI interface for
>>         examining and changing values of expressions. Unlike some other
>>         MI interfaces that work with expressions, variable objects are
>>         specifically designed for simple and efficient
>>         presentation in the frontend. A variable object is identified
>>         by string name. When a variable object is created, the
>>         frontend specifies the expression for that variable object.
>>         The expression can be a simple variable ........
> 
> The first two sentences sound to me more like advertisement, but if
> you feel you need to say that, fine.

Yes, I feel we need to emphasise that varobjs is what folks should use,
not some convenience that might be ignored.

> 
>> >   A child variable object can itself have children, until we reach
>> >   leaf variable objects which have built-in types.
>> 
>> That looks fine for me, but should not we have a command before "which"?
>> Otherwise, it sounds like there are two kind of leaf variable objects --
>> those of builtin types and those of non-builtin types.
> 
> I just tried to make a minimal modification of your text.  Perhaps a
> better variant is this:
> 
>   A child variable object can itself have children, recursively.
>   Recursion ends when we reach leaf variable objects that have
>   built-in types.

Again, "that have built-in types" sounds to me like restrictive clause,
as if there are leaf variables that don't have builtin-types. What about:

        Recursion ends when we reach leaf variable objects, which always have
        built-in types.

I attach the revised patch, incorporating those two corrections,
and using the above last sentence. Is it OK, or would you prefer 
your original sentence? 

Thanks,
Volodya






[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: varobj_doc__gdb_mainline.diff --]
[-- Type: text/x-diff; name="varobj_doc__gdb_mainline.diff", Size: 5883 bytes --]

--- gdb/doc/gdb.texinfo	(/patches/gdb/mi_inline_tests/gdb_mainline)	(revision 3074)
+++ gdb/doc/gdb.texinfo	(/patches/gdb/varobj_doc/gdb_mainline)	(revision 3074)
@@ -19570,26 +19570,40 @@ least, the following operations:
 
 @end ignore
 
-@subheading Introduction to Variable Objects in @sc{gdb/mi}
+@subheading Introduction to Variable Objects
 
 @cindex variable objects in @sc{gdb/mi}
-The basic idea behind variable objects is the creation 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.
-
-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.
-Appropriate language differences are handled for C, C@t{++} and Java.
-
-When returning the actual values of the objects, this facility allows
-for the individual selection of the display format used in the result
-creation.  It can be chosen among: binary, decimal, hexadecimal, octal
-and natural.  Natural refers to a default format automatically
-chosen based on the variable type (like decimal for an @code{int}, hex
-for pointers, etc.).
+
+Variable objects are "object-oriented" MI interface for examining and
+changing values of expressions.  Unlike some other MI interfaces that
+work with expressions, variable objects are specifically designed for
+simple and efficient presentation in the frontend.  A variable object
+is identified by string name.  When a variable object is created, the
+frontend specifies the expression for that variable object.  The
+expression can be a simple variable, or it can be an arbitrary complex
+expression, and can even involve CPU registers.  After creating a
+variable object, the frontend can invoke other variable object
+operations---for example to obtain or change the value of a variable
+object, or to change display format.
+
+Variable objects have hierarchical tree structure.  Any variable object
+that corresponds to a composite type, such as structure in C, has
+a number of child variable objects, for example corresponding to each
+element of a structure.  A child variable object can itself have 
+children, recursively.  Recursion ends when we reach 
+leaf variable objects, which always have built-in types.
+
+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
+obtained for a non-leaf variable object, but it's generally a string
+that only indicates the type of the object, and does not list its
+contents.  Assignment to a non-leaf variable object is not allowed.
+ 
+A frontend does not need to read the values of all variable objects each time
+the program stops.  Instead, MI provides an update command that lists all
+variable objects whose values has changed since the last update
+operation.  This considerably reduces the amount of data that must
+be transferred to the frontend.
 
 The following is the complete set of @sc{gdb/mi} operations defined to
 access this functionality:
@@ -19712,6 +19726,12 @@ The syntax for the @var{format-spec} is 
  @{binary | decimal | hexadecimal | octal | natural@}
 @end smallexample
 
+The natural format is the default format choosen automatically
+based on the variable type (like decimal for an @code{int}, hex
+for pointers, etc.).
+
+For a variable with children, the format is set only on the 
+variable itself, and the children are not affected.  
 
 @subheading The @code{-var-show-format} Command
 @findex -var-show-format
@@ -19843,8 +19863,8 @@ where @var{attr} is @code{@{ @{ editable
 @end smallexample
 
 Evaluates the expression that is represented by the specified variable
-object and returns its value as a string in the current format specified
-for the object:
+object and returns its value as a string.  The format of the
+string can be changed using the @code{-var-set-format} command.
 
 @smallexample
  value=@var{value}
@@ -19888,12 +19908,19 @@ subsequent @code{-var-update} list.
  -var-update [@var{print-values}] @{@var{name} | "*"@}
 @end smallexample
 
-Update the value of the variable object @var{name} by evaluating its
-expression after fetching all the new values from memory or registers.
-A @samp{*} causes all existing variable objects to be updated.  The
-option @var{print-values} determines whether names both and values, or
-just names are printed in the manner described for
-@code{-var-list-children} (@pxref{-var-list-children}).
+Reevaluate the expressions corresponding to the variable object
+@var{name} and all its direct and indirect children, and return the
+list of variable objects whose values have changed. Here,
+``changed'' means that the result of @code{-var-evaluate-expression} before
+and after the @code{-var-update} is different.  If @samp{*} is used
+as the variable object names, all existing variable objects are
+updated.  The option @var{print-values} determines whether both names 
+and values, or just names are printed.  The possible values of
+this options are the same as for @code{-var-list-children}
+(@pxref{-var-list-children}).  It is recommended to use the
+@samp{--all-values} option, to reduce the number of MI commands needed
+on each program stop.
+
 
 @subsubheading Example
 

Property changes on: 
___________________________________________________________________
Name: csl:base
 -/all/patches/gdb/mi_continue_to/gdb_mainline
 +/all/patches/gdb/mi_inline_tests/gdb_mainline
Name: svk:merge
  d48a11ec-ee1c-0410-b3f5-c20844f99675:/patches/gdb/mi_continue_to/gdb_mainline:2736
 +d48a11ec-ee1c-0410-b3f5-c20844f99675:/patches/gdb/mi_inline_tests/gdb_mainline:3051

Re: [doc] improve MI varobj introduction

[Eli Zaretskii]

> From: Vladimir Prus <ghost@cs.msu.su>
> Date: Mon, 08 Jan 2007 23:08:33 +0300
> 
> Again, "that have built-in types" sounds to me like restrictive clause,
> as if there are leaf variables that don't have builtin-types. What about:
> 
>         Recursion ends when we reach leaf variable objects, which always have
>         built-in types.

Fine with me.  (I don't really see the difference between this
sentence and what I wrote.)

> I attach the revised patch, incorporating those two corrections,
> and using the above last sentence. Is it OK, or would you prefer 
> your original sentence? 

It's okay, thanks.