Re: [PATCH v3 2/5] DWARF-5: .debug_names index producer

[Eli Zaretskii <eliz@gnu.org>]

> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Cc: Victor Leschuk <vleschuk@accesssoftek.com>
> Date: Mon, 19 Jun 2017 22:55:44 +0200
> 
>  @table @code
> -@item save gdb-index @var{directory}
> +@item save gdb-index [-dwarf-4] @var{directory}
>  @kindex save gdb-index
>  Create an index file for each symbol file currently known by
>  @value{GDBN}.  Each file is named after its corresponding symbol file,
> -with @samp{.gdb-index} appended, and is written into the given
> -@var{directory}.
> +with @samp{.debug_names} and @samp{.str} (or @samp{.gdb-index}
> +from @code{-dwarf-4} option for older index consumers) appended, and is written
> +into the given @var{directory}.

The file-name extensions are better put in @file.

More importantly, this text is now confusing: what do you mean by
"with @samp{.debug_names} and @samp{.str}"?  Do we produce one file or
two?  If only one, then what determines whether its extension will be
.debug_names or .str?

Once I understand this, I could suggest an alternative wording to
clarify the issue.

>  This section documents the index section that is created by @code{save
> -gdb-index} (@pxref{Index Files}).  The index section is
> +gdb-index -dwarf-4} (@pxref{Index Files}).  Currently preferred section is

The command should be in @kbd, not @code, as it's something the user
types on the keyboard.

> +@code{.debug_names} as produced by the default @code{save gdb-index} command.
> +@code{.debug_names} section is documented in official @code{DWARF-5}

DWARF-5 should not be in @code.  Maybe in @acronym, or even no markup
at all.

>    c = add_cmd ("gdb-index", class_files, save_gdb_index_command,
>  	       _("\
>  Save a gdb-index file.\n\
> -Usage: save gdb-index DIRECTORY"),
> +Usage: save gdb-index [-dwarf-4] DIRECTORY"),
>  	       &save_cmdlist);

I think we should have a short explanation how the -dwarf-4 option
changes the behavior.

Thanks.