[commit] Doc: -var-delete

[commit] Doc: -var-delete

[Nick Roberts]

Committed as obvious.

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


2006-12-04  Nick Roberts  <nickrob@snap.net.nz>

	* gdb.texinfo (GDB/MI Variable Objects): Describe -c option
	of -var-delete.


*** gdb.texinfo	23 Nov 2006 09:27:02 +1300	1.371
--- gdb.texinfo	04 Dec 2006 16:45:48 +1300	
***************
*** 19598,19604 ****
  @item @code{-var-create}
  @tab create a variable object
  @item @code{-var-delete}
! @tab delete the variable object and its children
  @item @code{-var-set-format}
  @tab set the display format of this variable
  @item @code{-var-show-format}
--- 19598,19604 ----
  @item @code{-var-create}
  @tab create a variable object
  @item @code{-var-delete}
! @tab delete the variable object and/or its children
  @item @code{-var-set-format}
  @tab set the display format of this variable
  @item @code{-var-show-format}
***************
*** 19681,19690 ****
  @subsubheading Synopsis
  
  @smallexample
!  -var-delete @var{name}
  @end smallexample
  
  Deletes a previously created variable object and all of its children.
  
  Returns an error if the object @var{name} is not found.
  
--- 19681,19691 ----
  @subsubheading Synopsis
  
  @smallexample
!  -var-delete [ -c ] @var{name}
  @end smallexample
  
  Deletes a previously created variable object and all of its children.
+ With the @samp{-c} option, just deletes the children.
  
  Returns an error if the object @var{name} is not found.
  

Re: [commit] Doc: -var-delete

[Eli Zaretskii]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Mon, 4 Dec 2006 16:52:51 +1300
> 
> Committed as obvious.

Not that I object to the change, but I'm curious: why did you think it
was obvious?

Re: [commit] Doc: -var-delete

[Nick Roberts]

 > Not that I object to the change, but I'm curious: why did you think it
 > was obvious?

I guess if it really was obvious then someone would have made the change before
me but I was trying to apply the definition in MAINTAINERS:

  An "obvious fix" means that there is no possibility that anyone will
  disagree with the change.

As I'm documenting existing (undocumented) functionality I can't see how anyone
can disagree.  You might be able to improve upon it, but that's presumably a
different point and you are still able to do so.

Why do you think it is not obvious?

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

Re: [commit] Doc: -var-delete

[Vladimir Prus]

Nick Roberts wrote:

> @smallexample
> !  -var-delete [ -c ] @var{name}
> @end smallexample
> 
> Deletes a previously created variable object and all of its children.
> + With the @samp{-c} option, just deletes the children.

Should this be "deletes just the children"? Or "deletes only the children"?
The way it's written now "just" binds to "deletes", so one wonders if
there's "just delete" behaviour and "not just delete" behaviour and what
the latter might be.

non-native-speakerly-picky-yours,
Volodya

Re: [commit] Doc: -var-delete

[Eli Zaretskii]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Mon, 4 Dec 2006 17:41:03 +1300
> Cc: gdb-patches@sources.redhat.com
> 
> I was trying to apply the definition in MAINTAINERS:
> 
>   An "obvious fix" means that there is no possibility that anyone will
>   disagree with the change.
> 
> As I'm documenting existing (undocumented) functionality I can't see how anyone
> can disagree.

The _need_ for documenting an existing feature is indisputable (at
least in this case, since that is my policy; you know as well as I do
that, in the case of Emacs, for example, RMS has a different policy,
so even the need for documenting an existing feature does not
necessarily constitute a good-enough reason).  However, _how_ it
should be documented is not obvious in any way; I could express the
same idea as you did in about a dozen different ways.

> Why do you think it is not obvious?

Because about the only kind of fix in the docs that is really obvious
is a typo or bad English.

Re: [commit] Doc: -var-delete

[Nick Roberts]

 > > Why do you think it is not obvious?
 > 
 > Because about the only kind of fix in the docs that is really obvious
 > is a typo or bad English.

OK, sorry.  I'll post to gdb-patches first, next time.  To avoid any confusion,
it might be a good idea to say this in MAINTAINERS.

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

Re: [commit] Doc: -var-delete

[Eli Zaretskii]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Tue, 5 Dec 2006 09:52:30 +1300
> Cc: gdb-patches@sources.redhat.com
> 
>  > > Why do you think it is not obvious?
>  > 
>  > Because about the only kind of fix in the docs that is really obvious
>  > is a typo or bad English.
> 
> OK, sorry.  I'll post to gdb-patches first, next time.  To avoid any confusion,
> it might be a good idea to say this in MAINTAINERS.

Done; thanks for the suggestion.

Re: [commit] Clarify obvious fix in the docs (was: Doc: -var-delete)

[Eli Zaretskii]

Here's the patch I committed to clarify the ``obvious fix'' in the
docs:

2006-12-08  Eli Zaretskii  <eliz@gnu.org>

	* MAINTAINERS: Clarify the meaning of an ``obvious fix'' in the
	docs.

Index: MAINTAINERS
===================================================================
RCS file: /cvs/src/src/gdb/MAINTAINERS,v
retrieving revision 1.354
retrieving revision 1.355
diff -u -r1.354 -r1.355
--- MAINTAINERS	6 Dec 2006 06:51:50 -0000	1.354
+++ MAINTAINERS	8 Dec 2006 17:28:31 -0000	1.355
@@ -95,6 +95,9 @@
 fix, since such a change without discussion will result in
 instantaneous and loud complaints.
 
+For documentation changes, about the only kind of fix that is obvious
+is correction of a typo or bad English usage.
+
 
 	     GDB Steering Committee
 	     ----------------------

Re: [commit] Doc: -var-delete

[Nick Roberts]

> > @smallexample
> > ! Â-var-delete [ -c ] @var{name}
> > @end smallexample
> > 
> > Deletes a previously created variable object and all of its children.
> > + With the @samp{-c} option, just deletes the children.

> Should this be "deletes just the children"? Or "deletes only the children"?
> The way it's written now "just" binds to "deletes", so one wonders if
> there's "just delete" behaviour and "not just delete" behaviour and what
> the latter might be.

If it were a legal contract, I think you may have found a loophole.  For
general reading though, I think the second sentence is unambiguous in the
context of the first.  However I don't mind if someone wants to change it.

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