On Thursday 27 September 2007 01:12:47 Eli Zaretskii wrote: > > From: Vladimir Prus > > Date: Wed, 26 Sep 2007 22:07:42 +0400 > > Now that the code patches for my breakpoint changes are in, > > here's the doc patch and NEWS addition. > > Thanks! > > > Comments? > > A few: > > > +* Pending breakpoints where changed to not change its number when > > + resolved. ^^^ > > It's "breakpoints" (plural), so "its" is wrong. > > "where" is also wrong; you meant "were". But please don't use past > tense in NEWS, present tense is better: > > Pending breakpoints no longer change their number when their address > is resolved. > > > +* Support for breakpoints with multiple locations was implemented, > > Avoiding passive voice makes text simpler and clearer: > > GDB now supports breakpoints with multiple locations, > > (also present tense instead of past). > > > +that are not enabled. An optional @samp{(p)} suffix marks pending > > +breakpoints --- breakpoints for which address is either not yet > > +resolved, pending load of a shared library, or for which address was > > +in a shared library that was since resolved. Such breakpoint won't > > +fire until a shared library that has the symbol or line referred by > > +breakpoint is loaded. See below for details. > > I'm left confused: if the address ``was since resolved'', then why do > we still mark the breakpoint with "(p)"? Sorry, "was since resolved" should read "was since unloaded" > > For a > > +pending breakpoint that never had its address known, > > I think this is better: > > For a pending address whose address is not yet known, ^^^^^^^ Did you mean "breakpoint" instead of first "address"? > > +have @samp{} in this field -- see below for details. > ^^ > Please use "---" -- 3 dashes in a row, not 2 -- for an em-dash. > > > +For a C++ constructor, the gcc compiler generates several function > > +bodies used in different cases. > > Please use C@t{++}, it looks better in print (there are several more > instances like this one). Also, we use "@value{NGCC}" instead of a > literal "gcc" in this manual. And instead of "several function > bodies", isn't it more accurate to say "several instances of the > function body"? I'm not quite sure I see the difference; I've changed this. > > > +For a C++ template function, a given line in the function can > > +correspond to unbounded set of instantiations. > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > "to any number of instantiations" is better. > > > +For an inlined function, a given line can correspond to > > +several places where that function is inlined. > > "given source line" or even "a breakpoint at a given source line" will > make things clearer, I think. I went with "given source line", since at this point we're still talking about what language constructs can correspond to multiple PC values. > > +In all those cases, @value{GDBN} will associate the breakpoint > > +with all relevant locations. > > Perhaps we better say "@value{GDBN} will insert a breakpoint at all > the relevant locations". "Associate the breakpoint" leaves me > wondering what does "associate" mean in this context. You're right. > > > +A breakpoint with multiple locations is displayed in the > > +breakpoint table using several rows --- one header row, followed > > +by one row for each breakpoint location. The header row > > +has @samp{} in the address column. The rows for > > +individual locations contain the actual addresses for locations, > > +and say what functions those locations are in. The number > > +column for a location has number in the format > > +@var{breakpoint-number}.@var{location-number}. > > Example, please. A picture is worth a thousand words. I've added one. Is example with a line as long as 75 characters OK? It looked good to me in PDF and info formats, but just to check. > > +Each location can be individually enabled or disabled by passing > > +the @var{breakpoint-number}.@var{location-number} to the @code{enable} > > +or @code{disable} commands. > > Each location can be individually enabled or disabled by passing > @var{breakpoint-number}.@var{location-number} as argument to the > @code{enable} and @code{disable} commands. > > > +It's quite common to have a breakpoint inside a shared library. > > +Further, the shared library may be loaded and unloaded explicitly, > > This "further" thing does not add anything to the sentence; just > remove it. > > > +and possible repeatedly, as the program is executed. To support > ^^^^^^^^ > "and possibly repeatedly". Yes. > > > +any shared library is loaded or unloaded. Typically, you would > ^^^ > Two spaces between sentences, please. > > > +a so called @dfn{pending breakpoint} --- breakpoint that is not yet > > +resolved to address. > > "breakpoint whose address is not yet resolved". > > > +After the program is run, whenever a new shared library is loaded, > > +@value{GDBN} reevaluates all breakpoints. In case a newly loaded > > +shared library contains the symbol or line referred to by breakpoint, > > +breakpoint is resolved and becomes an ordinary breakpoint. If a > > +library is unloaded, all breakpoints it in become pending again. > > Suggest to reword slightly like this: > > After the program is run, whenever a new shared library is loaded, > @value{GDBN} reevaluates all the breakpoints. When a newly loaded > shared library contains the symbol or line referred to by some > pending breakpoint, that breakpoint is resolved and becomes an > ordinary breakpoint. When a library is unloaded, all breakpoints > that refer to its symbols or source lines become pending again. Thanks, this is better. > > +a new location will be added to the existing breakpoint. > > Suggest "a new location is added to the list of locations for the > breakpoint". Thanks for review. I attach the revised version. - Volodya