Re: [PATCH] gdb.texinfo: Expand documentation for debuginfod

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 30 Apr 2021 19:50:48 -0400
> From: Aaron Merey via Gdb-patches <gdb-patches@sourceware.org>
> 
> Add section describing GDB's usage of debuginfod.
> 
> Refer to this new section in the description of the '--with-debuginfod'
> configure option.
> 
> Mention debuginfod in the 'Separate Debug Files' section.
> 
> gdb/doc/ChangeLog:
> 
> 	* gdb.texinfo (Debuginfod): New section.
> 	(Configure Options): Refer to debuginfod section.
> 	(Separate Debug Files): Mention debuginfod.

Thanks, some comments below.

> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -184,6 +184,7 @@ software in general.  We will miss him.
>                                   the operating system
>  * Trace File Format::		GDB trace file format
>  * Index Section Format::        .gdb_index section format
> +* Debuginfod::			Download debugging resources with debuginfod

Please don't use TAB characters in Texinfo sources; use spaces
instead.

> -hex characters, not 10.)
> +hex characters, not 10.) @value{GDBN} can automatically query
> +debuginfod servers using build IDs in order to download separate debug
> +files that cannot be found locally. For more information see
> +@ref{Debuginfod}.

Please leave 2 spaces between sentences, here and elsewhere in your
patch.  We use US English conventions and spelling.

> +If the debug file still has not been found and debuginfod is enabled,
> +@value{GDBN} will attempt to download the file from debuginfod servers.

Please add here a cross-reference to the node which describes
debuginfod (preferably @pxref in parentheses after "debuginfod"), so
that the readers could easily find the relevant information.

Also, I wonder whether "debuginfod" should be in @code everywhere
(except in cross-references and the node name), since I believe we use
that markup for other packages.

> +Used to automatically fetch ELF, DWARF and source files from debuginfod
> +servers using their associated build IDs.
                 ^^^^^
This "their" is ambiguous: it could refer to ELF/DWARF/source files,
or it could refer to debuginfod servers.  FWIW, I think the original
text is better in this regard.

>                                             Enabled by default if
> +libdebuginfod is installed and found at configure time. For more
> +information regarding debuginfod see @ref{Debuginfod}.

"libdebuginfod" should have the @file markup.

> +@node Debuginfod
> +@appendix Download debugging resources with Debuginfod

Please add here the "@cindex debuginfod" index entry.

> +Using the debuginfod client library, libdebuginfod, @value{GDBN} can
                                        ^^^^^^^^^^^^^
@file{libdebuginfod}

> +See @ref{Configure Options,,--with-debuginfod} for instructions on
   ^^^^^^^^
It's better to use @xref here instead of "See @ref".

> +building @value{GDBN} with libdebuginfod. Debuginfod is packaged with
> +elfutils, starting with version 0.178. See
   ^^^^^^^^
@code{elfutils}

> +`https://sourceware.org/elfutils/Debuginfod.html` for more information
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Please use @uref here instead of Markdown-like quoting.