From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 12286 invoked by alias); 27 Jul 2012 11:23:47 -0000 Received: (qmail 12277 invoked by uid 22791); 27 Jul 2012 11:23:45 -0000 X-SWARE-Spam-Status: No, hits=-4.2 required=5.0 tests=AWL,BAYES_00,KHOP_THREADED,RCVD_IN_DNSWL_NONE,RCVD_IN_HOSTKARMA_NO,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mtaout20.012.net.il (HELO mtaout20.012.net.il) (80.179.55.166) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Fri, 27 Jul 2012 11:23:29 +0000 Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0M7T00400GW0FX00@a-mtaout20.012.net.il> for gdb-patches@sourceware.org; Fri, 27 Jul 2012 14:23:28 +0300 (IDT) Received: from HOME-C4E4A596F7 ([87.69.210.75]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0M7T004LHGZ3CG10@a-mtaout20.012.net.il>; Fri, 27 Jul 2012 14:23:28 +0300 (IDT) Date: Fri, 27 Jul 2012 11:23:00 -0000 From: Eli Zaretskii Subject: Re: [RFA 5/5] Explicit linespecs - documentation In-reply-to: <50120FE7.8060100@redhat.com> To: Keith Seitz Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83394djvm1.fsf@gnu.org> References: <50120FE7.8060100@redhat.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: 2012-07/txt/msg00673.txt.bz2 > Date: Thu, 26 Jul 2012 20:49:59 -0700 > From: Keith Seitz > > The patch below adds documentation for explicit linespecs for both MI > and "Locations" chapters of the manual. Thanks. > Questions/comments/concerns? Some: > +* GDB now allows users to specify explicit locations, bypassing > + the linespec parser. Feature also accessible from GDB/MI. Without an example, this entry doesn't really say anything specific about the new feature. Also, "Feature also accessible from GDB/MI." is too laconic, please make it a full sentence. > +Linespecs may be specified implicitly or explicitly. Implicit linespecs > +are parsed by the linespec parser and converted into a location. > +This often involves multiple searches through the program's symbol > +table. For large programs, this may be extremely time-consuming. > +Explicit linespecs avoid a lot of this searching by allowing the direct > +specification of file name, function, and/or other source location > +attributes. This is too implementation oriented, and thus not really appropriate for the user manual. The text should: . explain what is an explicit spec, in a way that clarifies why it is called "explicit" (so that users could make a mental note of that, which will facilitate remembering the terminology); . describe the fundamental difference between the explicit and implicit specs, and . explain in user-understandable terms the advantages and disadvantages of each kind (explicit and implicit) of specs. > +Explicit linespecs maybe be specified using the generalized form > +@samp{-option value}. The list of valid options is summarized in the ^^^^^^^^^^^^^^^^^^^^ ^^^^^^^ "@samp{-@var{option} @var{value}}", and "@var{options}", since these are not literal strings. > +@item @var{-function} @var is not the right markup here, since "-function" is a literal string. You want @code instead (here and elsewhere). > +The value specifies the name of a function for the location. This does not say what is the accepted form of a function. E.g., will "utils.c:vwarning" be accepted? > +@item @var{-label} > +The value specifies the name of a label for the location. Again, please specify the precise format that is accepted by this option. > + This option > +requires the use of at least one other explicit linespec option. This is good information, but OTOH the other options do not state which additional options, if any, they require. Should they? > +@item @var{-offset} > +The value specifies an offset for the location. This option may either be > +an absolute (@var{-offset 3}) or relative (@var{-offset +3}) offset. This needs to document the units in which the offset is specified, and what is the origin of the relative offsets. I would also suggest to emphasize the difference between "3" and "+3". As I wrote elsewhere, I would prefer -line to -offset, as this is more in line with other GDB features. > + [ -p @var{thread-id} ] [ @var{location} | @var{explicit_location}] I think the convention is to use '-', not '_', in these arguments. > +An @var{explicit_location} may be used instead of a @var{location} > +by supplying at least one of the following options: "By supplying at least one" is not accurate, as you yourself write: > +@item -s @var{filename} > +The source file name of the location. This option requires the use > +of at least one other explicit linespec option. Last, but not least: we should augment the doc strings of various commands that receive linespecs with some of this information. E.g., the "break" command. Thanks.