RTe: Location Specs (Was: [pushed v5] gdb/manual: Introduce location specs)

[Eli Zaretskii <eliz@gnu.org>]

> Date: Mon, 30 May 2022 15:44:59 +0100
> Cc: gdb-patches@sourceware.org
> From: Pedro Alves <pedro@palves.net>
> 
> From: Pedro Alves <pedro@palves.net>
> Date: Tue, 17 May 2022 13:12:04 +0100
> Subject: [PATCH] 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."

I'd like to propose slight rewording and rearrangement of the section
which you modified with that commit.  Below please find: (a) the full
modified text of the section, and (b) diffs against the current master
branch.

WDYT?

----------------------------------------------------------------------
@node Location Specifications
@section Location Specifications
@cindex specifying location
@cindex locspec
@cindex source location
@cindex code location

@cindex location spec
Several @value{GDBN} commands accept arguments that specify a location
or locations of your program's code.  Since @value{GDBN} is a
source-level debugger, a location specification usually indicates some
line in some source file, but it can also do that indirectly, by
specifying a function name, an address, a label, etc.  The different
forms of specifying a location that @value{GDBN} recognizes are
collectively known as forms of @dfn{location specification}, or
@dfn{location spec}.  This section documents the forms of specifying
locations that @value{GDBN} recognizes.

@cindex location resolution
@cindex resolution of location spec
When you specify a location, @value{GDBN} needs to find the place in
your program, known as @dfn{code location}, that corresponds to the
given location spec.  We call this process of finding actual code
locations corresponding to a location spec @dfn{location resolution}.

A concrete code location in your program is uniquely identifiable by a
set of several attributes: its source line number, the name of its
source file, the fully-qualified and prototyped function in which it
is defined, and an instruction address.  Because each inferior has its
own address space, the inferior number is also a necessary part of
these attributes.  By contrast, location specs you type will many
times omit some of these attributes.  For example, it is customary to
specify just the source line number to mean a line in the current
source file, or specify just the basename of the file, omitting its
directories.  In other words, a location spec is usually incomplete, a
kind of blueprint, and @value{GDBN} needs to complete the missing
attributes by using the implied defaults, and by considering the
source code and the debug information available to it.  This is what
location resolution is about.

The resolution of an incomplete location spec can produce more than a
single code location, if the spec doesn't allow distinguishing between
them.  Here are some examples of situations that result in a location
spec matching multiple code locations in your program:

@itemize @bullet
@item
The location spec specifies a function name, and there are several
functions in the program which have that name.  (To distinguish
between them, you can specify a fully-qualified and prototyped
function name, such as @code{A::func(int)} instead of just
@code{func}.)

@item
The location spec specifies a source file name, and there are several
source files in the program that share the same name, for example
several files with the same basename in different subdirectories.  (To
distinguish between them, specify enough leading directories with the
file name.)

@item
For a C@t{++} constructor, the @value{NGCC} compiler generates several
instances of the function body, used in different cases, but their
source-level names are identical, unless you qualify them.

@item
For a C@t{++} template function, a given line in the function can
correspond to any number of instantiations.

@item
For an inlined function, a given source line can correspond to several
actual code locations with that function's inlined code.
@end itemize

Resolution of a location spec can also fail to produce a complete code
location, or even fail to produce any code location.  Here are some
examples of such situations:

@itemize @bullet
@item
Some parts of the program lack detailed enough debug info, so the
resolved code location lacks some attributes, like source file name
and line number, leaving just the instruction address and perhaps also
a function name.  Such an incomplete code location is only usable in
contexts that work with addresses and/or function names.  Some
commands can only work with complete code locations.

@item
The location spec specifies a function name, and there are no
functions in the program by that name, or they only exist in a
yet-unloaded shared library.

@item
The location spec specifies a source file name, and there are no
source files in the program by that name, or they only exist in a
yet-unloaded shared library.

@item
The location spec specifies both a source file name and a source line
number, and even though there are source files in the program that
match the file name, none of those files has the specified line
number.
@end itemize

Locations may be specified using three different formats: linespec
locations, explicit locations, or address locations.  The following
subsections describe these formats.

@menu
* Linespec Locations::                Linespec locations
* Explicit Locations::                Explicit locations
* Address Locations::                 Address locations
@end menu

----------------------------------------------------------------------

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 5f09f3a..3395735 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -9056,73 +9056,67 @@
 @node Location Specifications
 @section Location Specifications
 @cindex specifying location
-@cindex location spec
 @cindex locspec
 @cindex source location
 @cindex code location
 
+@cindex location spec
 Several @value{GDBN} commands accept arguments that specify a location
 or locations of your program's code.  Since @value{GDBN} is a
 source-level debugger, a location specification usually indicates some
-line in the source code, but it can also indicate a function name, an
-address, a label, and more.
+line in some source file, but it can also do that indirectly, by
+specifying a function name, an address, a label, etc.  The different
+forms of specifying a location that @value{GDBN} recognizes are
+collectively known as forms of @dfn{location specification}, or
+@dfn{location spec}.  This section documents the forms of specifying
+locations that @value{GDBN} recognizes.
+
+@cindex location resolution
+@cindex resolution of location spec
+When you specify a location, @value{GDBN} needs to find the place in
+your program, known as @dfn{code location}, that corresponds to the
+given location spec.  We call this process of finding actual code
+locations corresponding to a location spec @dfn{location resolution}.
 
 A concrete code location in your program is uniquely identifiable by a
-set of logical attributes.  A line number, the source file the line
-belongs to, the fully-qualified and prototyped function it is defined
-in, and an instruction address.  Because each inferior has its own
-address space, also an inferior number.  The source file attribute has
-as many directory components as possible, retrieved from the debug
-information, and in absolute form if possible, but it may also be in
-relative form.
-
-On the other hand, a @dfn{location specification} (a.k.a.@:
-@dfn{location spec}) is a way to find or refer to the concrete code
-locations in the program.  A location spec serves as a blueprint, and
-@value{GDBN} resolves the spec to actual code locations in your
-program by using the source and debug information.
-
-The location spec may be incomplete, and @value{GDBN} will do its best
-to find all the locations in the program that match it.
-
-For example, a location spec may just indicate a line number and a
-source filename with no directory components, or even not specify a
-filename at all, just a line number.  To differentiate between files
-with the same base name, the spec may prepend as many directories as
-is necessary to uniquely identify the desired file.
-
-Or, the spec may indicate a simple function name instead of a
-fully-qualified and prototyped function name (e.g., @code{func}
-instead of @code{A::func(int)}).  To differentiate between functions
-with the same name, the spec may prepend as many class and namespace
-names as is necessary to uniquely identify the desired function,
-and/or it may specify the function parameters as well.  In addition,
-the spec may indicate that the specified function name should be
-interpreted as a fully-qualified name.
-
-You may not have debug info for some of the instructions in the
-program, so a resolved code location that itself points to such code
-will be incomplete and be missing some attributes, such as the source
-file and line number, and sometimes even function names.  Such an
-incomplete code location is only usable in contexts that work with
-addresses and/or function names.  Some commands can only work with
-complete code locations.
-
-Here are examples of typical situations that result in a location spec
-matching multiple concrete code locations in your program:
+set of several attributes: its source line number, the name of its
+source file, the fully-qualified and prototyped function in which it
+is defined, and an instruction address.  Because each inferior has its
+own address space, the inferior number is also a necessary part of
+these attributes.  By contrast, location specs you type will many
+times omit some of these attributes.  For example, it is customary to
+specify just the source line number to mean a line in the current
+source file, or specify just the basename of the file, omitting its
+directories.  In other words, a location spec is usually incomplete, a
+kind of blueprint, and @value{GDBN} needs to complete the missing
+attributes by using the implied defaults, and by considering the
+source code and the debug information available to it.  This is what
+location resolution is about.
+
+The resolution of an incomplete location spec can produce more than a
+single code location, if the spec doesn't allow distinguishing between
+them.  Here are some examples of situations that result in a location
+spec matching multiple code locations in your program:
 
 @itemize @bullet
 @item
-The location spec specifies a function name, and multiple functions in
-the program may have the same name.
+The location spec specifies a function name, and there are several
+functions in the program which have that name.  (To distinguish
+between them, you can specify a fully-qualified and prototyped
+function name, such as @code{A::func(int)} instead of just
+@code{func}.)
 
 @item
-The location spec specifies a source file name, and multiple source
-files in the program share the same name.
+The location spec specifies a source file name, and there are several
+source files in the program that share the same name, for example
+several files with the same basename in different subdirectories.  (To
+distinguish between them, specify enough leading directories with the
+file name.)
 
 @item
 For a C@t{++} constructor, the @value{NGCC} compiler generates several
-instances of the function body, used in different cases.
+instances of the function body, used in different cases, but their
+source-level names are identical, unless you qualify them.
 
 @item
 For a C@t{++} template function, a given line in the function can
@@ -9130,21 +9124,30 @@
 
 @item
 For an inlined function, a given source line can correspond to several
-places where that function is inlined.
+actual code locations with that function's inlined code.
 @end itemize
 
-And here are examples of typical situations that result in a location
-spec matching no code locations in your program at all:
+Resolution of a location spec can also fail to produce a complete code
+location, or even fail to produce any code location.  Here are some
+examples of such situations:
 
 @itemize @bullet
 @item
+Some parts of the program lack detailed enough debug info, so the
+resolved code location lacks some attributes, like source file name
+and line number, leaving just the instruction address and perhaps also
+a function name.  Such an incomplete code location is only usable in
+contexts that work with addresses and/or function names.  Some
+commands can only work with complete code locations.
+
+@item
 The location spec specifies a function name, and there are no
-functions in the program with that name, or they only exist in a
+functions in the program by that name, or they only exist in a
 yet-unloaded shared library.
 
 @item
 The location spec specifies a source file name, and there are no
-source files in the program with that name, or they only exist in a
+source files in the program by that name, or they only exist in a
 yet-unloaded shared library.
 
 @item
@@ -9154,16 +9157,9 @@
 number.
 @end itemize
 
-The act of finding all the actual code locations that match the user
-input is called @dfn{resolving the location spec}.  The code locations
-that @value{GDBN} finds are the @dfn{resolved code locations}.
-
-If @value{GDBN} cannot find any code location that matches the user
-input, it is said that @value{GDBN} could not resolve the location
-spec.
-
 Locations may be specified using three different formats: linespec
-locations, explicit locations, or address locations.
+locations, explicit locations, or address locations.  The following
+subsections describe these formats.
 
 @menu
 * Linespec Locations::                Linespec locations