From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 15127 invoked by alias); 21 Jun 2013 08:25:05 -0000 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 Received: (qmail 15112 invoked by uid 89); 21 Jun 2013 08:25:04 -0000 X-Spam-SWARE-Status: No, score=-4.2 required=5.0 tests=AWL,BAYES_00,KHOP_THREADED,RCVD_IN_DNSWL_NONE,RCVD_IN_HOSTKARMA_NO,SPF_SOFTFAIL autolearn=no version=3.3.1 Received: from mtaout23.012.net.il (HELO mtaout23.012.net.il) (80.179.55.175) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Fri, 21 Jun 2013 08:25:03 +0000 Received: from conversion-daemon.a-mtaout23.012.net.il by a-mtaout23.012.net.il (HyperSendmail v2007.08) id <0MOQ00G00HUU6900@a-mtaout23.012.net.il> for gdb-patches@sourceware.org; Fri, 21 Jun 2013 11:24:23 +0300 (IDT) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout23.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MOQ00G37I0M07B0@a-mtaout23.012.net.il>; Fri, 21 Jun 2013 11:24:23 +0300 (IDT) Date: Fri, 21 Jun 2013 09:53:00 -0000 From: Eli Zaretskii Subject: Re: [RFA 4/4 doc] Explicit locations In-reply-to: <51C2349B.7080303@redhat.com> To: Keith Seitz Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83a9mjooql.fsf@gnu.org> References: <514B9EC2.5060502@redhat.com> <514BA08F.4010305@redhat.com> <83620j6a8i.fsf@gnu.org> <51C2349B.7080303@redhat.com> X-SW-Source: 2013-06/txt/msg00579.txt.bz2 > Date: Wed, 19 Jun 2013 15:45:47 -0700 > From: Keith Seitz > CC: gdb-patches@sourceware.org > > >> +@table @code > >> +@item -source > >> +The value specifies the source file name. This option > >> +requires the use of either @code{-function} or @code{-line}. > > > > I think this should explain how to specify a file name unambiguously > > (after all, this is what explicit locations are all about, right?). > > For example, what if only a basename is specified? how to specify the > > file name when several different files in the source tree have the > > same basename? > > I've made an attempt at this. It probably needs a little more work, > though, and the eyes of an outsider. It looks fine to me. > +#define LOCATION_HELP_STRING \ > +"Linespecs are a colon-separated list of location parameters, such as\n\ "Linespecs are colon-separated lists", in plural. > +Address locations begin with \"*\" and specify an exact address in the.\n\ ^ That period should be removed. > +program. Example: To specify the fourth byte past the start function\n\ > +\"main\",use \"*main + 4\".\n\ ^ Space before the comma here. > -LOCATION may be a line number, function name, or \"*\" and an address.\n\ > -If a line number is specified, break at start of code for that line.\n\ > -If a function is specified, break at start of code for that function.\n\ > -If an address is specified, break at that exact address.\n\ > +LOCATION may be a linespec, address, or explicit location.\n\ > +\n" LOCATION_HELP_STRING "\n\ > With no LOCATION, uses current execution address of the selected\n\ > stack frame. This is useful for breaking on return to a stack frame.\n\ > \n\ I would move the "With no LOCATION ..." part before LOCATION_HELP_STRING, since the latter is long. You can add "as described below" to the preceding sentence, to make the reference more explicit. > +Clear breakpoint at specified location.\n\ > +Argument may be a linespec, explicit, or address location.\n\ > +\n" LOCATION_HELP_STRING "\n\ > With no argument, clears all breakpoints in the line that the selected > frame\n\ > is executing in.\n\ > \n\ Likewise here (and elsewhere). > +Locations may be specified using three different formats, > +linespec locations, explicit locations, or address locations. I would put a colon after "Different formats", not a comma. > +sources. In these cases, explicit locations point to the source > +line you meant more accurately and unequivocally. Also, using ^^^^^^^^^^^^^ I would use "unambiguously" here. > +For example, the linespec ``foo:bar'' may refer to a function ``bar'' > +defined in the file named ``foo'' or the label ``bar'' in a function > +named ``foo''. @value{GDBN} must search either the file system or The markup here is incorrect. Drop the quotes, and use @file for file names, @code for functions and labels, and @samp for everything else, like @samp{foo:bar}. > +@table @code > +@item -source > +The value specifies the source file name. To differentiate between I would use a more explicit @item -source @var{filename} (and similarly for other options), like you did in the MI sections. Otherwise, the only place where you hint on the format is the sentence about "option-value pairs", and without an example this is not enough. Btw, adding an example would be great. > +to uniquely identify the desired file, e.g., ``foo/bar/baz.c''. Otherwise ^^^^^^^^^^^^^^^^^ Drop the quotes and use @file markup for file names. > @smallexample > -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] > [ -c @var{condition} ] [ -i @var{ignore-count} ] > - [ -p @var{thread-id} ] [ @var{location} ] > + [ -p @var{thread-id} ] @var{location} Is LOCATION no longer an optional parameter for -break-insert? OK with those changes. Thanks!