gdb.texinfo patch for -var-list-children (2)

gdb.texinfo patch for -var-list-children (2)

[Chris Genly]

Description

The gdb documentation for the MI command -var-list-children does not
define the exp
result for a child.  Exp and other child results documented.

Sorry I didn't document this with the last patch.  But my
understanding of MI commands is still increasing.

Change log

2009-06-19  Chris Genly  <chris@genly.us>
	* doc/gdb.texinfo (GDB/MI Variable Objects): Document child
	definition in -var-list-children.  Added exp result for child.

Patch

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.600
diff -c -p -r1.600 gdb.texinfo
*** gdb.texinfo	15 Jun 2009 12:11:36 -0000	1.600
--- gdb.texinfo	20 Jun 2009 04:07:54 -0000
*************** Returns the format used to display the v
*** 23224,23229 ****
--- 23224,23231 ----
  @smallexample
   -var-info-num-children @var{name}
  @end smallexample
+ @anchor{-var-info-num-children}
+

  Returns the number of children of a variable object @var{name}:

*************** Returns the number of children of a vari
*** 23242,23247 ****
--- 23244,23250 ----
  @end smallexample
  @anchor{-var-list-children}

+
  Return a list of the children of the specified variable object and
  create variable objects for them, if they do not already exist.  With
  a single argument or if @var{print-values} has a value for of 0 or
*************** values; and if it is 2 or @code{--simple
*** 23251,23266 ****
  value for simple data types and just the name for arrays, structures
  and unions.

  @subsubheading Example

  @smallexample
  (gdb)
   -var-list-children n
!  ^done,numchild=@var{n},children=[@{name=@var{name},
   numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
  (gdb)
   -var-list-children --all-values n
!  ^done,numchild=@var{n},children=[@{name=@var{name},
   numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
  @end smallexample

--- 23254,23290 ----
  value for simple data types and just the name for arrays, structures
  and unions.

+ For each child the following results are returned:
+
+ @table @var
+
+ @item name
+ Name of the variable object created for this child.
+
+ @item exp
+ The expression to be shown to the user by the front end to designate
this child.
+ For example this may be the name of a structure member.
+
+ For C/C++ structures there are several psuedo children returned to
+ designate access qualifiers.  For these pseudo children @var{exp} is
+ @samp{public}, @samp{private}, or @samp{protected}.  No type need be provided.
+
+ @item numchild
+ Number of children this child has.
+ @item type
+ The type of the child.
+ @end table
+
  @subsubheading Example

  @smallexample
  (gdb)
   -var-list-children n
!  ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp},
   numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
  (gdb)
   -var-list-children --all-values n
!  ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp},
   numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
  @end smallexample

Re: gdb.texinfo patch for -var-list-children (2)

[Vladimir Prus]

Chris Genly wrote:

> Description
> 
> The gdb documentation for the MI command -var-list-children does not
> define the exp
> result for a child.  Exp and other child results documented.
> 
> Sorry I didn't document this with the last patch.  But my
> understanding of MI commands is still increasing.
> 
> Change log
> 
> 2009-06-19  Chris Genly  <chris@genly.us>
> * doc/gdb.texinfo (GDB/MI Variable Objects): Document child
> definition in -var-list-children.  Added exp result for child.
> 
> Patch
> 
> Index: gdb.texinfo
> ===================================================================
> RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
> retrieving revision 1.600
> diff -c -p -r1.600 gdb.texinfo
> *** gdb.texinfo       15 Jun 2009 12:11:36 -0000      1.600
> --- gdb.texinfo       20 Jun 2009 04:07:54 -0000
> *************** Returns the format used to display the v

I suggest you use unified diffs for patches (cvs diff -u). The default "context"
format is some historically-inflicted thing that is hard to read.

- Volodya

Re: gdb.texinfo patch for -var-list-children (2)

[Eli Zaretskii]

> From:  Vladimir Prus <vladimir@codesourcery.com>
> Date:  Sat, 20 Jun 2009 12:41:09 +0400
> 
> I suggest you use unified diffs for patches (cvs diff -u). The default "context"
> format is some historically-inflicted thing that is hard to read.

I'm fine with both context and unified diffs.

Re: gdb.texinfo patch for -var-list-children (2)

[Joel Brobecker]

> > I suggest you use unified diffs for patches (cvs diff -u). The
> > default "context" format is some historically-inflicted thing that
> > is hard to read.
> 
> I'm fine with both context and unified diffs.

That's very kind of you to accept context diffs, but I do feel that
most reviewers are more comfortable with unified diffs - so I suggest
we keep asking for unified for future patches. I, for one, cannot
read context diffs. I usually don't ask a resend, and convert the patch
from one format to the next, but I like to ask that future patches
be in unified format.

-- 
Joel

Re: gdb.texinfo patch for -var-list-children (2)

[Eli Zaretskii]

> Date: Sun, 21 Jun 2009 20:18:32 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: Vladimir Prus <vladimir@codesourcery.com>, 	Chris Genly <chgenly@gmail.com>, gdb-patches@sources.redhat.com
> 
> > > I suggest you use unified diffs for patches (cvs diff -u). The
> > > default "context" format is some historically-inflicted thing that
> > > is hard to read.
> > 
> > I'm fine with both context and unified diffs.
> 
> That's very kind of you to accept context diffs, but I do feel that
> most reviewers are more comfortable with unified diffs - so I suggest
> we keep asking for unified for future patches. I, for one, cannot
> read context diffs. I usually don't ask a resend, and convert the patch
> from one format to the next, but I like to ask that future patches
> be in unified format.

I'm surprised by such strong feelings, since the difference between
context and unified diffs is not so large.

Anyway, all GNU projects I ever contributed to accept both context and
unified diffs, and in fact so does GDB, because gdb/CONTRIBUTE says
this:

    o	Submitting Patches

	    [...]
	    The patch itself. If you are accessing the CVS repository use
	    "cvs update; cvs diff -cp"; else, use "diff -cp OLD NEW" or
	    "diff -up OLD NEW". If your version of diff does not support
	    these options, then get the latest version of GNU diff.

So if from now on we are going to request only unified diffs, we
should at least change this text.  FWIW, I don't think we should
change this policy because it may prove inconvenient in some
situations (e.g., the Patch utility produces reject files in context
diff format).  But that's me.

Re: gdb.texinfo patch for -var-list-children (2)

[Daniel Jacobowitz]

On Mon, Jun 22, 2009 at 12:42:31AM -0400, Eli Zaretskii wrote:
> So if from now on we are going to request only unified diffs, we
> should at least change this text.  FWIW, I don't think we should
> change this policy because it may prove inconvenient in some
> situations (e.g., the Patch utility produces reject files in context
> diff format).  But that's me.

I agree that we should accept context diffs.  I (strongly) prefer
unified, but there are some cases where a context diff is much easier
to read.

As for patch, I recently discovered --unified-reject-files - very useful.

-- 
Daniel Jacobowitz
CodeSourcery

Re: gdb.texinfo patch for -var-list-children (2)

[Eli Zaretskii]

> Date: Mon, 22 Jun 2009 11:02:01 -0400
> From: Daniel Jacobowitz <drow@false.org>
> Cc: Joel Brobecker <brobecker@adacore.com>, vladimir@codesourcery.com,
> 	chgenly@gmail.com, gdb-patches@sources.redhat.com
> 
> I (strongly) prefer unified

Same here, but I don't want to impose my preferences on others.

> As for patch, I recently discovered --unified-reject-files - very useful.

Right, but that option is only available in the unofficial beta
versions of Patch.  Many users are unlikely to have it.  The latest
official release doesn't support such an option.  (And then there's
the issue with tools that use Patch as their back-end, and don't let
you use this option easily.)

Re: gdb.texinfo patch for -var-list-children (2)

[Daniel Jacobowitz]

On Mon, Jun 22, 2009 at 09:00:31PM -0400, Eli Zaretskii wrote:
> > As for patch, I recently discovered --unified-reject-files - very useful.
> 
> Right, but that option is only available in the unofficial beta
> versions of Patch.  Many users are unlikely to have it.  The latest
> official release doesn't support such an option.  (And then there's
> the issue with tools that use Patch as their back-end, and don't let
> you use this option easily.)

Huh, thanks.  I didn't know that; Debian's packages imported the
option 3.5 years ago.  I actually use it with one such tool (quilt) :-)

-- 
Daniel Jacobowitz
CodeSourcery

Re: gdb.texinfo patch for -var-list-children (2)

[Eli Zaretskii]

> Date: Fri, 19 Jun 2009 21:11:07 -0700
> From: Chris Genly <chgenly@gmail.com>
> 
> The gdb documentation for the MI command -var-list-children does not
> define the exp
> result for a child.  Exp and other child results documented.

Thanks.  A few comments:

> + @anchor{-var-info-num-children}

Why did you add this @anchor?  I don't see it referenced anywhere in
your changes.

> + For C/C++ structures there are several psuedo children returned to
                                           ^^^^^^
A typo.

Also, please use "C@t{++}" instead of just "C++", the former looks
better in print.

Okay with these corrections.

Btw, you seem to have no copyright assignment on file with the FSF,
and your grace of 15 lines of contributions without an assignment is
almost exhausted.  Did you start your paperwork with FSF?  If not,
please consider doing that soon, or else we will be unable to accept
your contributions.

Thanks.

Re: gdb.texinfo patch for -var-list-children (2)

[Chris Genly]

I'll submit a new patch based on your comments.  I appreciate you
spending your time on these changes.


>> + @anchor{-var-info-num-children}
>
> Why did you add this @anchor?  I don't see it referenced anywhere in
> your changes.

I'll fix that.

>> + For C/C++ structures there are several psuedo children returned to
>                                           ^^^^^^

You are pointing to the word "there".  I believe "there" is correct.
Are you thinking it should b e "their"?

> A typo.

> Also, please use "C@t{++}" instead of just "C++", the former looks
> better in print.

Ah. Good.

> Okay with these corrections.
>
> Btw, you seem to have no copyright assignment on file with the FSF,
> and your grace of 15 lines of contributions without an assignment is
> almost exhausted.  Did you start your paperwork with FSF?  If not,
> please consider doing that soon, or else we will be unable to accept
> your contributions.

I wasn't aware of the need for paperwork.  I appreciate you guiding me
through this.  I should have been aware.  I read
http://sourceware.org/cgi-bin/cvsweb.cgi/~checkout~/src/gdb/CONTRIBUTE?content-type=text/x-cvsweb-markup&cvsroot=src
document.  But I skimmed some sections.

I have filled out the request-assign.future document and sent it in.

Re: gdb.texinfo patch for -var-list-children (2)

[Chris Genly]

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

Description

The gdb documentation for the MI command -var-list-children does not
define the exp result for a child.  Exp and other child results documented.

Change log

2009-06-20  Chris Genly  <chris@genly.us>
       * doc/gdb.texinfo (GDB/MI Variable Objects): Document child
       definition in -var-list-children.  Added exp result for child.

Patch

Attached.

[-- Attachment #2: gdb.texinfo.patch --]
[-- Type: application/octet-stream, Size: 2604 bytes --]

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.600
diff -c -p -r1.600 gdb.texinfo
*** gdb.texinfo	15 Jun 2009 12:11:36 -0000	1.600
--- gdb.texinfo	20 Jun 2009 21:25:52 -0000
*************** Returns the format used to display the v
*** 23225,23230 ****
--- 23225,23231 ----
   -var-info-num-children @var{name}
  @end smallexample
  
+ 
  Returns the number of children of a variable object @var{name}:
  
  @smallexample
*************** values; and if it is 2 or @code{--simple
*** 23251,23266 ****
  value for simple data types and just the name for arrays, structures
  and unions.
  
  @subsubheading Example
  
  @smallexample
  (gdb)
   -var-list-children n
!  ^done,numchild=@var{n},children=[@{name=@var{name},
   numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
  (gdb)
   -var-list-children --all-values n
!  ^done,numchild=@var{n},children=[@{name=@var{name},
   numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
  @end smallexample
  
--- 23252,23300 ----
  value for simple data types and just the name for arrays, structures
  and unions.
  
+ For each child the following results are returned:
+ 
+ @table @var
+ 
+ @item name
+ Name of the variable object created for this child.
+ 
+ @item exp
+ The expression to be shown to the user by the front end to designate this child.
+ For example this may be the name of a structure member.  
+ 
+ For C/C@t{++} structures there are several psuedo children returned to
+ designate access qualifiers.  For these pseudo children @var{exp} is
+ @samp{public}, @samp{private}, or @samp{protected}.  In this case the
+ type and value are not present.
+ 
+ @item numchild
+ Number of children this child has.
+ 
+ @item type
+ The type of the child.
+ 
+ @item value
+ If values were requested, this is the value.
+ 
+ @item thread-id
+ If this variable object is associated with a thread, this is the thread id.  
+ Otherwise this result is not present.
+ 
+ @item frozen
+ If the variable object is frozen, this variable will be present with a value of 1.
+ @end table
+ 
  @subsubheading Example
  
  @smallexample
  (gdb)
   -var-list-children n
!  ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp},
   numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
  (gdb)
   -var-list-children --all-values n
!  ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp},
   numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
  @end smallexample
  

Re: gdb.texinfo patch for -var-list-children (2)

[Eli Zaretskii]

> Date: Sat, 20 Jun 2009 14:33:02 -0700
> From: Chris Genly <chgenly@gmail.com>
> Cc: gdb-patches@sourceware.org
> 
> The gdb documentation for the MI command -var-list-children does not
> define the exp result for a child.  Exp and other child results documented.
> 
> Change log
> 
> 2009-06-20  Chris Genly  <chris@genly.us>
>        * doc/gdb.texinfo (GDB/MI Variable Objects): Document child
>        definition in -var-list-children.  Added exp result for child.
> 
> Patch
> 
> Attached.

Sorry for the delay.  I committed this patch.

Thanks.

Re: gdb.texinfo patch for -var-list-children (2)

[Eli Zaretskii]

> Date: Sat, 20 Jun 2009 13:30:57 -0700
> From: Chris Genly <chgenly@gmail.com>
> Cc: gdb-patches@sourceware.org
> 
> >> + For C/C++ structures there are several psuedo children returned to
> >                                           ^^^^^^
> 
> You are pointing to the word "there".

No, to "psuedo".

> I have filled out the request-assign.future document and sent it in.

Thank you.

Re: gdb.texinfo patch for -var-list-children (2)

[Samuel Bronson]

At Sat, 20 Jun 2009 13:30:57 -0700,
Chris Genly wrote:

> >> + For C/C++ structures there are several psuedo children returned to
> >                                           ^^^^^^
> 
> You are pointing to the word "there".  I believe "there" is correct.
> Are you thinking it should b e "their"?

Actually, those ^^^^^^ are under "psuedo". I guess maybe your email
isn't displayed in a fixed-width font?

Re: gdb.texinfo patch for -var-list-children (2)

[Chris Genly]

Ah, pseudo. I could have stared at that forever and not seen it.  Do
you want another patch? Is it the practice that patches become
perfect? Or do the appliers of the patches sometimes tweak the patch?
I'm happy to make another patch.

Yes my mailer (gmail) shows variable width fonts.

On Sat, Jun 20, 2009 at 4:17 PM, Samuel Bronson<naesten@gmail.com> wrote:
> At Sat, 20 Jun 2009 13:30:57 -0700,
> Chris Genly wrote:
>
>> >> + For C/C++ structures there are several psuedo children returned to
>> >                                           ^^^^^^
>>
>> You are pointing to the word "there".  I believe "there" is correct.
>> Are you thinking it should b e "their"?
>
> Actually, those ^^^^^^ are under "psuedo". I guess maybe your email
> isn't displayed in a fixed-width font?
>

Re: gdb.texinfo patch for -var-list-children (2)

[Eli Zaretskii]

> Date: Sun, 21 Jun 2009 12:28:21 -0700
> From: Chris Genly <chgenly@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, gdb-patches@sourceware.org
> 
> Ah, pseudo. I could have stared at that forever and not seen it.  Do
> you want another patch? Is it the practice that patches become
> perfect?

It is customary to post here the patch that actually gets committed.
But in this case, there's no need for another patch because of a
single typo.