From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 22672 invoked by alias); 22 Mar 2013 09:44: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 22600 invoked by uid 89); 22 Mar 2013 09:43:20 -0000 X-Spam-SWARE-Status: No, score=-3.6 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,SPF_SOFTFAIL autolearn=no version=3.3.1 Received: from mtaout22.012.net.il (HELO mtaout22.012.net.il) (80.179.55.172) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Fri, 22 Mar 2013 09:43:15 +0000 Received: from conversion-daemon.a-mtaout22.012.net.il by a-mtaout22.012.net.il (HyperSendmail v2007.08) id <0MK2003002YCDX00@a-mtaout22.012.net.il> for gdb-patches@sourceware.org; Fri, 22 Mar 2013 11:43:08 +0200 (IST) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout22.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MK20034N2ZVD620@a-mtaout22.012.net.il>; Fri, 22 Mar 2013 11:43:08 +0200 (IST) Date: Fri, 22 Mar 2013 09:46:00 -0000 From: Eli Zaretskii Subject: Re: [RFA 4/4 doc] Explicit locations In-reply-to: <514BA08F.4010305@redhat.com> To: Keith Seitz Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83620j6a8i.fsf@gnu.org> References: <514B9EC2.5060502@redhat.com> <514BA08F.4010305@redhat.com> X-SW-Source: 2013-03/txt/msg00832.txt.bz2 > Date: Thu, 21 Mar 2013 17:06:39 -0700 > From: Keith Seitz > > --- a/gdb/breakpoint.c > +++ b/gdb/breakpoint.c > @@ -15975,10 +15975,9 @@ command" [PROBE_MODIFIER] [LOCATION] [thread > THREADNUM] [if CONDITION]\n\ > PROBE_MODIFIER shall be present if the command is to be placed in a\n\ > probe point. Accepted values are `-probe' (for a generic, > automatically\n\ > guessed probe type) or `-probe-stap' (for a SystemTap probe).\n\ > -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, explicit, or address location. See \"help\n\ > +locations\" for more help with specifying locations.\n\ > +\n\ Why is it a good idea to remove the information about linespec and address methods of specifying locations? I would suggest to leave them alone, perhaps add a one-line summary for the new 'explicit' method, and leave the details to the new "help locations" doc string. You see, I think one of the nastiest annoyances in documentation is excessive reliance on cross-references. This is BA-A-A-D because it requires the reader to fish elsewhere for info necessary for what she wants to do, instead of giving that info right there and then. It is okay to use cross-references for _more_details_ on a subject, but the bare necessities should not IMO be deferred to some other node in the docs. > add_com ("clear", class_breakpoint, clear_command, _("\ > -Clear breakpoint at specified line or function.\n\ > -Argument may be line number, function name, or \"*\" and an address.\n\ > -If line number is specified, all breakpoints in that line are cleared.\n\ > -If function is specified, breakpoints at beginning of function are > cleared.\n\ > -If an address is specified, breakpoints at that address are cleared.\n\ > +Clear breakpoint at specified location.\n\ > +Argument may be a linespec, explicit, or address location. Seen\n\ > +\"help locations\" for more help with specifying locations.\n\ Same comment here. > Set a static tracepoint at specified line, function or marker.\n\ > \n\ > strace [LOCATION] [if CONDITION]\n\ > -LOCATION may be a line number, function name, \"*\" and an address,\n\ > -or -m MARKER_ID.\n\ > -If a line number is specified, probe the marker at start of code\n\ > -for that line. If a function is specified, probe the marker at start\n\ > -of code for that function. If an address is specified, probe the marker\n\ > -at that exact address. If a marker id is specified, probe the marker\n\ > +LOCATION may be a linespec, explicit, or address location or\n\ > +or -m MARKER_ID. See \"help locations\" for more help with specifying\n\ > +locations.\n\ And here. > c = add_com ("dprintf", class_breakpoint, dprintf_command, _("\ > -Set a dynamic printf at specified line or function.\n\ > +Set a dynamic printf at specified location.\n\ > dprintf location,format string,arg1,arg2,...\n\ > -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\ > -")); > +location may be a linespec, explicit, or address location. See \"help\n\ > +locations\" for more help with specifying locations.")); And here. > + add_com ("locations", help_class, NULL, > + _("GDB supports several ways to specify locations. Any place\n\ The first line of a doc string should be a single full sentence, suitable to serve as a summary of the feature. That line is shown by commands like "apropos", so it should be legible by itself. I suggest Different forms of specifying locations supported by GDB. > + EXPLICIT LOCATIONS bypass the linespec parser, allowing the user to\n\ Why do we need to talk about the "linespec parser" in user documentation? For that matter, how is it useful for the user to know that EXPLICIT bypasses something? It's just an alternative method of specifying a location, so it should be described as such, in the same format you used for the other 2. > + Parsing linespecs often involves multiple searches through the > program's\n\ > + symbol table or the file system. For large programs, this may be\n\ > + extremely time-consuming. Explicit locations may help avoid a lot of\n\ > + this unnecessary searching.\n\ I suggest to make this user-oriented, something like Explicit locations are useful when several functions, labels, or file names have the same name (base name for files) in the program's sources. In these cases, explicit locations point to the source line you meant more accurately and unequivocally. Also, using explicit locations might be faster in large programs. On the other hand, using explicit locations means more typing. On second thought, this whole merits/demerits thing probably belongs to the manual, not to a doc string. > diff --git a/gdb/cli/cli-decode.c b/gdb/cli/cli-decode.c > index 61a7b5a..95b55c1 100644 > --- a/gdb/cli/cli-decode.c > +++ b/gdb/cli/cli-decode.c > @@ -948,7 +948,8 @@ help_cmd (char *arg, struct ui_file *stream) > fputs_filtered (c->doc, stream); > fputs_filtered ("\n", stream); > > - if (c->prefixlist == 0 && c->func != NULL) > + if ((c->prefixlist == 0 && c->func != NULL) > + || c->class == help_class) > return; > fprintf_filtered (stream, "\n"); > > @@ -1161,7 +1162,8 @@ help_cmd_list (struct cmd_list_element *list, enum > command_class class, > > for (c = list; c; c = c->next) > { > - if (c->abbrev_flag == 0 > + if (c->class != help_class > + && c->abbrev_flag == 0 > && (class == all_commands > || (class == all_classes && c->func == NULL) > || (class == c->class && c->func != NULL))) > diff --git a/gdb/command.h b/gdb/command.h > index 81edc43..777e847 100644 > --- a/gdb/command.h > +++ b/gdb/command.h > @@ -33,7 +33,8 @@ > enum command_class > { > /* Special args to help_list */ > - class_deprecated = -3, all_classes = -2, all_commands = -1, > + class_deprecated = -4, help_class = -3, all_classes = -2, > + all_commands = -1, > /* Classes of commands */ > no_class = -1, class_run = 0, class_vars, class_stack, class_files, > class_support, class_info, class_breakpoint, class_trace, These parts don't belong to documentation. > @@ -6970,15 +6970,21 @@ As described in the preceding table. > > Several @value{GDBN} commands accept arguments that specify a location > of your program's code. Since @value{GDBN} is a source-level > -debugger, a location usually specifies some line in the source code; > -for that reason, locations are also known as @dfn{linespecs}. > +debugger, a location usually specifies some line in the source code. > +Locations may be specified using three different formats, > +linespec locations, explicit locations, or address locations. > > -Here are all the different ways of specifying a code location that > -@value{GDBN} understands: > +@node Linespec Locations > +@subsection Linespec Locations Did you actually try to build the manual after these changes? I think it won't build, because you introduced new nodes that don't appear in any menu in their parent node, which makes them "orphans", and makeinfo will barf. Anyway, I don't think we want additional sub-nodes here. The "Specify Location" node is not large; adding the new explicit locations to it will still not make it much longer. Just add the new stuff there. > + > +A @dfn{linespec} is a colon-separated list of source location > parameters such > +as file name, function name, etc. They are parsed and converted into an > +internal representation used by @value{GDBN}. I would omit the last sentence, it does not add any useful information for GDB users. > @table @code > @item @var{linenum} > -Specifies the line number @var{linenum} of the current source file. > +Specifies the line number @var{linenum} of the @dfn{current source} file. I don't necessarily object, but I see no special reason to put "current source" in @dfn, as it is not some terminology that needs explanation, nor is it actually explained in the text. (By contrast, "current line" does need an explanation, which is given in the text.) > +@dfn{Explict locations} bypass the linespec parser, allowing the user > +to explicitly specify the source location's parameters. As mentioned earlier, the issue of parsing and bypassing it does not add any useful information here, so I'd omit it. > +Parsing linespecs often involves multiple searches through the program's > +symbol table or the file system. For large programs, this may be extremely > +time-consuming. Explicit locations may help avoid a lot of this > +unnecessary searching. > + > +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 symbol table to know. I would reword this, similar to what I suggested above for the doc string. > +@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? > +@item -function > +The value specifies the name of a function. Operations > +on function locations unmodified by other options (such as @code{-label} > +or @code{-line}) affect the line that begins the body of the function. ^^^^^^ "Affect" or "specify" or "refer"? If the former, what does "affect" mean? > +@item -line > +The value specifies a line offset for the location. The offset may either > +be absolute (@code{-line 3}) or relative (@code{-line +3}), depending on > +the command. When specified without any other options, the line offset is > +relative to the current function. The last sentence seems to describe an unexpected (for me) behavior: usually, I'd expect "line +3" to specify an offset from the current _line_, not current function. > -Here @var{address} may be any expression valid in the current working > +@var{address} may be any expression valid in the current working That "Here" was there for a reason: "address" starts with a lower-case letter, which is inappropriate in the first word of a sentence. (In the Info manual, @var causes its argument be up-cased, but in the printed manual @var switches to a slant typeface and does not up-case, so the sentence will look incorrect.) > +@item explicit location > +An explicit location. @sc{gdb/mi} explicit locations are > +analogous to @value{GDBN}'s explicit locations using the option names I don't think we want to contrast GDB with GDB/MI, as the latter is part of the former. I think you need to use CLI instead of @value{GDBN} here. > +listed below. @xref{Explicit Locations}. ^^ Two spaces here, please.