Re: [PATCH 07/10] gdb: add qMachineId packet

[Andrew Burgess <aburgess@redhat.com>]

Eli Zaretskii <eliz@gnu.org> writes:

>> Cc: Andrew Burgess <aburgess@redhat.com>
>> Date: Wed, 16 Aug 2023 16:55:03 +0100
>> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
>> 
>> diff --git a/gdb/NEWS b/gdb/NEWS
>> index 9839330c46d..d83f097d937 100644
>> --- a/gdb/NEWS
>> +++ b/gdb/NEWS
>> @@ -272,6 +272,11 @@ qDefaultExecAndArgs
>>    which the server was started.  If no such information was given to
>>    the server then this is reflected in the reply.
>>  
>> +qMachineId
>> +  This packet returns an identifier that allows GDB to determine if
>> +  the remote server and GDB are running on the same host, and can see
>> +  the same filesystem.
>> +
>>  *** Changes in GDB 13
>
> This part is OK.
>
>> @@ -44748,6 +44749,49 @@
>>  Indicates an error was encountered.
>>  @end table
>>  
>> +@anchor{Machine-Id Packet}
>> +@item qMachineId
>> +@cindex query remote machine-id, remote request
>> +@cindex @samp{qMachineId} packet
>
> Please move the @cindex entries before the @item line, so that
> index-search in an Info reader lands you on the line corresponding to
> @item, not on the text after that.
>
>> +within a single reply.  See @ref{Machine-Id Details} for details of
>                                                        ^
> Comma there, please (it is needed for some older versions of Texinfo).

Thanks for the feedback, I'll get that fixed.

> Btw, when a sentence starts with "See @ref", you could simplify by
> using @xref, as that is its main purpose.

When generating the 'info' docs @xref doesn't add the 'See' prefix, but
when generating the pdf 'See' is added.  I guess this explains why 'See
@ref' is common throughout the GDB manual.

It seems strange the prefix is added in some contexts, but not in
others.  The info docs don't seem to read as clearly without the 'See'
prefix, so for me at least, @xref seems the worse choice.

My question is, what am I missing here?  I'm sure there's some logic
behind this difference, but I'm not seeing it.

Thanks,
Andrew