From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 24670 invoked by alias); 5 Jul 2005 03:25:27 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 24612 invoked by uid 22791); 5 Jul 2005 03:25:19 -0000 Received: from viper.snap.net.nz (HELO viper.snap.net.nz) (202.37.101.8) by sourceware.org (qpsmtpd/0.30-dev) with ESMTP; Tue, 05 Jul 2005 03:25:19 +0000 Received: from farnswood.snap.net.nz (p224-tnt1.snap.net.nz [202.124.110.224]) by viper.snap.net.nz (Postfix) with ESMTP id EF26B5DC7BD; Tue, 5 Jul 2005 15:25:12 +1200 (NZST) Received: by farnswood.snap.net.nz (Postfix, from userid 501) id 6BFF562A99; Tue, 5 Jul 2005 04:25:22 +0100 (BST) From: Nick Roberts MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <17097.64927.197634.566992@farnswood.snap.net.nz> Date: Tue, 05 Jul 2005 03:25:00 -0000 To: Eli Zaretskii Cc: bob@brasko.net, gdb-patches@sources.redhat.com Subject: Re: [PATCH: gdb/mi + doco] -var-update In-Reply-To: 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> <20050617140410.GA24575@nevyn.them.org> <20050703195630.GM13811@nevyn.them.org> <17097.42837.514419.9496@farnswood.snap.net.nz> X-SW-Source: 2005-07/txt/msg00055.txt.bz2 > > +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 * 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