[RFA 5/5] Explicit linespecs - documentation

[Keith Seitz <keiths@redhat.com>]

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