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

[Andrew Burgess <aburgess@redhat.com>]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Andrew Burgess <aburgess@redhat.com>
>> Cc: gdb-patches@sourceware.org
>> Date: Fri, 25 Aug 2023 15:49:00 +0100
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> > 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.
>
> No, @xref always produces "See".  Where did you see it without "See"?

Sorry Eli, I missed your reply here.

I am using GNU texinfo 6.7, and I don't see @xref adding "See" when
generating 'info' output format.  When producing 'pdf' output I do see
the "See" prefix.

This is visible to me in the current GDB info page(s).

For example, this paragraph in gdb.texinfo:

  If the architecture supports memory tagging, the @code{print} command will
  display pointer/memory tag mismatches if what is being printed is a pointer
  or reference type. @xref{Memory Tagging}.

Is rendered like this in 'info' format:

     If the architecture supports memory tagging, the 'print' command will
  display pointer/memory tag mismatches if what is being printed is a
  pointer or reference type.  *Note Memory Tagging::.

I guess it has the '*Note ' prefix instead, but in contrast, this
partial paragraph from gdb.texinfo:

  This command allows to control the information printed when
  the debugger prints a frame.  See @ref{Frames}, @ref{Backtrace},
  for a general explanation about frames and frame information.

Is rendered like this in 'info' format:

  This command allows to control the information printed when the
  debugger prints a frame.  See *note Frames::, *note Backtrace::,
  for a general explanation about frames and frame information.

Which I think is nicer, for me starting the sentence with 'Note' doesn't
seem as friendly.

Thanks,
Andrew