[RFA 5/5] Explicit linespecs - documentation

[RFA 5/5] Explicit linespecs - documentation

[Keith Seitz]

Hi,

The patch below adds documentation for explicit linespecs for both MI 
and "Locations" chapters of the manual.

Questions/comments/concerns?
Keith

ChangeLog
2012-07-26  Keith Seitz  <keiths@redhat.com>

	* NEWS: Mention new explicit linespec feature.

doc/ChangeLog
2012-07-26  Keith Seitz  <keiths@redhat.com>

	* gdb.texinfo (Specifying a Location): Describe explicit
	linespecs.
	(GDB/MI Breakpoint Commands): Likewise for -break-insert.

diff --git a/gdb/NEWS b/gdb/NEWS
index a590bee..09c2403 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -19,6 +19,9 @@ maint info bfds

  *** Changes in GDB 7.5

+* GDB now allows users to specify explicit locations, bypassing
+  the linespec parser.  Feature also accessible from GDB/MI.
+
  * GDB now supports x32 ABI.  Visit <http://sites.google.com/site/x32abi/>
    for more x32 ABI info.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index facca8f..e0c3792 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -6760,7 +6760,16 @@ 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}.

-Here are all the different ways of specifying a code location that
+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.
+
+Here are all the different ways of specifying an implicit code location 
that
  @value{GDBN} understands:

  @table @code
@@ -6858,6 +6867,32 @@ each one of those probes.

  @end table

+Explicit linespecs maybe be specified using the generalized form
+@samp{-option value}.  The list of valid options is summarized in the
+following table:
+
+@table @code
+@item @var{-source}
+The value specifies the source filename for the location.  This option
+requires the use of at least one other explicit linespec option.
+
+@item @var{-function}
+The value specifies the name of a function for the location.
+
+@item @var{-label}
+The value specifies the name of a label for the location.
+
+@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.
+
+@item @var{-address}
+The value specifies any valid code address in the program.  This option
+may not be used with any other option.
+@end table
+
+Explicit linespec options may be abbreviated by omitting any non-unique
+trailing characters from the option name, e.g., @code{break -func main 
-o 3}.

  @node Edit
  @section Editing Source Files
@@ -28088,7 +28123,8 @@ N.A.
  @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} | @var{explicit_location}]
+
  @end smallexample

  @noindent
@@ -28104,6 +28140,28 @@ If specified, @var{location}, can be one of:
  @item *address
  @end itemize

+@noindent
+An @var{explicit_location} may be used instead of a @var{location}
+by supplying at least one of the following options:
+
+@table @samp
+@item -s @var{filename}
+The source file name of the location.  This option requires the use
+of at least one other explicit linespec option.
+
+@item -m @var{function}
+The name of a function.
+
+@item -l @var{label}
+The name of a label.
+
+@item -o @var{offset}
+An absolute or relative offset from the start of the location.
+
+@item -e @var{address}
+A code address of the program.
+@end table
+
  The possible optional parameters of this command are:

  @table @samp

Re: [RFA 5/5] Explicit linespecs - documentation

[Eli Zaretskii]

> Date: Thu, 26 Jul 2012 20:49:59 -0700
> From: Keith Seitz <keiths@redhat.com>
> 
> 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.

Re: [RFA 5/5] Explicit linespecs - documentation

[Pedro Alves]

On 07/27/2012 12:23 PM, Eli Zaretskii wrote:
> 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);

Or maybe (shocking suggestion follows), not even calling
"explicit linespecs" "linespecs" at all.  IOW, you either use linespecs,
or explicit locations.

-- 
Pedro Alves

Re: [RFA 5/5] Explicit linespecs - documentation

[Eli Zaretskii]

> Date: Wed, 01 Aug 2012 11:20:54 +0100
> From: Pedro Alves <palves@redhat.com>
> CC: Keith Seitz <keiths@redhat.com>, gdb-patches@sourceware.org
> 
> On 07/27/2012 12:23 PM, Eli Zaretskii wrote:
> > 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);
> 
> Or maybe (shocking suggestion follows), not even calling
> "explicit linespecs" "linespecs" at all.  IOW, you either use linespecs,
> or explicit locations.

Not shocking at all, at least not for me.  I could go with "explicit
locations".  We still need to say at least something to explain what's
the "explicit" part doing there.