From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 25397 invoked by alias); 26 Sep 2007 21:13:14 -0000 Received: (qmail 25386 invoked by uid 22791); 26 Sep 2007 21:13:13 -0000 X-Spam-Check-By: sourceware.org Received: from romy.inter.net.il (HELO romy.inter.net.il) (213.8.233.24) by sourceware.org (qpsmtpd/0.31) with ESMTP; Wed, 26 Sep 2007 21:13:11 +0000 Received: from HOME-C4E4A596F7 (IGLD-83-130-198-199.inter.net.il [83.130.198.199]) by romy.inter.net.il (MOS 3.7.3-GA) with ESMTP id IZE64729 (AUTH halo1); Wed, 26 Sep 2007 23:12:38 +0200 (IST) Date: Wed, 26 Sep 2007 21:13:00 -0000 Message-Id: From: Eli Zaretskii To: Vladimir Prus CC: gdb-patches@sources.redhat.com In-reply-to: <200709262207.42508.vladimir@codesourcery.com> (message from Vladimir Prus on Wed, 26 Sep 2007 22:07:42 +0400) Subject: Re: Docs and NEWS for breakpoint changes Reply-to: Eli Zaretskii References: <200709262207.42508.vladimir@codesourcery.com> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2007-09/txt/msg00392.txt.bz2 > 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)"? If what matters is that the library is not yet loaded, why should we confuse things by distinguishing the case where the address is not resolved from the case where it is? > 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, > +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"? > +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. > +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. > +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. > +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". > +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. > +a new location will be added to the existing breakpoint. Suggest "a new location is added to the list of locations for the breakpoint".