[PATCH] gdb/manual: Introduce locspecs

[Pedro Alves]

On 2022-05-25 20:56, Eli Zaretskii wrote:
>> From: Pedro Alves <pedro@palves.net>
>> Date: Wed, 25 May 2022 20:31:26 +0100
>>
>> To clarify this, I propose we use the term "Location Specification",
>> with shorthand "locspec", 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
>> locations in the program, which are what GDB finds based on the
>> user-specified locspec.  Then use "locspec" thoughout instead of
>> "location" when we're talking about the user input.
> 
> Sorry, but I don't think this is a good idea.  It is IMO okay to
> introduce "location specification" into our terminology; it is even
> okay to use "location spec" as its shorthand.  But "locspec" is too
> much: it's not a word, so it doesn't explain itself enough, and thus
> cannot be used very far from where it is defined, because the reader
> will likely not understand what it means.

Yet, we have "linespec" and people understand it just fine, it's described
once in a single spot in the manual.  "locspec" just sounds novel now, but it won't be
novel anymore once we start using it.  It sounds like you are against any term that
is new just because it is new.  That just blocks progress forever.  It is not reasonable.
New shorthand names for for things that are referred very frequently should be fine
to invent.  Our users aren't dummies and they learn things.

> "Locspec" is fine to use in
> the likes of @var{locspec}, where we describe commands that take a
> location specification as an argument, but using it as a general term
> everywhere in the manual (and we have quite a lot of references to
> location specs, as several commands work in these terms) will make the
> manual more awkward to write (we will need a lot more references to
> where "locspec" is defined), 

No we wont.  Everywhere I used "locspec" already has a xref to where
it is defined...  Please give the patch a change and read it in more detail.

> and as result harder to read where these
> are mentioned, due to the need to actually go to that cross-referenced
> section.
> 
> As I suggested elsewhere, I think it would be a better idea to reserve
> the use of "location" only to these specifications, and use some other
> term (e.g., "address") for the actual "resolved" locations that are
> places in the program's code.  That will allow us to use "location" as
> a shorthand for "location specification", something that will
> inevitably happen anyway (people being what they are: we hate to type
> long phrases when we think a shorter one will do).  If we use
> "location" for two related but different concepts, this tendency will
> cause confusing text both in the manual and even in our discussions
> here on the list.

And I've already explained why that would be incorrect.  Please give it a read, here:

 https://sourceware.org/pipermail/gdb-patches/2022-May/189418.html

> 
> Or maybe there are other ideas to resolve this difficulty.  If someone
> has alternative proposals, please describe them, and let's discuss.
> 
> Thanks.
>