[RFA 4/4 doc] Explicit locations

Eli Zaretskii eliz@gnu.org
Fri Mar 22 09:46:00 GMT 2013


> Date: Thu, 21 Mar 2013 17:06:39 -0700
> From: Keith Seitz <keiths@redhat.com>
> 
> --- 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.



More information about the Gdb-patches mailing list