Re: [PATCH v4] gdb/manual: Introduce location specs

[Pedro Alves <pedro@palves.net>]

On 2022-05-27 20:00, Eli Zaretskii wrote:

> What I was talking about was not about using the location specs, it
> was about explaining what it is and how it differs from the code
> location.  I think we have to explain the terminology before we use
> it, since it is not entirely trivial.

OK, here's what I added on top of v4, locally.  WDYT?

From 97024e5cd68a1608287c28ea06693a3c18804474 Mon Sep 17 00:00:00 2001
From: Pedro Alves <pedro@palves.net>
Date: Fri, 27 May 2022 20:22:49 +0100
Subject: [PATCH] foo

Change-Id: I18ab66ae278767e2636aa76712e2d5c44ca6ee83
---
 gdb/doc/gdb.texinfo | 37 +++++++++++++++++++++++++++----------
 1 file changed, 27 insertions(+), 10 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 6deaad88d31..8f25f899263 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -9053,10 +9053,13 @@ line in the source code, but it can also indicate a function name, an
 address, a label, and more.
 
 A concrete code location in your program is uniquely identifiable by a
-set of logical attributes.  Typically, 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.
+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.@: location
 spec) is a way to find or refer to the concrete code locations in the
@@ -9065,12 +9068,22 @@ 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.  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 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 funnction,
+and/or it may specify the function parameters as well.  In addition,
+the spec may indicate that the 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 location that itself points to such code will
@@ -9105,6 +9118,10 @@ For an inlined function, a given source line can correspond to several
 places where that function is inlined.
 @end itemize
 
+The act of finding all the actual code location 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}.
+
 Locations may be specified using three different formats: linespec
 locations, explicit locations, or address locations.
 

-- 
2.36.0