RFA: Fix per-thread watchpoint documentation

RFA: Fix per-thread watchpoint documentation

[Jim Blandy]

The GDB documentation doesn't build at the moment, because the
per-thread watchpoint documentation introduces an @item outside any
@table.

One could fix this by simply wrapping a @table around the new @item,
but it doesn't seem to me that that description is in the right place
within its node.

So, does this look okay?

gdb/doc/ChangeLog:
2007-12-17  Jim Blandy  <jimb@codesourcery.com>

	* doc/gdb.texinfo: Integrate per-thread watchpoint explanation
	into the main description of the watchpoint command.

diff -r f76996bac30f gdb/doc/gdb.texinfo
--- a/gdb/doc/gdb.texinfo	Mon Dec 17 08:21:17 2007 -0800
+++ b/gdb/doc/gdb.texinfo	Mon Dec 17 08:38:52 2007 -0800
@@ -3222,7 +3222,7 @@ watchpoints, which do not slow down the 
 
 @table @code
 @kindex watch
-@item watch @var{expr}
+@item watch @var{expr} @r{[}thread @var{threadnum}@r{]}
 Set a watchpoint for an expression.  @value{GDBN} will break when the
 expression @var{expr} is written into by the program and its value
 changes.  The simplest (and the most popular) use of this command is
@@ -3232,13 +3232,20 @@ to watch the value of a single variable:
 (@value{GDBP}) watch foo
 @end smallexample
 
+If the command includes a @code{@r{[}thread @var{threadnum}@r{]}}
+clause, @value{GDBN} breaks only when the thread identified by
+@var{threadnum} changes the value of @var{expr}.  If any other threads
+change the value of @var{expr}, @value{GDBN} will not break.  Note
+that watchpoints restricted to a single thread in this way only work
+with Hardware Watchpoints.
+
 @kindex rwatch
-@item rwatch @var{expr}
+@item rwatch @var{expr} @r{[}thread @var{threadnum}@r{]}
 Set a watchpoint that will break when the value of @var{expr} is read
 by the program.
 
 @kindex awatch
-@item awatch @var{expr}
+@item awatch @var{expr} @r{[}thread @var{threadnum}@r{]}
 Set a watchpoint that will break when @var{expr} is either read from
 or written into by the program.
 
@@ -3356,13 +3363,6 @@ way of doing that would be to set a code
 @cindex threads and watchpoints
 In multi-threaded programs, watchpoints will detect changes to the
 watched expression from every thread.
-
-@kindex watch thread thread_num
-@item watch @var{expr} thread @var{threadnum}
-Set a watchpoint that will break when @var{expr} is either read from
-or written into by the thread identified by @var{threadnum}.  If @var{expr}
-is modified by any other threads not matching @var{threadnum}, @value{GDBN}
-will not break.  Note that this will only work with Hardware Watchpoints.
 
 @quotation
 @emph{Warning:} In multi-threaded programs, software watchpoints

Re: RFA: Fix per-thread watchpoint documentation

[Luis Machado]

> So, does this look okay?

Looks OK to me. Thanks for fixing this. I'll install the required
packages to verify the documentation bits and avoid future problems like
this one. Sorry.

-- 
Luis Machado
Software Engineer 
IBM Linux Technology Center

Re: RFA: Fix per-thread watchpoint documentation

[Eli Zaretskii]

> From: Jim Blandy <jimb@codesourcery.com>
> Date: Mon, 17 Dec 2007 08:46:09 -0800
> 
> 
> The GDB documentation doesn't build at the moment, because the
> per-thread watchpoint documentation introduces an @item outside any
> @table.
> 
> One could fix this by simply wrapping a @table around the new @item,
> but it doesn't seem to me that that description is in the right place
> within its node.
> 
> So, does this look okay?

Yes, but you also changed other places which you didn't announce.  Not
that I object to them, though...

Thanks.

Re: RFA: Fix per-thread watchpoint documentation

[Jim Blandy]

Eli Zaretskii <eliz at gnu.org> writes:
>> From: Jim Blandy <jimb@codesourcery.com>
>> Date: Mon, 17 Dec 2007 08:46:09 -0800
>> 
>> 
>> The GDB documentation doesn't build at the moment, because the
>> per-thread watchpoint documentation introduces an @item outside any
>> @table.
>> 
>> One could fix this by simply wrapping a @table around the new @item,
>> but it doesn't seem to me that that description is in the right place
>> within its node.
>> 
>> So, does this look okay?
>
> Yes, but you also changed other places which you didn't announce.  Not
> that I object to them, though...

My ChangeLog entry was not up to par; thanks.  I've committed the
following:

gdb/doc/ChangeLog:
2007-12-18  Jim Blandy  <jimb@codesourcery.com>

	* doc/gdb.texinfo (Set Watchpoints): Integrate per-thread
	watchpoint explanation into the main description of the watchpoint
	command; update synopses of 'watch', 'rwatch', and 'awatch'
	commands.

diff -r 45aa3691eac1 gdb/doc/gdb.texinfo
--- a/gdb/doc/gdb.texinfo	Tue Dec 18 09:26:19 2007 -0800
+++ b/gdb/doc/gdb.texinfo	Tue Dec 18 10:06:04 2007 -0800
@@ -3222,7 +3222,7 @@ watchpoints, which do not slow down the 
 
 @table @code
 @kindex watch
-@item watch @var{expr}
+@item watch @var{expr} @r{[}thread @var{threadnum}@r{]}
 Set a watchpoint for an expression.  @value{GDBN} will break when the
 expression @var{expr} is written into by the program and its value
 changes.  The simplest (and the most popular) use of this command is
@@ -3232,13 +3232,20 @@ to watch the value of a single variable:
 (@value{GDBP}) watch foo
 @end smallexample
 
+If the command includes a @code{@r{[}thread @var{threadnum}@r{]}}
+clause, @value{GDBN} breaks only when the thread identified by
+@var{threadnum} changes the value of @var{expr}.  If any other threads
+change the value of @var{expr}, @value{GDBN} will not break.  Note
+that watchpoints restricted to a single thread in this way only work
+with Hardware Watchpoints.
+
 @kindex rwatch
-@item rwatch @var{expr}
+@item rwatch @var{expr} @r{[}thread @var{threadnum}@r{]}
 Set a watchpoint that will break when the value of @var{expr} is read
 by the program.
 
 @kindex awatch
-@item awatch @var{expr}
+@item awatch @var{expr} @r{[}thread @var{threadnum}@r{]}
 Set a watchpoint that will break when @var{expr} is either read from
 or written into by the program.
 
@@ -3356,13 +3363,6 @@ way of doing that would be to set a code
 @cindex threads and watchpoints
 In multi-threaded programs, watchpoints will detect changes to the
 watched expression from every thread.
-
-@kindex watch thread thread_num
-@item watch @var{expr} thread @var{threadnum}
-Set a watchpoint that will break when @var{expr} is either read from
-or written into by the thread identified by @var{threadnum}.  If @var{expr}
-is modified by any other threads not matching @var{threadnum}, @value{GDBN}
-will not break.  Note that this will only work with Hardware Watchpoints.
 
 @quotation
 @emph{Warning:} In multi-threaded programs, software watchpoints