Re: [PATCH 2/5] gdb/doc: fix some incorrect '@table @code' uses

[Eli Zaretskii <eliz@gnu.org>]

> From: Andrew Burgess <aburgess@redhat.com>
> Cc: Andrew Burgess <aburgess@redhat.com>
> Date: Mon, 12 Oct 2026 19:54:27 +0100
> 
> When we have something like this:
> 
>   @table @code
>   @item blah
>   This is the text.
>   @end table
> 
> Then the 'blah' text is formatted as '@code{blah}'.  We have several
> places in the GDB docs where we use '@table @code' when there is a
> better alternative than @code.
> 
> I also found a few places where we did something like:
> 
>   @table @code
>   @item @code{blah}
>   This is the text.
>   @end table
> 
> In this case the @code around 'blah' is unnecessary, as the table
> already applies @code formatting.  In this case I've removed the
> formatting around the blah text.
> 
> I also spotted this pattern:
> 
>   @table @code
>   @item @var{blah}, some additional explanation.
>   This is the text.
>   @end table
> 
> In this case 'blah' is formatted as @var and 'some additional
> explanation' is formatted as @code, when I think it is really just
> normal text.  In this case I change the @code to @asis which will
> leave the additional text as-is, i.e. with no special formatting.
> 
> I have not tried to check every @table in the docs.  This patch mostly
> focused on @code to @kbd, though I did fix up a few other tables where
> it was obvious that something else should be applied.  However, there
> are a lot of tables in the docs, my strategy was to basically spend no
> more than a second or two looking at a table, if it wasn't immediately
> obvious what change was needed then I left the table as @code.  My
> hope is that this patch improves the quality of the docs.
> ---
>  gdb/doc/gdb.texinfo | 622 ++++++++++++++++++++++----------------------
>  gdb/doc/guile.texi  |   6 +-
>  gdb/doc/python.texi |  16 +-
>  3 files changed, 322 insertions(+), 322 deletions(-)

Thanks, this is okay.  I have a comments:

> -@table @code
> +@table @asis
>  @item @var{linenum}
>  @itemx @var{filename}:@var{linenum}
>  @itemx -line @var{linenum}

There's nothing wrong with having a @var inside @code, we do it in
many manuals all the time.  The problem happens when there are words
in such a table which should neither be in @code nor in @var; but
there are no such cases here, AFAICT.  OTOH, changing to @asis makes
the "@item -line" have the wrong typeface: it should be in @code.

So I would leave this case alone.

Approved-By: Eli Zaretskii <eliz@gnu.org>