Re: [PATCH] Add autoload-breakpoints [7/7] autoload-breakpoints doc

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 20 Mar 2012 23:41:51 +0800
> From: Hui Zhu <hui_zhu@mentor.com>
> CC: <gdb-patches@sourceware.org>, <stan_shebs@mentor.com>
> 
> >   @value{GDBN} can receive the information about autoload-breakpoints
> >   from the remote stub, if the stub supports that.
> >
> > Also, as we don't mention autoload-breakpoints anywhere else in the
> > manual, we need to explain here what these breakpoints are and why
> > controlling them is useful.
> 
> What about:
> Some stub support set breakpoints with itself, with this function, GDB 
> can handle the breakpoint that set by the stub better.

I think we need to explain more.  How about using what Yao wrote
yesterday:

  Prior to GDB connects to remote stub, some breakpoints might have been
  already set in target, either by a prior GDB session or by the program
  itself through some special system API.  When GDB connects to target, it
  should handle these existing breakpoints from remote stub.  We call
  these breakpoints as "auotload breakpoints".

  The other use case we want to support in GDB is that inferior may
  delete/clear breakpoints on its own, and remote stub gets GDB notified,
  and GDB can take some actions accordingly.  We believe such reliable
  report is useful to GDB, and generalize it, called "ReportAsync".

  The connection between "ReportAsync" and "autoload breakpoint" is when
  inferior/stub delete breakpoints, sends async report to GDB about
  removed breakpoints.

If this is accurate, it just needs some rewording for it to be a good
introduction to this topic.

> >> +@item set breakpoint autoload merge
> >> +If this option is merge, the autoload-breakpoints of @value{GDBN}
> >                       ^^^^^
> > @samp{merge}
> >
> >> +and stub will merge together when @value{GDBN} connect to stub.
> >
> > I don't understand what it means to "merge" breakpoints.
> 
> It means that merge together.  Keep both the autoload-breakpoints in the 
> GDB and the stub.

Then please don't use "merge", its normal meaning gets in the way.
Instead, say this:

 the autoload-breakpoints of both @value{GDBN} and of the stub will be
 kept.

> > Please don't add subsections without a node (and a menu in the parent
> > section).  Such subsections cannot be navigated with on-line Info
> > commands.
> 
> Should I change it to:
> @node Autoload-breakpoints base format
> @subsection Autoload-breakpoints base format
> @cindex Autoload-breakpoints base format

Yes, but (a) you also need a menu in the parent node, and (b) @cindex
entries should always begin with a lower-case letter.

> OK.  I will do it according to your comments.

Thank you.