This is the mail archive of the
gdb-patches@sources.redhat.com
mailing list for the GDB project.
Re: [PATCH: gdb/mi + doco] -var-update
- From: Nick Roberts <nickrob at snap dot net dot nz>
- To: Eli Zaretskii <eliz at gnu dot org>
- Cc: bob at brasko dot net, gdb-patches at sources dot redhat dot com
- Date: Tue, 5 Jul 2005 15:25:19 +1200
- Subject: Re: [PATCH: gdb/mi + doco] -var-update
- References: <16929.8147.933720.246602@farnswood.snap.net.nz><16955.41017.161288.832646@farnswood.snap.net.nz><20050401024942.GA2179@white><17013.35649.62745.226730@farnswood.snap.net.nz><20050502040526.GA10023@nevyn.them.org><17013.54662.20554.239976@farnswood.snap.net.nz><20050617034329.GH17013@nevyn.them.org><uoea51bqt.fsf@gnu.org><20050617140410.GA24575@nevyn.them.org><ud5qk0z51.fsf@gnu.org><20050703195630.GM13811@nevyn.them.org><ull4np132.fsf@gnu.org><17097.42837.514419.9496@farnswood.snap.net.nz><ubr5ip33y.fsf@gnu.org>
> > +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