suggestions for node "(gdb)Set Watchpoints"

[Samuel Bronson <naesten@gmail.com>]

Hi Eli,
    Pedro Alves told me to prod you if I wanted to make suggestions
for the manual?

This paragraph is found very close to the end of the node "(gdb)Set
Watchpoints" in the GDB 6.8 manual:

/----
   GDB automatically deletes watchpoints that watch local (automatic)
variables, or expressions that involve such variables, when they go out
of scope, that is, when the execution leaves the block in which these
variables were defined.  In particular, when the program being debugged
terminates, _all_ local variables go out of scope, and so only
watchpoints that watch global variables remain set.  If you rerun the
program, you will need to set all such watchpoints again.  One way of
doing that would be to set a code breakpoint at the entry to the `main'
function and when it breaks, set all the watchpoints.
\----

I actually didn't see this until I claimed it wasn't in the
documentation, and Pedro quoted the beginning of the paragraph to me
and linked me to that node of the online manual to me in #gdb. I think
this kind of thing might be prevented by moving it much nearer to the
bulleted list at the top of the node -- especially with the paragraph
that was already added between 6.8 and CVS HEAD (as of a few days
ago), which also discusses scope:

/---
   You can set a watchpoint on an expression even if the expression can
not be evaluated yet.  For instance, you can set a watchpoint on
`*global_ptr' before `global_ptr' is initialized.  GDB will stop when
your program sets `global_ptr' and the expression produces a valid
value.  If the expression becomes valid in some other way than changing
a variable (e.g. if the memory pointed to by `*global_ptr' becomes
readable as the result of a `malloc' call), GDB may not stop until the
next time the expression changes.
\----

This paragraph does make things a lot better, but at the same time
makes it even stranger that the other paragraph is so far away from
the description of what kinds of expressions to watch. I think the
other paragraph should be moved up to be with this one -- probably
after it.

It would also be nice to have a more in-depth description of exactly
which watchpoint-related events GDB is actually able to intercept.