Re: [PATCH: gdb/mi + doco] -var-update

[Nick Roberts <nickrob@snap.net.nz>]

 > > +Display the local variable names for the current frame.  A value for
 > > +@var{print-values} of 0 or @code{--no-values}, prints only the names
 > > +of the variables; a value of 1 or @code{--all-values}, prints also
 > > +their values; and a value of 2 or @code{--simple-values}, prints the
 > > +name, type and value for simple data types and the name and type for
 > > +arrays, structures and unions.
 > 
 > It would be much simpler to rephrase like this:
 > 
 >    Display the local variable names for the current frame.  If
 >    @var{print-values} is 0 or @code{--no-values}, print only the names
 >    of the variables; if it is 1 or @code{--all-values}, print their
 >    values as well; if it is 2 or @code{--simple-values}, print ...
 > 
 > you get the point.  Note that I also changed "prints" -> "print",
 > since the sentence before that says "Display", not "Displays".

OK.  The rest of the documentation uses a mixture of the imperative and
present tense.

Also it should read "for the selected frame".  There seem to be quite a few
places in the manual where "current frame" is used incorrectly
(-stack-select-frame is another example)

 > > +In this last case, the idea is that
 > > +the user can see the value of simple data types immediately and he can
 > > +create variable objects for other data types if he wishes to explore
 > > +their values in more detail.
 > 
 > I think the GNU project's convention is not to use "he" where "she" is
 > also possible.

OK.  And not to use the passive either.  It makes it difficult to express
things clearly in this case.

 > > +Returns a list of the children of the specified variable object.  A
 > > +single argument or an optional value for @var{print-values} of 0 or
 > > +@code{--no-values}, prints only the names of the variables; a value
 > > +for @var{print-values} of 1 or @code{--all-values}, also prints their
 > > +values; and a value of 2 or @code{--simple-values} prints the name and
 > > +value for simple data types and just the name for arrays, structures
 > > +and unions.
 > 
 > This could also use similar rephrasing.

OK.  I've also noted that -var-list-children creates variable objects for
the children if they  don't already exist.

 > > -A @samp{*} causes all existing variable objects to be updated.
 > > +A @samp{*} causes all existing variable objects to be updated.  
 > 
 > These two lines are identical, except that the second one has 2
 > trailing blanks.  Please remove those blanks.

OK.

 > > +The option @var{print-values} determines whether names and values, or
 > > +just names are printed in the manner described for @code{-var-list-children}.
 > 
 > Please add a cross-reference here that points to the description of
 > "-var-list-children".  (Since the commands don't have each one its own
 > node, you will have to use @anchor to create a point-able place for
 > the xref.)

OK.

Nick


2005-07-05  Nick Roberts  <nickrob@snap.net.nz>

	* gdb.texinfo (GDB/MI Variable Objects): Describe print-values
	option for -var-list-children and -var-update.
	(GDB/MI Stack Manipulation): Simplify description of
	print-values option for -stack-list-locals.  Say that
	-stack-select-frame changes selected frame, not current one.
	(GDB/MI Command Description Format): Clarify.
	(Mode Options): Spelling of superseded.


*** gdb.texinfo.~1.272.~	2005-07-04 11:59:22.000000000 +1200
--- gdb.texinfo	2005-07-05 15:23:44.000000000 +1200
***************
*** 1075,1081 ****
  @sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs
  that control @value{GDBN}, and level 2 has been deprecated.
  
! The annotation mechanism has largely been superseeded by @sc{gdb/mi}
  (@pxref{GDB/MI}).
  
  @item --args
--- 1075,1081 ----
  @sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs
  that control @value{GDBN}, and level 2 has been deprecated.
  
! The annotation mechanism has largely been superseded by @sc{gdb/mi}
  (@pxref{GDB/MI}).
  
  @item --args
***************
*** 17094,17112 ****
   -command @var{args}@dots{}
  @end smallexample
  
- @subsubheading @value{GDBN} Command
- 
- The corresponding @value{GDBN} CLI command.
- 
  @subsubheading Result
  
! @subsubheading Out-of-band
  
! @subsubheading Notes
  
  @subsubheading Example
  
- 
  @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  @node GDB/MI Breakpoint Table Commands
  @section @sc{gdb/mi} Breakpoint table commands
--- 17094,17107 ----
   -command @var{args}@dots{}
  @end smallexample
  
  @subsubheading Result
  
! @subsubheading @value{GDBN} Command
  
! The corresponding @value{GDBN} CLI command(s), if any.
  
  @subsubheading Example
  
  @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  @node GDB/MI Breakpoint Table Commands
  @section @sc{gdb/mi} Breakpoint table commands
***************
*** 19491,19504 ****
   -stack-list-locals @var{print-values}
  @end smallexample
  
! Display the local variable names for the current frame.  With an
! argument of 0 or @code{--no-values}, prints only the names of the variables.
! With argument of 1 or @code{--all-values}, prints also their values.  With
! argument of 2 or @code{--simple-values}, prints the name, type and value for
! simple data types and the name and type for arrays, structures and
! unions.  In this last case, the idea is that the user can see the
! value of simple data types immediately and he can create variable
! objects for other data types if he wishes to explore their values in
  more detail.
  
  @subsubheading @value{GDBN} Command
--- 19486,19499 ----
   -stack-list-locals @var{print-values}
  @end smallexample
  
! Display the local variable names for the selected frame.  If
! @var{print-values} is 0 or @code{--no-values}, print only the names of
! the variables; if it is 1 or @code{--all-values}, print also their
! values; and if it is 2 or @code{--simple-values}, print the name,
! type and value for simple data types and the name and type for arrays,
! structures and unions.  In this last case, a frontend can immediately
! display the value of simple data types and create variable objects for
! other data types when the the user wishes to explore their values in
  more detail.
  
  @subsubheading @value{GDBN} Command
***************
*** 19531,19537 ****
   -stack-select-frame @var{framenum}
  @end smallexample
  
! Change the current frame.  Select a different frame @var{framenum} on
  the stack.
  
  @subsubheading @value{GDBN} Command
--- 19526,19532 ----
   -stack-select-frame @var{framenum}
  @end smallexample
  
! Change the selected frame.  Select a different frame @var{framenum} on
  the stack.
  
  @subsubheading @value{GDBN} Command
***************
*** 20463,20485 ****
  @smallexample
   -var-list-children [@var{print-values}] @var{name}
  @end smallexample
  
! Returns a list of the children of the specified variable object.  With
! just the variable object name as an argument or with an optional
! preceding argument of 0 or @code{--no-values}, prints only the names of the
! variables.  With an optional preceding argument of 1 or @code{--all-values},
! also prints their values.
  
  @subsubheading Example
  
  @smallexample
  (@value{GDBP})
   -var-list-children n
!  numchild=@var{n},children=[@{name=@var{name},
   numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
  (@value{GDBP})
   -var-list-children --all-values n
!  numchild=@var{n},children=[@{name=@var{name},
   numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
  @end smallexample
  
--- 20458,20484 ----
  @smallexample
   -var-list-children [@var{print-values}] @var{name}
  @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
! @code{--no-values}, print only the names of the variables; if
! @var{print-values} is 1 or @code{--all-values}, also print their
! values; and if it is 2 or @code{--simple-values} print the name and
! value for simple data types and just the name for arrays, structures
! and unions.
  
  @subsubheading Example
  
  @smallexample
  (@value{GDBP})
   -var-list-children n
!  ^done,numchild=@var{n},children=[@{name=@var{name},
   numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
  (@value{GDBP})
   -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
  
***************
*** 20590,20602 ****
  @subsubheading Synopsis
  
  @smallexample
!  -var-update @{@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.
  
  
  @node Annotations
  @chapter @value{GDBN} Annotations
--- 20589,20616 ----
  @subsubheading Synopsis
  
  @smallexample
!  -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 and values, or just
! names are printed in the manner described for
! @code{@pxref{-var-list-children}}.
! 
! @subsubheading Example
  
+ @smallexample
+ (@value{GDBP})
+ -var-assign var1 3
+ ^done,value="3"
+ (@value{GDBP})
+ -var-update --all-values var1
+ ^done,changelist=[@{name="var1",value="3",in_scope="true",
+ type_changed="false"@}]
+ (@value{GDBP})
+ @end smallexample
  
  @node Annotations
  @chapter @value{GDBN} Annotations