gdb/manual: Introduce location specs

The current "Specify Location" section of the GDB manual starts with:

 "Several @value{GDBN} commands accept arguments that specify a location
 of your program's code."

And then, such commands are documented as taking a "location"
argument.  For example, here's a representative subset:

 @item break @var{location}
 @item clear @var{location}
 @item until @var{location}
 @item list @var{location}
 @item edit @var{location}
 @itemx info line @var{location}
 @item info macros @var{location}
 @item trace @var{location}
 @item info scope @var{location}
 @item maint agent @r{[}-at @var{location}@r{,}@r{]} @var{expression}

The issue here is that "location" isn't really correct for most of
these commands.  Instead, the "location" argument is really a
placeholder that represent an umbrella term for all of the
"linespecs", "explicit location", and "address location" input
formats.  GDB parses these and then finds the actual code locations
(plural) in the program that match.  For example, a "location"
specified like "-function func" will actually match all the code
locations in the program that correspond to the address/file/lineno of
all the functions named "func" in all the loaded programs and shared
libraries of all the inferiors.  A location specified like "-function
func -label lab" matches all the addresses of C labels named "lab" in
all functions named "func".  Etc.

This means that several of the commands that claim they accept a
"location", actually end up working with multiple locations, and the
manual doesn't explain that all that well.  In some cases, the command
will work with all the resolved locations.  In other cases, the
command aborts with an error if the location specification resolves to
multiple locations in the program.  In other cases, GDB just
arbitrarily and silently picks whatever is the first resolved code
location (which sounds like should be improved).

To clarify this, I propose we use the term "Location Specification",
with shorthand "locaction spec", when we're talking about the user
input, the argument or arguments that is/are passed to commands to
instruct GDB how to find locations of interest.  This is distinct from
the actual code locations in the program, which are what GDB finds
based on the user-specified location spec.  Then use "location
specification or the shorter "location spec" thoughout instead of
"location" when we're talking about the user input.

Thus, this commit does the following:

- renames the "Specify Location" section of the manual to "Location
  Specifications".

- It then introduces the term "Location Specification", with
  corresponding shorthand "location spec", as something distinct from
  an actual code location in the program.  It explains what a concrete
  code location is.  It explains that a location specification may be
  incomplete, and that may match multiple code locations in the
  program, or no code location at all.  It gives examples.  Some
  pre-existing examples were moved from the "Set Breaks" section, and
  a few new ones that didn't exist yet were added.  I think it is
  better to have these centralized in this "Location Specification"
  section, since all the other commands that accept a location spec
  have an xref that points there.

- Goes through the manual, and where "@var{location}" was used for a
  command argument, updated it to say "@var{locspec}" instead.  At the
  same time, tweaks the description of the affected commands to
  describe what happens when the location spec resolves to more than
  one location.  Most commands just did not say anything about that.

  One command -- "maint agent -at @var{location}" -- currently says it
  accepts a "location", suggesting it can accept address and explicit
  locations too, but that's incorrect.  In reality, it only accepts
  linespecs, so fix it accordingly.

  One MI command -- "-trace-find line" -- currently says it accepts a
  "line specification", but it can accept address and explicit
  locations too, so fix it accordingly.

Special thanks goes to Eli Zaretskii for reviews and rewording
suggestions.

Change-Id: Ic42ad8565e79ca67bfebb22cbb4794ea816fd08b

1 files changed, 1 insertions, 1 deletions

diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
index 3c51723..63916ee 100644
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -1965,7 +1965,7 @@ This constant means that filename completion should be performed.
 
 @item COMPLETE_LOCATION
 This constant means that location completion should be done.
-@xref{Specify Location}.
+@xref{Location Specifications}.
 
 @item COMPLETE_COMMAND
 This constant means that completion should examine @value{GDBN}